Comment utiliser pandoc pour convertir des fichiers sur la ligne de commande Linux

Vous pouvez utiliser pandoc sur Linux pour convertir entre plus de 40 formats de fichiers. Vous pouvez également l’utiliser pour créer un système docs-as-code simple en écrivant dans Markdown, en stockant dans gitet la publication dans l’un de ses formats pris en charge.

Conversion de documents et Docs-as-Code

Si vous avez un document dans l’un des pandoc's de nombreux formats de fichiers pris en charge, le convertir en l’un des autres est un jeu d’enfant. C’est un outil pratique à avoir!

Mais le vrai pouvoir de pandoc devient évident lorsque vous l’utilisez comme base d’un simple système docs-as-code. Le principe de la documentation en tant que code est d’adopter certaines des techniques et principes du développement logiciel et de les appliquer à la rédaction de la documentation, en particulier pour les projets de développement logiciel. Vous pouvez cependant l’appliquer au développement de tout type de documentation.

Les développeurs de logiciels utilisent leur éditeur préféré ou environnement de développement intégré (IDE) pour écrire leurs programmes. Le code qu’ils saisissent est enregistré dans des fichiers texte. Ceux-ci contiennent le code source pour le programme.

Ils utilisent un système de contrôle de version, ou VCS (Git est le plus populaire), pour capturer les modifications du code source au fur et à mesure de son développement et de son amélioration. Cela signifie que le programmeur a un historique complet de toutes les versions des fichiers de code source. Il peut accéder rapidement à toute version précédente d’un fichier. Git stocke les fichiers dans un référentiel. Il existe un référentiel local sur l’ordinateur de chaque développeur et un référentiel central, partagé et distant, souvent hébergé dans le cloud.

Lorsqu’ils sont prêts à produire une version fonctionnelle du programme, ils utilisent un compilateur pour lire le code source et générer un exécutable binaire.

En écrivant vos documents dans un langage de balisage léger et basé sur du texte, vous pouvez utiliser un VCS pour contrôler la version de votre écriture. Lorsque vous êtes prêt à distribuer ou publier un document, vous pouvez utiliser pandoc pour générer autant de versions différentes de votre documentation que nécessaire, y compris sur le Web (HTML), traitement de texte ou composition (LibreOffice, Microsoft Word, Texas), Portable Document Format (PDF), livre électronique (ePub), etc.

Vous pouvez effectuer tout cela à partir d’un ensemble de fichiers texte légers contrôlés par version.

Installation de pandoc

À installer pandoc sur Ubuntu, utilisez cette commande:

sudo apt-get install pandoc

sudo apt-get install pandoc dans une fenêtre de terminal.

Sur Fedora, la commande dont vous avez besoin est la suivante:

sudo dnf install pandoc

sudo dnf installe pandoc dans une fenêtre de terminal.

Sur Manjaro, vous devez taper:

sudo pacman -Syu pandoc

sudo pacman -Syu pandoc dans une fenêtre de terminal.

Vous pouvez vérifier la version que vous avez installée en utilisant le --version option:

pandoc --version

pandoc --version dans une fenêtre de terminal.

Utiliser pandoc sans fichiers

Si tu utilises pandoc sans aucune option de ligne de commande, il accepte également les entrées tapées. Vous appuyez simplement sur Ctrl + D pour indiquer que vous avez terminé de taper. pandoc attend que vous tapiez au format Markdown, et il génère une sortie HTML.

Regardons un exemple:

pandoc

pandoc dans une fenêtre de terminal.

Nous avons tapé quelques lignes de Markdown et sommes sur le point d’appuyer sur Ctrl + D.

Exemples de lignes de démarques saisies dans pandoc dans une fenêtre de terminal.

Dès que nous le faisons, pandoc génère la sortie HTML équivalente.

HTML généré par pandoc dans une fenêtre de terminal.

Pour faire quelque chose d’utile avec pandoc, cependant, nous devons vraiment utiliser des fichiers.

Principes de base de Markdown

Markdown est un langage de balisage léger, et une signification particulière est donnée à certains caractères. Vous pouvez utiliser un éditeur de texte brut pour créer un fichier Markdown.

