IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)

Vous êtes nouveau sur Developpez.com ? Créez votre compte ou connectez-vous afin de pouvoir participer !

Vous devez avoir un compte Developpez.com et être connecté pour pouvoir participer aux discussions.

Vous n'avez pas encore de compte Developpez.com ? Créez-en un en quelques instants, c'est entièrement gratuit !

Si vous disposez déjà d'un compte et qu'il est bien activé, connectez-vous à l'aide du formulaire ci-dessous.

Identifiez-vous
Identifiant
Mot de passe
Mot de passe oublié ?
Créer un compte

L'inscription est gratuite et ne vous prendra que quelques instants !

Je m'inscris !

Markdown vs LaTeX : quel outil utilisez-vous pour écrire la documentation de vos projets ?
Markdown serait plus performant mais ne peut pas transporter des données

Le , par Bill Fassinou

1.2KPARTAGES

10  0 
Quel outil utilisez-vous pour écrire la documentation de vos projets ? Vous avez forcément une préférence pour un outil donné, mais y en a-t-il un qui est plus performant que les autres ? Dans le lot d’outils qui existent, l’on retrouve Markdown et Latex. Pour les certains, Markdown est l’outil le plus performant pour écrire son document, mais pour d’autres, il présente des incohérences et ne peut pas transporter des données. Pour ces derniers, il faut choisir Latex à la place afin de fournir un travail correct. Voici certaines choses qu’ils disent dans leur argumentation.

Markdown est un langage de balisage léger créé en 2004 par John Gruber avec l'aide d'Aaron Swartz. L’objectif est de mettre à disposition un langage doté d’une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l'état sans donner l’impression d'avoir été balisé ou formaté par des instructions particulières. De l’autre côté, LaTeX est un langage, mais aussi un système de composition de documents. C’est une collection de macro-commandes qui cherchent à faciliter et à améliorer l'utilisation du « processeur de texte » TeX de Donald Knuth.

Pour Jeff Geerling, développeur Web et logiciel, Markdown est un excellent choix pour écrire son document. Selon lui, Markdown suffit dans 98 % pour mettre en place une documentation en bonne et due forme, ce qui lui donne un avantage considérable sur les alternatives qui existent. Il soutient que Markdown est essentiellement du texte simple que tout le monde peut apprendre à écrire en quelques secondes seulement, avec des fonctionnalités supplémentaires. De même, il cite aussi comme argument le fait qu’il existe une multitude de bibliothèques pour l’outil.


« Le fait que le plus petit dénominateur commun de Markdown soit “je peux écrire du texte simple”, associé au fait qu'il existe de très bonnes bibliothèques pour Markdown dans tous les langages imaginables, signifie qu’il est le moyen le plus simple dont vous disposez pour pouvoir écrire une documentation maintenable, quel que soit l'auteur qui contribue à votre base de code », a-t-il écrit. Selon lui, il est plus facile de modifier une documentation en texte clair qu’une autre écrite dans un format spécifique, moins populaire et nécessitant plus de spécificité.

Cependant, selon HIllel Wayne, un programmeur et conseillé en méthodes formelles, Markdown n’est pas du tout l’outil idéal pour écrire une bonne documentation. Selon lui, Markdown est tolérable pour écrire les documents courts, comme un readme.md. « En dehors de ça, ce n'est pas le bon outil pour le travail », a-t-il écrit. Markdown est juste une question de formatage, pas d'information, selon lui. Autrement dit, c’est juste une façon d’écrire du HTML plus simple et plus beau. Les gens l’utilisent parce qu’il est facile à apprendre.

En outre, il estime que les gens le choisissent parce qu’il est facile d'écrire une sorte d'analyseur Markdown dans n'importe quel langage de programmation. Pour lui, Markdown ne peut pas transporter des données. Il n’existe aucun moyen d'intégrer des propriétés dans un texte en utilisant Markdown. Il estime qu’une bonne documentation n’est pas une question de formatage, mais elle concerne le balisage sémantique. De plus, il n’est pas extensible. En effet, il estime que quand vous utilisez Markdown, vous n’avez droit qu’à trois types de formatage : gras, italique et code.


Si c’est le cas, que faire si vous souhaitez que certains éléments de la documentation soient colorés en bleu ? Ce type d’action n’est pas faisable. Vous ne pouvez que changer le CSS pour <em>, mais vous perdez l'italique dès lors que vous faites cela. Toutefois, il rappelle que Markdown peut être extensié uniquement en ajoutant du HTML brut. Le HTML est interprété comme du HTML à l'intérieur d'un document Markdown. Mais l’objectif de Markdown est d'éviter d'avoir à écrire du HTML en premier lieu. Vous ne pouvez pas non plus “hybrider” le Markdown avec du HTML.

En fait, ce qui se trouve dans les balises HTML ne sera pas analysé comme Markdown. Les gens ont essayé de résoudre ce problème avec les extensions pour l’outil, mais elles sont directement ajoutées au moteur de Markdown, et non dans le cadre d'une fonctionnalité d'extensibilité de ce dernier. Si vous voulez avoir une nouvelle chose, vous devez modifier le code du moteur. Par exemple, c’est ce qui arrive avec des images avec une légende. Ceci ne fait pas partie des spécifications de Markdown. En outre, il estime que Markdown ne propose qu’un traitement local.

