title

subtitle

lang

author

Introduction

Traditionnellement, les outils d'édition de rapport privilégiés des étudiants sont Microsoft Word ou LibreOffice Writer. D'aucuns, plus courageux, se lancent dans \LaTeX à l'aide d'un éditeur riche comme LyX ou, l'éditeur en ligne qu'est ShareLaTeX.

L'approche présentée ici se place entre ces deux univers. Markdown est un format très facile à prendre en main et intégrer dans un système de gestion de version. Pandoc offre lui une conversion vers PDF qui fonctionne sans prise de tête. Les limitations de Markdown vis-à-vis d'un éditeur riche impliquent de recourir à d'autres outils pour gérer la bibliographie ou les références.

À ma connaissance, cette approche a été utilisée pour le support du cours de troisième année Développement Web, ainsi que par d'anciens étudiants depuis diplômés.

Rapport technique

Selon les directives de l'école [@arc2017], les difficultés d'un rapport technique au niveau de sa structure sont de réaliser correctement les éléments suivants:

page de titre;
table des matières;
liste des figures, tableaux et/ou équations;
abstract, introduction et conclusion;
le fameux SPRI [@timbal1982communication], ou IMMRID (voir le glossaire);
ainsi que la bibliographie.

Parmi ces éléments, les gros morceaux requièrent un investissement conséquent en terme de rédaction. Mais également, un travail d'organisation et de documentation très fin. Si constituer une bibliographie via Zotero, BibDesk, ou autre, est relativement aisé; gérer les citations, références et formater le tout correctement peut être fastidieux. Tout comme documenter et référencer chaque figure (ou image), équation ou table de données. Et c'est en occultant que c'est un travail de groupe dont il faut également coordonner les diverses contributions.

Markdown

L'idée est de reposer sur un format de fichier textuel, similaire à HTML mais avec une syntaxe plus légère. Markdown est inspiré d'un formalisme apparu de facto dans les listes de diffusion d'e-mails.

Ce format semi-structuré est devenu au fil des ans le favori des geeks. HTML étant trop fastidieux, ils n'ont eu de cesse d'imaginer des alternatives pour permettre l'édition de pages web au plus grand nombre, notamment au travers des wikiwikiwebs (plus connus sous le nom de wikis), tel que Wikipedia.

"A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions."

-- John Gruber

<!-- ceci est un commentaire -->

# Titre 1
## Titre 2
### Titre 3
#### Titre 4
##### Titre 5
###### Titre 6

*emphase* ou _emphase_ (affiché en italique)

**forte emphase** ou __forte emphase__ (affiché en gras)


- liste
- non
- ordonnée


1. liste
2. ordonnée


liste

: de définition


