partage/outils_redaction
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
outils_redaction/document2_0.md
François Pelletier a9a52e4fd0 améliorations depuis Windows
2017-12-05 16:43:59 -05:00

9.8 KiB
Raw Permalink Blame History

title author date
Le document 2.0 François Pelletier 7 décembre 2017

Bienvenue !!!

Objectifs de cet atelier:

  1. Partager ma méthode de travail pour créer des documents
  2. Présenter une méthodologie de travail axée sur le minimalisme
  3. Présenter les avantages de travailler avec des formats ouverts et des outils libres

Ordre du jour

  1. La syntaxe Markdown
  2. Les thèmes Bootstrap
  3. L'outil de conversion de documents Pandoc

Markdown

  • Markdown est une syntaxe simple pour écrire des textes et de la documentation.
  • C'est un langage de balisage léger, beaucoup plus simple que le HTML et le LaTeX.
  • Cette syntaxe permet la création de documents source lisibles par l'humain.
  • Elle est inspirée de plusieurs notations utilisées dans les courriels avant l'utilisation massive du HTML.
  • La documentation complète de Markdown tient dans une seule page: cheat sheet

Conversion du Markdown

Markdown est concu pour être converti en d'autres formats facilement:

  • HTML: Site web prêt à mettre en ligne)
  • PDF: Documents imprimables et diapositives.
  • LaTeX: Documents scientifiques et publications professionnelles
  • ODT: Format ouvert de document pour le traitement de texte utilisé par LibreOffice, OpenOffice, Google Docs. Assure la pérennité de l'information
  • Office Open XML (fichiers .docx): Format commun de bureautique (très mauvaise compatibilité)
  • MediaWiki: Syntaxe de documentation collaborative, utilisée par Wikipédia et autres

Les saveurs de Markdown

Attention: Il n'existe pas de standard de Markdown

  • Il y a par contre peu de différences entre celles-ci, ce sont surtout des ajouts pour des besoins précis

Quelques saveurs:

  • GitHub: Utilisée sur ce réseau social pour développeurs
  • R Markdown: Utilisé pour créer des rapports statistiques très élégants (C'est ce qu'on utilise dans mon équipe)
  • Pandoc Markdown: Utile pour créer des documents riches dans plusieurs formats de façon automatisée.

La syntaxe

La documentation de la syntaxe Markdown peut facilement être trouvée en ligne. Une version française se trouve ici:

Quel éditeur utiliser?

  • Pour les minimalistes, le bloc-notes de Windows peut amplement suffire.
  • Plusieurs éditeurs de code permettent d'utiliser Markdown plus aisément:
    • Atom
    • Visual Studio Code
    • Remarkable
    • RStudio

Atom

Atom: Éditeur de texte pour le 21e siècle!

Capture d'écran d'Atom

Visual Studio

Visual Studio Code est un éditeur libre, moderne et tres performant développé par la communauté et Microsoft.

Capture d'écran de Visual Studio

Je recommande Visual Studio Code. Il est disponible sur tous les environnements de bureau et existe aussi en version portable afin de contourner les restrictions d'entreprise.

Remarkable

Remarkable est un éditeur simple et convivial pour la syntaxe Markdown

Remarkable sur GitHub

Capture d'écran de Remarkable

RStudio

RStudio est d'abord un environnement de développement intégré (IDE) pour le langage statistique R, mais il est aussi un excellent éditeur markdown. Il supporte aussi sa propre syntaxe RMarkdown pour la production de rapports statistiques et de documents interactifs.

RStudio RMarkdown

Bootstrap

Bootstrap est un module qui permet d'utiliser des consignes de formatages faciles à interpréter par le navigateur. Il utilise le CSS (Cascading Style Sheet) pour créer des thèmes personnalisés et interchangeables. Créer un thème bootstrap requiert une connaissance du HTML et du CSS, mais les utiliser est plutôt simple.

Bootswatch

Bootswatch est un site web qui propose des thèmes gratuits pour Bootstrap.

Capture du site web bootswatch.com démontrant 6 thèmes

Pandoc

Pandoc est un outil et une librairie écrit en Haskell qui permet de convertir des documents entre plusieurs formats ouverts.

Il y a aussi une librairie très utilisée par plusieurs autres logiciels. Si votre éditeur permet d'exporter votre travail dans une multitude de formats, c'est probablement grâce à Pandoc.

Pandoc est multi-plateformes, mais certaines fonctionnalités peuvent être limitées. Par exemple, il faut avoir Microsoft Word ou LibreOffice pour produire des .docx.