Enfin, le dernier argument qu’il trouve en défaveur de Markdown est qu’il est juste bon pour écrire du HTML, mais pas du tout adapté pour écrire des documents PDF par exemple. Selon lui, une documentation doit être consultable hors ligne. Ainsi, si vous ne fournissez pas un PDF pour cela, il faut que vous proposiez au moins un lien pour télécharger les documents. Comme alternative, il vous propose d’utiliser reStructuredText ou RST pour écrire vos documentations. Selon lui, Latex est un bon outil, mais il n’est pas meilleur que Markdown.

D’après lui, avec reStructuredText, vous pouvez ajouter toutes sortes d'autres choses, comme montrer ou cacher des sections ou intégrer des mathématiques. Cela dit, l'inconvénient est qu'il est plus complexe que Markdown. Une autre alternative qu’il propose est AsciiDoc. Selon lui, AsciiDoc semble être très utile aussi.

Pour finir, selon Jeff Geerling qui soutient que Markdown est le meilleur outil pour vos documentations, il y a souvent de bonnes raisons de préférer une option plus structurée, comme reStructuredText, LaTeX ou Asciidoc. Cela arrive surtout dans le cadre des projets où un texte plus formel est nécessaire, ou lorsque vous devez prendre en charge la mise en forme de textes spécialisés et structurés. Néanmoins, Jeff Geerling pense que Markdown est le meilleur et le plus flexible des outils pour une documentation.

Sources : Jeff Geerling, HIllel Wayne

Et vous ?

Quel est votre avis sur le sujet ?
Quel outil utilisez-vous pour écrire la documentation de vos projets ?
Quelle est votre préférence, Markdown ou LaTeX ou autres ? Pourquoi ?

Voir aussi

Mark Text : un éditeur Markdown simple et élégant axé sur la rapidité et la convivialité selon son développeur. Disponible pour macOS, Windows et Linux

YouTrack 2019.3 est disponible avec un support HTML dans Markdown et d'autres nouvelles fonctionnalités et améliorations

Utilisez Markdown pour rédiger des articles ou tutoriels sur Developpez.com, en plus des autres outils toujours disponibles

Une erreur dans cette actualité ? Signalez-nous-la !

Avatar de frfancha
Membre éprouvé https://www.developpez.com
Le 27/03/2020 à 16:51
Markdown vs latex???
On compare vélo avec autocar là !
Ça me viendrait pas à l'idée du tout d'aller chercher mon pain en autocar.
Ni d'organiser l'excursion de la boîte en baie de Somme à vélo.
Je comprends pas bien l'intérêt de la question.
14  0 
Avatar de TheGuit
Membre régulier https://www.developpez.com
Le 27/03/2020 à 17:00
Citation Envoyé par frfancha Voir le message
Markdown vs latex???
On compare vélo avec autocar là !
Ça me viendrait pas à l'idée du tout d'aller chercher mon pain en autocar.
Ni d'organiser l'excursion de la boîte en baie de Somme à vélo.
Je comprends pas bien l'intérêt de la question.
Entièrement d'accord. Si demain je fais un rapport de 150 pages je pense qu'il a plus de chance d'être en LaTeX. Si c'est pour faire un README dans mon projet OpenSource moins.
6  0 
Avatar de TheGuit
Membre régulier https://www.developpez.com
Le 27/03/2020 à 19:33
Citation Envoyé par dourouc05 Voir le message
Et encore... Tu utiliserais LaTeX pour un document simple ? L'outil est trop compliqué pour la grande majorité des tâches de bureautique. Il est bien pour générer un PDF léché, surtout du gros, mais sinon... (Déjà, pour rédiger la source utilisée pour générer ce PDF, j'ai du mal à imaginer utiliser LaTeX, comme si les gens écrivaient leur code en assembleur dans toutes les situations...)
Ouais enfin quand tu connais la syntaxe tu fait un doc LaTeX dans le même temps que d'autre démarre Word. C'est plus une question d'habitude pour le coup.
6  0 
Avatar de TheGuit
Membre régulier https://www.developpez.com
Le 27/03/2020 à 16:58
http://asciidoc.org/ plus complet que MD.
4  0 
Avatar de Samir_OUCHENE
Membre à l'essai https://www.developpez.com
Le 27/03/2020 à 20:54
Je pense qu'avec pandoc, les choses sont, désormais, relativement facile. On peut rédiger avec markdown et le convertir en plein d'autres formats(Tex, HTML, MS Word, Pdf, ...etc).
4  0 
Avatar de cavo789
Membre émérite https://www.developpez.com
Le 27/03/2020 à 21:22
Bonsoir

Je rejoins l'idée mentionnée ci-dessus qu'avec Pandoc on fait déjà des merveilles. On écrit en markdown et on produit des documents dans de multiples format dont PDF.

