Introduction
Lors de la SAÉ
S.303 vous allez devoir documenter vos travaux
- en rédigeant des procédures de mise en place
- en rédigeant des comptes-rendus des séances
d’autonomie
Ce travail devra obligatoirement être fait
- via des fichiers textes au format Markdown
- gérés dans un dépôt Git
Lors des premières séances d’autonomie vous devez
- vous documenter sur le fonctionnement de ces
outils
- vous familiariser à leur usage
La qualité de cette documentation sera une partie
importante de la note
Ce document vous donne quelques bases et des liens pour vous
aider
Il est disponible en
Outils
- Markdown
est un langage de balisage simple
- facile à lire et écrire par les humains et les programmes
- qui permet de transformer un fichier balisé vers HTML ou PDF
automatiquement
- dont il existe plusieurs variantes
- Pandoc est un
logiciel de conversion de documents
- il permet de convertir des fichiers d’un format de balisage à un
autre
- markup.rocks permet de manipuler
du texte directement via Pandoc
- Git est un outil
de contrôle de version distribué qui permet
- de suivre l’historique des modifications d’un ensemble de
fichiers
- de gérer des versions différentes en parallèle
- de travailler à plusieurs sur les mêmes fichiers
- de mettre en place des modes de collaborations différents
Markdown
Syntaxe générale
La syntaxe de Markdown permet
de donner une structure au document
- paragraphes : séparation par des lignes vides
- titres de différents niveaux : lignes débutant par
des
#
- listes libres : indentation de paragraphe avec
lignes débutant par des
- ou des *
- listes ordonnées : indentation avec lignes débutant
par des
1.
- blocs de citations : paragraphes préfixés par
“
>”
- blocs de codes : paragraphes indentés par 4
espaces
d’inclure des éléments de mise en forme
logique
emphase, accentuation forte et
code
d’inclure des liens vers des URL
Elle est décrite en détails ailleurs (cf liens de cette diapo)
Images
{ width=50% }
Texte alternatif pour HTML
Tableaux
- Plusieurs supports de tableaux accessibles via le Markdown de pandoc
- Celui utilisé par Gitlab et GitHub est très basique
- défini par
pipe_tables dans pandoc
pandoc |
conversion de formats |
pdflatex |
composition de LaTeX en PDF |
beamer |
jeux de balisage LaTeX pour la composition de présentation |
Code source
Le code source peut être coloré en fonction de la syntaxe du
language
#include <stdio.h>
int main(int argc, char ** argv) {
printf("Hello world !\n");
}
pandoc
- Pandoc est un logiciel de
conversion de documents
- il permet de convertir des fichiers d’un format de balisage à un
autre
- il définit une extension de Markdown : Pandoc’s
Markdown
- Options importantes
-f : format du fichier de départ-t : format du fichier de sortie-o : nom du fichier de sortie
- Plus de détails
Liens
Pour aller plus loin
Markdown
Git