Installation

Windows

Cette configuration permet l'utilisation portable depuis une clé USB ou un disque réseau sans avoir les droits administrateur. C'est ce que j'utilise au bureau.

  • Installer le fichier pandoc-2.0.3-windows.zip depuis cette page
  • Installer MikTeX Portable au besoin (pour faire des PDF) depuis cette page

MacOS

Installer depuis homebrew:

brew install pandoc

Sinon:

  • Installer le fichier pandoc-2.0.3-macOS.pkg depuis cette page
  • Installer BasicTeX avec le fichier BasicTeX.pkg depuis cette page

Linux

  • Debian, Ubuntu, ...
sudo apt-get install pandoc texlive-base
  • RedHat, ...
sudo yum install pandoc

(RedHat n'ont pas TeX Live dans les dépots):

  • Télécharger manuellement en suivant les instructions ici

Pandoc: Formats d'entrée

Les formats d'entrée incluent:

  • markdown
  • DocBook
  • LaTeX
  • OpenDocument
  • Epub
  • ...

Pandoc: Formats de sortie

Les formats de sortie incliuent:

  • HTML/CSS/JavaScript (HTML5, Slidy, RevealJS)
  • OpenDocument
  • EPub
  • DocBook
  • LaTeX
  • PDF
  • Markdown
  • MediaWiki
  • DokuWiki

Pandoc Markdown

Le Pandoc Markdown est un des formats d'entrée les plus versatiles. Il s'agit d'une variante de Markdown supportant plusieurs fonctionnalités additionnelles.

Référence: Anthoring Pandoc Markdown

Pandoc Markdown: Blocs de lignes

Les blocs de lignes permettent de séparer le texte manuellement. Par exemple, pour les adresses:

Code:

| Desjardins Groupe d'Assurance Générales
|
| 6300 Boul. Guillaume Couture
| Lévis, QC G6V 6P9

Résultat:

| Desjardins Groupe d'Assurance Générales | | 6300 Boul. Guillaume Couture | Lévis, QC G6V 6P9

Pandoc Markdown: Tables simples

Il faut spécifier l'extension +simple_tables

Code:

| Droite  | Gauche | Centre | Defaut |
| -----:  | :----- | :----: | ------ |
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |

Table:  Demonstration de la syntaxe des tables simples.

Résultat:

Droite Gauche Centre Defaut
12 12 12 12
123 123 123 123

Table: Demonstration de la syntaxe des tables simples.

Pandoc Markdown: métadonnées

Les métadonnées permettent d'identifier le titre, l'auteur et la date dans l'entête du document. On utilise l'extension +pandoc_title_block

Code:

---
title: "Le document 2.0"
author: "François Pelletier"
date: "7 décembre 2017"
---

Pandoc Markdown: mathématiques

Pandoc permet de traiter les équations mathématiques saisies avec la syntaxe LaTeX à l'aide de différents outils tout dépendamment du format de document en sortie.

Les principaux outils utilisés sont MathML, MathJaX et AMS LaTeX

Pandoc Markdown: mathématiques

On saisis les contenus mathématiques entre signes $ ou $$ pour les expressions multilignes.

Code:

$$
{\begin{aligned}
&\gamma _{ij}(x,t) \\ 
=&\sum _{k=1}^{N}\sigma _{ik}(x,t)\sigma _{jk}(x,t)
\end{aligned}}
$$

Résultat:

$$ {\begin{aligned} &\gamma _{ij}(x,t) \ =&\sum _{k=1}^{N}\sigma _{ik}(x,t)\sigma _{jk}(x,t) \end{aligned}}

Produire des présentations facilement

Un exemple: cette présentation a été écrite avec le langage Markdown et exportée en PDF et en HTML avec Pandoc.

#!/bin/bash
pandoc -f markdown+simple_tables+pandoc_title_block \
  -t html document2_0.md -o document2_0.html --template template.html \
  --css template.css --mathjax --toc --toc-depth 2

pandoc -f markdown+simple_tables+pandoc_title_block \
  -t slidy document2_0.md -o document2_0_slidy.html \
  --css template.css --mathjax --toc --toc-depth 3

Publier sur un wiki ou un site web

Il est aussi possible d'exporter le contenu d'un document vers la syntaxe dokuwiki, ce qui peut être très utile !

#!/bin/bash
pandoc -f markdown+simple_tables+pandoc_title_block \
 -t dokuwiki -s presentation.md -o presentation.dokuwiki

Références