A ce titre, je vous invite à découvrir le template `eisvogel.tex` (https://github.com/Wandmalfarbe/pand...latex-template) de Pascal Wagler.

Je rédige tout en markdown et quand je dis tout, c'est presque tout : emails, documentations et présentations (slideshow). Pour ce dernier, j'utilise alors `reveal.js` (https://github.com/hakimel/reveal.js).

Retour sur markdown : oui, le langage est limité mais c'est sa force. Il est lisible en tant que tel et déjà largement suffisant.

Mais pas que... J'ai développé un script (professionnel; désolé) en Powershell qui parse mes documents.

Je crée une structure de dossier avec des dossiers, sous-dossiers et documents .md. Le script parcoure le projet et prends chaque fichiers `.md` et consolide dans un seul fichier (`mon_projet.md` p.ex.). A chaque fois que je descends dans la structure (un sous-dossier), j'ajoute un niveau à mes titres (un `#` devient donc un `##`) et ainsi je respecte la hiérarchie des documents selon la structure.

Code : Sélectionner tout
1
2
3
4
5
6
7
8
9
10
11
Mon projet
    010-Introduction
        index.md
    020-Installation
        010-Téléchargement
            index.md
        020-Exécution
            index.md
    030-Configuration
    etc

Toujours avec ce parser, j'analyse le contenu des fichiers `.md` et je recherche des *tags* : j'ajoute p.ex. un `<!-- plugin::toc -->` et le parser voit `<!-- plugin::XXX -->` et sait qu'il doit faire quelque chose.

J'ai des dizaines de plugins, dont p.ex. `toc` pour générer une table des matières et donc, le parser lit le fichier complet (`mon_projet.md`); fait l'inventaire des titres et génère une table des matières.

Des dizaines ... et c'est simple à en créer d'autres.

* `<!-- plugin::exec "dir *.png" -->` pour exécuter une commande DOS, récupérer l'output de la commande et insérer cela dans mon document (et donc avoir une liste d'images .png p.ex.),
* `<!-- plugin::webservice {"url":"XXXX", "...."} -->` pour exécuter un service web, la liste des paramètres étant fournis dans un code de type JSON, l'output du service web sera insérer dans le document,
* `<!-- plugin::mysql {"db":"xxx", "user":"xxx", "sql":"select * from ...", "...."} -->` pour exécuter un query SELECT ... ROM sur une DB MySQL, récupérer le résultat et l'afficher sous forme de tableau dans mon document,
* `<!-- plugin::csv "fichier.csv" -->` pour lire un fichier .csv, le convertir en un tableau et l'insérer dans le document,
* `<!-- plugin::include "source.php" -->` pour inclure un fichier externe et l'afficher dans un tag PHP ou XML ou JSON ou ...
* ...

La seule limite est l'imagination.

Tout ça avec :

1. Tout se fait en markdown
2. Un script qui traite le fichier / les fichiers et qui génère un fichier final
3. Pandoc pour la conversion vers le format souhaité
4. Selon le format utilisé pour la conversion, ajout de paramètres à Pandoc pour p.ex. utiliser un modèle .tex ou .docx (pour Word) ou .html/.css pour un export en HTML.

Alors un immense OUI à Markdown.

Bonne soirée.
4  0 
Avatar de Markand
Membre éclairé https://www.developpez.com
Le 27/03/2020 à 14:47
Usuellement j'utilise du mdoc car je documente sous forme de page de manuel puis je converti en HTML pour afficher une version en ligne. Ensuite j'utilise la syntaxe textile de mon wiki redmine pour tout ce qui est annexe.

Le markdown est bien trop limité.
2  0 
Avatar de dourouc05
Responsable Qt & Livres https://www.developpez.com
Le 27/03/2020 à 18:45
Citation Envoyé par air-dex Voir le message
Le LaTeX sert plus pour de la bureautique, genre publication de plusieurs dizaines ou centaines de pages. LaTeX est plus un concurrent de MS Office ou de LibreOffice que de Markdown.
Et encore... Tu utiliserais LaTeX pour un document simple ? L'outil est trop compliqué pour la grande majorité des tâches de bureautique. Il est bien pour générer un PDF léché, surtout du gros, mais sinon... (Déjà, pour rédiger la source utilisée pour générer ce PDF, j'ai du mal à imaginer utiliser LaTeX, comme si les gens écrivaient leur code en assembleur dans toutes les situations...)
2  0 
Avatar de Angelsafrania
Membre éclairé https://www.developpez.com
Le 27/03/2020 à 15:55
Pour moi la doc c'est JavaDoc pour le code et markdown pour le reste.
1  0 
Avatar de air-dex
Membre expert https://www.developpez.com
Le 27/03/2020 à 18:23
Les deux n'ont surtout pas les mêmes usages. Le LaTeX sert plus pour de la bureautique, genre publication de plusieurs dizaines ou centaines de pages. LaTeX est plus un concurrent de MS Office ou de LibreOffice que de Markdown.

Pour documenter mon code j'utiliserais plutôt Markdown ou Doxygen.
1  0