[lien hypertext](https://example.org)

![texte alternatif](image.png)

> citation

    texte non-formaté

L'avantage à utiliser du texte est qu'il est aisé à versionner (svn, git, etc.) et qu'il sépare les tâches de rédaction et de mise en forme. Notre cerveau, en mode écriture, est ainsi libre dans sa créativité et ne s'occupe pas de la mise en page.

GitHub est un grand utilisateur du format Markdown et propose un guide utile à son apprentissage. En matière d'édition collaborative, HackMD.io propose un système proche de Google Docs.

Formules mathématiques

Il est même possible de faire des tables HTML et même des formules mathématiques grâce à MathJax.

$$-1 = e^{j \pi}$${#eq:minus-one}

Le format utilisé est celui de \LaTeX. Avec un signe dollar ($) pour une formule en ligne, par exemple $e^{j \pi}$. Et deux $$ pour une formule centrée sur sa propre ligne (telle que @eq:minus-one).

$$-1 = e^{j \pi}$$

Méta-données

Ce qu'il manque à Markdown est d'être capable de renseigner des informations à propos du contenu: des métadonnées. Le moyen de faire ceci est d'utiliser un prologue dans autre format, nommé YAML. Le prologue YAML est enfermé dans deux triple-tirets ---.

---
title: Mon titre
lang: fr
---

... mon rapport technique ...

Ici, nous avons renseigné des informations permettant de construire la page de titre du rapport, ainsi que d'appliquer les règles de formatage typographiques propre au français (fr).

Pandoc

Un logiciel très puissant issu du temps libre d'un certain John MacFarlane, professeur de psychologie à l'université de Berkeley, Californie. Supportant pléthore de formats différents, il est capable de les convertir de l'un à l'autre selon la table (@tbl:input-output).

entrée	sortie
docbook, docx, epub, html, \LaTeX, markdown, mediawiki, odt, rst, textile, twiki, ...	idem + beamer, dzslides, epub3, html5, pdf, revealjs, rtf, s5, slideous, slidy, ...

: formats d'entrée et de sortie. {#tbl:input-output}

La liste complète des options à disposition se trouve dans l'aide de la commande.

$ man pandoc

Alternatives et variantes

S'il est possible de tout faire avec Pandoc, un usage intermédiaire est envisageable où le squelette du rapport est réalisé avec \LaTeX et le contenu des différentes sections écrit en Markdown pour des raisons de simplicité. Un template pour la HES-SO a été créé par Marc Demierre et peut servir de base.

Sphinx est une bonne alternative si le but est de produire une documentation technique en lien avec un code source.

Installation

Se lancer dans la production de document PDF avec \LaTeX demande de télécharger la moitié d'Internet et peut être déroutant.

La suite des opérations est prévue pour fonctionner sous Ubuntu ainsi que Ubuntu sous Windows (aussi nommé WSL (Windows Subsystem for Linux) disponible sous Windows 10 via le Store). Elle a été testée dans l'environnement suivant:

$ lsb_release -a
Distributor ID: Ubuntu
Description:    Ubuntu 20.04 LTS
Release:        20.04
Codename:       focal

Depuis un terminal, installez quelques dépendances à l'aide d'apt.

$ sudo apt install \
    pandoc \
    texlive-fonts-extra \
    texlive-lang-english \
    texlive-lang-french \
    texlive-xetex \
    ttf-mscorefonts-installer

Quoi est quoi?

\ évite de tout avoir sur seule ligne, c'est une astuce pour mettre de longues commandes dans un fichier imprimable tel que celui-ci;
pandoc convertit des formats textes en d'autres, ici de Markdown vers \LaTeX;
texlive-fonts-extra plein de polices de caractères;
texlive-lang-english les bouts de code source seront en anglais;
texlive-lang-french notre contenu sera en français;
texlive-xetex un meilleur support des polices et de l'Unicode;
ttf-mscorefonts-installer pour ceux qui veulent utiliser les polices Windows (Comic Sans, Impact, ...).

Pandoc nightly

Les versions fournies avec Ubuntu Focal (20.04) peuvent être un peu vieilles. Une alternative est d'installer pandoc directement depuis GitHub.

$ pandoc -v
pandoc 2.5

$ sudo apt-get remove pandoc

$ wget https://github.com/jgm/pandoc/releases\
> /download/2.11.0.4/pandoc-2.11.0.4-1-amd64.deb

$ sudo dpkg -i pandoc-2.11.0.4-1-amd64.deb

$ pandoc -v
pandoc 2.11
...

Édition avec VS Code

L'éditeur de la société Microsoft VS Code permet via l'extension Remote WSL de travailler à l'intérieur de l'environnement GNU Linux (@fig:vscode). Hélas cette extension utilise du code propriétaire et ne peut fonctionner sous VSCodium.

{#fig:vscode}

Réalisation

Une fois le langage de description Markdown apprivoisé, il ne manque plus qu'à générer un document PDF. Nous y incluerons ensuite les éléments importants du rapport technique tels que la bibliographie, la table des matières, les références, et la page de titre.

Le B.a.-ba

À partir d'un document Markdown, ici nommé rapport.md, nous pouvons débuter la conversion.

$ pandoc rapport.md --to latex

Le contenu est transformé selon le formalisme latex, généralement écrit \LaTeX. Et seulement, le contenu. Le drapeau --standalone permet d'en faire un document complet comportant les entêtes et méta-données nécessaires.

$ pandoc rapport.md \
    --standalone \
    --to latex

La commande suivante le transformera, avec un peu de chance, en document PDF. Le moteur de rendu est à spécifier, ici \XeLaTeX.

$ pandoc rapport.md \
    --standalone \
    --to latex \
    --pdf-engine xelatex \
    --output rapport.pdf

Le détail de chaque drapeau:

--standalone ajoute les entête et pied au document. Sinon, seul le contenu est produit;
--to latex décrit que le format de sortie désiré est \LaTeX;
--pdf-engine xelatex pour un meilleur support des polices (OTF, TTF, etc.) et de l'Unicode (caractères accentués);
--output rapport.pdf le nom du fichier de sortie.

Page de titre

Markdown ne s'occupant que du contenu, il est nécessaire de passer par le prologue YAML du fichier pour renseigner les méta-données (données sur les données).

---
title: My awesome project
lang: en
author:
- Yoan Blanc <yoan@dosimple.ch>
- Marc Schaefer <marc.schaefer@he-arc.ch>
date: \today
pagesize: A4
---

Table des matières

Le format \LaTeX contient des macros (fonctions) permettant de produire une superbe table des matières. Son activation dans le prologue l'activera.

---
toc: true
toc-depth: 5
---

Mise en forme

Avec quelques options de base, il est déjà possible d'obtenir un résultat intéressant. Pour aller plus loin, s'intéresser au fonctionnement des templates \LaTeX devient indispensable.

---
fontsize: 12pt
documentclass: scrreprt
documentoptions: twoside
numbersections: true
---

Les styles de base tels que article, report et book ont leur pendant dans la bibliothèque Koma-Script avec scrartcl, scrreprt et scrbook. Koma est assez populaire car son rendu est de bonne facture.

Polices de caractères et couleurs

Les polices de caractères Microsoft (ttf-mscorefonts-installer) sont installées. Il est possible de s'en servir et de pouvoir ressembler à un document produit avec Microsoft Word.

---
colorlinks: blue
mainfont: Times New Roman
sansfont: Arial Black
monofont: Andale Mono
monofontoptions: Scale=0.8  # Pour ceux qui écrivent en Java
                            # c'est peut-être encore trop grand.
---

Sous GNU/Linux, les polices sont généralement installées dans /usr/share/fonts. Et apt permet d'en installer tout un tas d'autres de bonne facture via texlive-fonts-extra. La famille Linux Libertine est utilisée dans ce document.

Bibliographie avec citeproc

Le format \LaTeX possède un outil, ou de nombreux outils, permettant de gérer les bibliographies. citeproc en supporte plusieurs dont Bib\LaTeX, le format généralement utilisé avec \LaTeX.

---
bibliography: bibliographie.bib
---

Création de la référence [@arc2017].

NB: Pour qu'un élément apparaisse dans la bibliographie, il est nécessaire qu'il soit cité dans le corps du document.

$ pandoc rapport.md \
    --citeproc \
    ...

Un moyen simple de créer son fichier .bib (par exemple [@lst:bibliographie]) est d'utiliser un logiciel permettant de collecter les références bibliographiques tel que Zotero ou de les exporter via Google Scholar.

@article{arc2017,
  title={Communication I : le rapport technique},
  author={Perret, Michael and Raboud, Stéphane and Babey, Magali},
  year={2017}
}

Style de la bibliographie

Pandoc utilise le style dit Chicago [@webster2017chicago] car très populaire dans les sciences humaines. Il ne l'est pas forcément au sein des sciences de l'ingénierie.

Les styles de bibliographie sont nombreux et donc interchangeables d'une plateforme de publication à l'autre. CitationsStyles permet de décrire le format de la bibliographie et des citations. Vous trouverez des styles à choix sur le Zotero Style Repository. Le format francophone et le style ISO 690 sont recommandés par la HES-SO.

---
bibliography: README.bib
csl: iso690-author-date-fr.csl
---

Références avec pandoc-crossref

Dans un document scientifique, il est recommandé de numéroter et référencer toutes les figures, et tables de données. Une tâche qui est un peu fastidieuse. Elle devient presque aisée à l'aide d'un outil comme pandoc-crossref.

# Pandoc 2.5
$ wget https://github.com/lierdakil/pandoc-crossref/releases\
> /download/v0.3.4.2/linux-pandoc_2_7_3.tar.gz
$ tar xf linux-pandoc_2_7_3.tar.gz

# Pandoc 2.9.2.1
$ wget https://github.com/lierdakil/pandoc-crossref/releases\
> /download/v0.3.6.3/pandoc-crossref-Linux-2.9.2.1.tar.xz
$ tar xf pandoc-crossref-Linux_2.9.2.1.tar.xz

# Installation
$ sudo mv pandoc-crossref /usr/local/bin/
$ sudo mv pandoc-crossref.1 /usr/local/man/
$ sudo mandb

Il est important d'exécuter le filtre des références avant celui des citations.

$ pandoc rapport.md \
    --filter pandoc-crossref \
    --citeproc \
    ...

{#fig:clippy}

Un paragraphe décrivant l'illustration (@fig:id).

![légende](fichier.jpg){#fig:id}

En \LaTeX, afficher la table des figures se fait via \listoffigures, qui existe au sein du prologue avec lof (et lot pour \listoftables).

---
lof: true   # table des figures
lot: true   # liste des tableaux
---

ou, en \LaTeX directement pour contrôler leur place et/ou leur ordre dans le document.

\listoffigures

\listoftables

\listoflistings    # `lol` n'existe pas dans pandoc.

Les options sont expliquées dans la page manuelle de la commande elle-même.

$ pandoc-crossref --man

Étendre pandoc

Il est possible de modifier le format produit par pandoc à l'aide de filtres en Haskell (le langage de Pandoc), Lua (Pandoc 2) ou Python (pandoc-filters).

Exemple: les problèmes liés au français

La bibliothèque gérant les langues va nous fournir des corrections adaptées à la langue choisie. Comme nous écrivons en français, elle va, entre autres, ajouter un espace insécable devant certains éléments de ponctuation tels que le deux-points (:), le point-virgule (;). Et elle s'occupe également de modifier l'apostrophe, et les "guillemets". Choses qui ne sont pas désirées lorsqu'il s'agit de code source.

Le filtre (@lst:english) écrit en Lua change la langue utilisée dans les blocs de code. S'en servir est aussi simple qu'avec les autres filtres.

$ pandoc rapport.md \
    --lua-filter english.lua \
    --filter pandoc-crossref \
    --citeproc \
    ...

Sans ceci, tous les blocs de code source contenant ces éléments de ponctuation seraient cassés. C'est un usage très avancé, que les plus informaticiens d'entre vous sauront dompter.

local lang = 'en'

return {
  {
    Code = function(el)
      return pandoc.Span(el, pandoc.Attr("", {}, {lang = lang}))
    end,

    CodeBlock = function(el)
      return pandoc.Div(el, pandoc.Attr("", {}, {lang = lang}))
    end,
  }
}

Conclusion

Réaliser le rapport technique d'un projet de semestre, de diplôme, seul ou en groupe est un gros investissement en énergie. Il est parfois un élément du projet sous-estimé par les étudiants. Markdown est un format suffisamment simple pour permettre la prise de notes tout au long du projet. Il est possible d'en faire l'édition en ligne aisément voire même de collaborer en même temps sur un document.

Pandoc est ensuite la baguette magique transformant tout ceci en un document de bonne facture. L'avantage est d'être progressif dans le sens où on débute simplement sans se soucier de la mise en page future. Un document \LaTeX demande un investissement d'apprentissage relativement important même s'il permet beaucoup plus d'options. Et à l'inverse Microsoft Word est trop laxiste, n'imposant pas une structure forte dès le départ rendant les modifications futures complexes.

Le but de ce document est de servir de base pour correspondre aux attentes de la Haute-École ARC. Il est améliorable sous de nombreux aspects et reste suffisamment ouvert permettant ainsi un peu de créativité.

La source de ce document se trouve sur https://github.com/HE-Arc/rapport-technique. Faites-en bon usage!

Annexes {-}

Glossaire {-}

IMMRID

: Introduction, Matériel, Méthode, Résultats, Interprétation, et Discussion. Méthode de structuration adaptée à un projet de recherche.

\LaTeX

: Un langage de description destiné à la production de documents techniques et scientifiques. https://www.latex-project.org/

Lua

: Un langage de programmation léger et généralement embarqué pour étendre une application. https://www.lua.org/

Python

: Un langage de programmation impératif, facile, ludique, et populaire. https://python.org

SPRI

: Situation, Problème, Résolution, et Informations. Une méthode permettant structurer un plan de présentation et introduite par Louis Timbal-Duclaux.

WSL

: Windows Subsystem for Linux une plateforme permettant de faire fonctionner des logiciels GNU/Linux sur le système Windows sans passer par une machine virtuelle. https://docs.microsoft.com/en-us/windows/wsl/about

YAML

: YAML Ain't a Markup Language un format de description structuré n'étant pas XML. https://yaml.org

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rapport.md

rapport.md

Introduction

Rapport technique

Markdown

Formules mathématiques

Méta-données

Pandoc

Alternatives et variantes

Installation

Pandoc nightly

Édition avec VS Code

Réalisation

Le B.a.-ba

Page de titre

Table des matières

Mise en forme

Polices de caractères et couleurs

Bibliographie avec citeproc

Style de la bibliographie

Références avec pandoc-crossref

Étendre pandoc

Exemple: les problèmes liés au français

Conclusion

Annexes {-}

Glossaire {-}

Sources {-}

Files

rapport.md

Latest commit

History

rapport.md

File metadata and controls

Introduction

Rapport technique

Markdown

Formules mathématiques

Méta-données

Pandoc

Alternatives et variantes

Installation

Pandoc nightly

Édition avec VS Code

Réalisation

Le B.a.-ba

Page de titre

Table des matières

Mise en forme

Polices de caractères et couleurs

Bibliographie avec citeproc

Style de la bibliographie

Références avec pandoc-crossref

Étendre pandoc

Exemple: les problèmes liés au français

Conclusion

Annexes {-}

Glossaire {-}

Sources {-}