Markdown peut être lu facilement, car il n’y a pas de balises visuellement encombrantes pour détourner l’attention du texte. Le formatage dans les documents Markdown ressemble au formatage qu’il représente. Voici quelques-unes des bases:

  • Pour mettre en valeur le texte avec italique, enveloppez-le d’astérisques. *This will be emphasized*
  • À audacieux texte, utilisez deux astérisques. **This will be in bold**
  • Les en-têtes sont représentés par le signe dièse / signe dièse (#). Le texte est séparé du hachage par un espace. Utilisez un hachage pour un en-tête de niveau supérieur, deux pour un deuxième niveau, et ainsi de suite.
  • Pour créer une liste à puces, commencez chaque ligne de la liste par un astérisque et insérez un espace avant le texte.
  • Pour créer une liste numérotée, commencez chaque ligne par un chiffre suivi d’un point, puis insérez un espace avant le texte.
  • Pour créer un lien hypertexte, mettez le nom du site entre crochets ([]) et l’URL entre parenthèses [()] ainsi: [Link to How to Geek](https://www.howtogeek.com/).
  • Pour insérer une image, tapez un point d’exclamation juste avant les crochets (![]). Tapez tout autre texte pour l’image entre crochets. Ensuite, mettez le chemin d’accès à l’image entre parenthèses [()“]. Voici un exemple: ![The Geek](HTG.png).

Nous couvrirons plus d’exemples de tout cela dans la section suivante.

En relation :  Comment ouvrir l'éditeur de registre sur Windows 10

Bientôt: Qu’est-ce que Markdown et comment l’utilisez-vous?

Conversion de fichiers

Les conversions de fichiers sont simples. pandoc peut généralement déterminer les formats de fichiers avec lesquels vous travaillez à partir de leurs noms de fichiers. Ici, nous allons générer un fichier HTML à partir d’un fichier Markdown. le -o (sortie) indique pandoc le nom du fichier que nous souhaitons créer:

pandoc -o sample.html sample.md

pandoc -o sample.html sample.md dans une fenêtre de terminal.

Notre exemple de fichier Markdown, sample.md, contient la courte section de Markdown présentée dans l’image ci-dessous.

Texte Markdown dans le fichier sample.md dans une fenêtre de l'éditeur gedit.

Un fichier appelé sample.html est créé. Lorsque nous double-cliquons sur le fichier, notre navigateur par défaut l’ouvrira.

Rendu HTML du fichier markdown sample.md, dans une fenêtre de navigateur.

Maintenant, générons un Ouvrir le format de document document texte dans lequel nous pouvons ouvrir LibreOffice Writer:

pandoc -o sample.odt sample.md

pandoc -o sample.odt sample.md dans une fenêtre de terminal.

Le fichier ODT a le même contenu que le fichier HTML.

Un document ODT rendu à partir de markdown et ouvert dans LibreOffice Writer.

Une touche soignée est que le texte alternatif de l’image est également utilisé pour générer automatiquement une légende pour la figure.

Une légende de figure générée automatiquement dans LibreOffice Writer.

Spécification des formats de fichier

le -f (de) et -t (à) les options sont utilisées pour dire pandoc les formats de fichiers à partir desquels et vers lesquels vous souhaitez convertir. Cela peut être utile si vous travaillez avec un format de fichier qui partage une extension de fichier avec d’autres formats associés. Par exemple, Texas, et Latex tous deux utilisent l’extension «.tex».

Nous utilisons également le -s (autonome) option donc pandoc générera tout le préambule LaTeX requis pour qu’un document soit un document LaTeX complet, autonome et bien formé. Sans le -s (autonome), la sortie serait toujours LaTeX bien formée qui pourrait être insérée dans un autre document LaTeX, elle ne serait pas analysée correctement comme un document LaTeX autonome.

Nous tapons ce qui suit:

pandoc -f markdown -t latex -s -o sample.tex sample.md

pandoc -f markdown -t latex -s -o sample.tex sample.md dans une fenêtre de terminal.

Si vous ouvrez le fichier «sample.tex» dans un éditeur de texte, vous verrez le LaTeX généré. Si vous disposez d’un éditeur LaTeX, vous pouvez ouvrir le fichier TEX pour voir un aperçu de la façon dont les commandes de composition LaTeX sont interprétées. Réduire la fenêtre pour l’adapter à l’image ci-dessous donnait à l’écran un aspect exigu, mais, en réalité, tout allait bien.

Un fichier LaTeX ouvert dans Texmaker, montrant un aperçu de la page de composition.

Nous avons utilisé un éditeur LaTeX appelé Texmaker. Si vous souhaitez l’installer dans Ubuntu, tapez ce qui suit:

sudo apt-get install texmaker

Dans Fedora, la commande est:

sudo dnf install texmaker

Dans Manjaro, utilisez:

sudo pacman -Syu texmaker

Conversion de fichiers avec des modèles

Vous commencez probablement à comprendre la flexibilité que pandoc fournit. Vous pouvez écrire une fois et publier dans presque tous les formats. C’est un grand exploit, mais les documents ont l’air un peu vanille.

Avec les modèles, vous pouvez dicter les styles pandoc utilise lorsqu’il génère des documents. Par exemple, vous pouvez dire pandoc pour utiliser les styles définis dans un Feuilles de style en cascade (CSS) avec le --css option.

Nous avons créé un petit fichier CSS contenant le texte ci-dessous. Il modifie l’espacement au-dessus et en dessous du style d’en-tête de niveau un. Il change également la couleur du texte en blanc et la couleur d’arrière-plan en une nuance de bleu:

h1 {
  color: #FFFFFF;
  background-color: #3C33FF;
  margin-top: 0px;
  margin-bottom: 1px;
}

La commande complète est ci-dessous – notez que nous avons également utilisé l’option autonome (-s):

pandoc -o sample.html -s --css sample.css sample.md

pandoc utilise le style unique de notre fichier CSS minimaliste et l’applique à l’en-tête de niveau un.

En relation :  Comment créer des emplacements de lettres espacés régulièrement pour les formulaires dans Microsoft Word?

HTML rendu à partir du démarque avec un style CSS appliqué à l'en-tête de niveau un, dans une fenêtre de navigateur

Une autre option de réglage fin dont vous disposez lorsque vous travaillez avec des fichiers HTML consiste à inclure un balisage HTML dans votre fichier Markdown. Cela sera transmis au fichier HTML généré en tant que balisage HTML standard.

Cette technique doit cependant être réservée lorsque vous ne générez qu’une sortie HTML. Si vous travaillez avec plusieurs formats de fichiers, pandoc ignorera le balisage HTML pour les fichiers non HTML, et il sera transmis à ceux-ci sous forme de texte.

Nous pouvons également spécifier les styles utilisés lors de la génération des fichiers ODT. Ouvrez un document LibreOffice Writer vierge et ajustez les styles d’en-tête et de police en fonction de vos besoins. Dans notre exemple, nous avons également ajouté un en-tête et un pied de page. Enregistrez votre document sous «odt-template.odt».

Nous pouvons maintenant l’utiliser comme modèle avec le --reference-doc option:

pandoc -o sample.odt --reference-doc=odt-template.odt sample.md

pandoc -o sample.odt --reference-doc = odt-template.odt sample.md dans une fenêtre de terminal.

Comparez cela avec l’exemple ODT précédent. Ce document utilise une police différente, a des en-têtes colorés et inclut des en-têtes et des pieds de page. Cependant, il a été généré à partir du même fichier Markdown «sample.md».

Un fichier ODT rendu à partir du markdown avec un document LibreOffice faisant office de feuille de style, dans une fenêtre LibreOffice Writer.

Les modèles de document de référence peuvent être utilisés pour indiquer les différentes étapes de la production d’un document. Par exemple, vous pouvez avoir des modèles comportant des filigranes «Brouillon» ou «À réviser». Un modèle sans filigrane serait utilisé pour un document finalisé.

Générer des PDF

Par défaut, pandoc utilise le moteur LaTeX PDF pour générer des fichiers PDF. Le moyen le plus simple de s’assurer que les dépendances LaTeX appropriées sont satisfaites est d’installer un éditeur LaTeX, tel que Texmaker.

C’est une installation assez volumineuse, cependant – Tex et LaTeX sont tous les deux assez lourds. Si l’espace de votre disque dur est limité ou si vous savez que vous n’utiliserez jamais TeX ou LaTeX, vous préférerez peut-être générer un fichier ODT. Ensuite, vous pouvez simplement l’ouvrir dans LibreOffice Writer et l’enregistrer au format PDF.

Documents en tant que code

Il y a plusieurs avantages à utiliser Markdown comme langage d’écriture, notamment les suivants:

  • Travailler dans des fichiers texte brut est rapide: Ils se chargent plus rapidement que les fichiers de traitement de texte de taille similaire et ont tendance à se déplacer plus rapidement dans le document. De nombreux éditeurs, dont gedit , Vim , et Emacs, utilisez la coloration syntaxique avec le texte Markdown.
  • Vous aurez une chronologie de toutes les versions de vos documents: Si vous stockez votre documentation dans un VCS, tel que Git, vous pouvez facilement voir les différences entre deux versions du même fichier. Cependant, cela ne fonctionne vraiment que lorsque les fichiers sont en texte brut, car c’est ce avec quoi un VCS s’attend à travailler.
  • Un VCS peut enregistrer qui a apporté des modifications et quand: Ceci est particulièrement utile si vous collaborez souvent avec d’autres sur de grands projets. Il fournit également un référentiel central pour les documents eux-mêmes. De nombreux services Git hébergés dans le cloud, tels que GitHub, GitLab, et BitBucket, ont des niveaux gratuits dans leurs modèles de tarification.
  • Vous pouvez générer vos documents dans plusieurs formats: Avec juste quelques scripts shell simples, vous pouvez extraire les styles de CSS et de documents de référence. Si vous stockez vos documents dans un référentiel VCS qui s’intègre à Intégration continue et déploiement continu (CI / CD), ils peuvent être générés automatiquement à chaque fois que le logiciel est construit.

Bientôt: Qu’est-ce que GitHub et à quoi sert-il?

Dernières pensées

Il existe de nombreuses autres options et fonctionnalités dans pandoc que ce que nous avons couvert ici. Les processus de conversion pour la plupart des types de fichiers peuvent être modifiés et affinés. Pour en savoir plus, consultez les excellents exemples sur le site officiel (et extrêmement détaillés) page web pandoc.

Moyens Staff
Moyens I/O Staff vous a motivé, donner des conseils sur la technologie, le développement personnel, le style de vie et des stratégies qui vous aider.