Vous pouvez utiliser pandoc sur Linux pour convertir entre plus de 40 format de fichier. Vous pouvez également l'utiliser pour créer un système de document simple en tant que code en écrivant dans Markdown, stocker dans gitet publier dans l'un de ses formats pris en charge.
Convertir des documents et des documents en tant que code
Si vous avez un document dans l'un des pandoc's de nombreux formats de fichiers pris en charge, le transformer en l'un des autres est un morceau de gâteau. C'est un outil utile pour avoir!
Mais le vrai pouvoir de pandoc devient évident lorsque vous l'utilisez comme base d'un système de document simple en tant que code. La prémisse de docs-as-code est de prendre certaines des techniques et principes du développement logiciel et de les appliquer à la rédaction de documentation, en particulier pour les projets de développement de logiciels. Malgré cela, vous pouvez l'appliquer à l'élaboration de tout type de documentation.
Les développeurs de logiciels utilisent leur éditeur préféré ou environnement de développement intégré (ICI) pour écrire vos programmes. Le code qu'ils écrivent 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, le VCS (Git est le plus populaire), pour capturer les modifications apportées au code source au fur et à mesure qu'il est développé et amélioré. Cela signifie que le programmeur a un historique complet de toutes les versions des fichiers de code source.. Vous pouvez accéder rapidement à n'importe quelle 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 qui est souvent hébergé dans le cloud.
Quand ils sont prêts à produire une version de travail du programme, ils utilisent un compilateur pour lire le code source et générer un exécutable binaire.
En rédigeant vos documents dans un langage de balisage textuel léger, vous pouvez utiliser un VCS pour contrôler la version de votre script. 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 vous le souhaitez, y compris ceux pris en charge sur le Web (HTML), traitement de texte ou typographique (LibreOffice, Microsoft Word, Texas), Portable Document Format (PDF), livre électronique (ePub), etc.
Vous pouvez faire tout cela à partir d'un ensemble de fichiers texte légers contrôlés par version.
Installation Pandoc
Installer pandoc sous Ubuntu, utilise cette commande:
sudo apt-get install pandoc
Dans Fedora, la commande dont vous avez besoin est la suivante:
sudo dnf installer pandoc
à Manjaro, doit écrire:
sudo pacman -Syu pandoc
Vous pouvez vérifier quelle version vous avez installée en utilisant le --version option:
pandoc --version
Utiliser pandoc sans fichiers
Si tu utilises pandoc sans aucune option de ligne de commande, accepte également les entrées écrites. Appuyez simplement sur Ctrl + D pour indiquer que vous avez fini de taper. pandoc s'attend à ce que vous écriviez au format Markdown et génère une sortie HTML.
Voyons un exemple:
pandoc
Nous avons écrit quelques lignes de Markdown et nous sommes sur le point d'appuyer sur Ctrl + ré.
Dès que nous le faisons pandoc génère une sortie HTML similaire.
Pour faire quelque chose d'utile avec pandoc, malgré cela, nous avons vraiment besoin d'utiliser des fichiers.
Notions de base sur la démarque
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 facilement lu, car il n'y a pas d'étiquettes visuellement encombrantes pour détourner l'attention du texte. Le format dans les documents Markdown ressemble au format qu'il représente. Voici quelques-unes des bases:
- Pour souligner le texte avec italique, entourez-le d'astérisques.
*This will be emphasized* - Pour caractère gras texte, utiliser deux astérisques.
**This will be in bold** - Les titres sont représentés par le signe dièse / marque de tampon (
#). Le texte est séparé du hachage par un espace. Utiliser 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, commencer chaque ligne de la liste par un astérisque et insérer 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, mettre le nom du site entre crochets (
[]) et l'url entre parenthèses [()] de la même manière que:[Link to How to Geek](https://www.systempeaker.com/). - Pour insérer une image, tapez un point d'exclamation juste avant les crochets (
![]). Écrivez tout texte alternatif pour l'image entre parenthèses. Ensuite, mettre le chemin de l'image entre parenthèses [()"]. Voici un exemple:.
Nous couvrirons plus d'exemples de tous ces éléments dans la section suivante..
EN RELATION: Qu'est-ce que le Markdown et comment est-il utilisé?
Conversion de fichiers
Les conversions de fichiers sont faciles. pandoc En général, vous pouvez 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. Les -o (sortir) option dit pandoc le nom du fichier que nous voulons créer:
pandoc -o exemple.html exemple.md
Notre exemple de fichier Markdown, échantillon.md, contient la courte section Markdown montrée dans l'image ci-dessous.
Un fichier appelé sample.html est créé. Lorsque nous double-cliquons sur le fichier, notre navigateur par défaut l'ouvrira.
À présent, generamos un Ouvrir le format de document document texte que nous pouvons ouvrir dans Rédacteur LibreOffice:
pandoc -o sample.odt sample.md
Le fichier ODT a le même contenu que le fichier HTML.
Une touche propre est le texte alternatif de l'image qui est également utilisé pour générer automatiquement un titre pour la figure.
Spécifier les formats de fichier
Les -f (de) et -t (une) les alternatives sont utilisées pour dire pandoc les formats de fichiers vers et depuis 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 les deux utilisent l'extension ".tex".
Nous utilisons également le -s (Indépendant) option pandoc générera tout le préambule LaTeX nécessaire pour qu'un document soit un document LaTeX complet, autonome et bien formé. Sans lui -s (Indépendant), la sortie serait toujours du LaTeX bien formé qui pourrait être inséré dans un autre document LaTeX, ne serait pas analysé correctement en tant que document LaTeX autonome.
Nous écrivons ce qui suit:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Si vous ouvrez le fichier “échantillon.tex” dans un éditeur de texte, vous verrez le LaTeX généré. Si vous avez 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. Le rétrécissement de la fenêtre pour l'adapter à l'image ci-dessous a fait apparaître l'écran étroit, mais, en réalité, c'était bien.
Nous utilisons un éditeur LaTeX appelé Texmaker. Si vous voulez l'installer sur Ubuntu, écris ce qui suit:
sudo apt-get install texmaker
Dans Fedora, la commande est:
sudo dnf installer texmaker
à Manjaro, utilisation:
sudo pacman -Syu texmaker
Convertir des fichiers avec des modèles
Vous commencez probablement à comprendre la flexibilité qui pandoc fournit. Vous pouvez écrire une fois et publier dans presque tous les formats. C'est un grand exploit, mais les docs ont l'air un peu vanille.
Avec des modèles, peut dicter quels styles pandoc utilisé lors de la génération de documents. Par exemple, tu peux dire pandoc utiliser les styles définis dans un Feuilles de style en cascade (CSS) fichier avec --css option.
Nous avons créé un petit fichier CSS contenant le texte ci-dessous. Modifier l'espace au-dessus et au-dessous du style de titre de niveau. Il change également la couleur du texte en blanc et la couleur d'arrière-plan en bleu.:
h1 {
Couleur: #FFFFFF;
Couleur de l'arrière plan: #3C33FF;
marge-haut: 0px;
marge-bas: 1px;
}La commande complète est ci-dessous; notez que nous utilisons également 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.
Une autre alternative de wrapper dont vous disposez lorsque vous travaillez avec des fichiers HTML consiste à inclure le balisage HTML dans votre fichier Markdown.. Ceci sera transmis au fichier HTML généré en tant que balisage HTML standard.
Malgré cela, cette technique doit être réservée lorsque vous générez uniquement une sortie HTML. Si vous travaillez avec suffisamment de formats de fichiers, pandoc ignorera le balisage HTML pour les fichiers non HTML et leur passera sous forme de texte.
Nous pouvons également spécifier quels styles sont utilisés lors de la génération de fichiers ODT. Ouvrez un document LibreOffice Writer vierge et ajustez le titre et les styles de police en fonction de vos besoins. Dans notre exemple, nous ajoutons également un en-tête et un pied de page. Enregistrer votre document sous “odt-template.odt”.
Maintenant, nous pouvons l'utiliser comme modèle avec le --reference-doc option:
pandoc -o sample.odt --reference-doc = odt-template.odt sample.md
Comparez ceci à l'exemple ODT ci-dessus. Ce document utilise une police différente, a des en-têtes colorés et comprend des en-têtes et des pieds de page. Malgré cela, a été généré à partir exactement du même fichier Markdown “échantillon.md”.
Les modèles de documents 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 qui ont des filigranes “Brouillon” O “Pour examen”. Un modèle sans filigrane serait utilisé pour un document fini.
Génération de fichiers 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 bonnes dépendances LaTeX sont satisfaites est d'installer un éditeur LaTeX, en tant que Texmaker.
Malgré cela, c'est une assez grande installation: Tex et LaTeX sont assez lourds. Si l'espace de votre disque dur est limité, 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 l'ouvrir dans LibreOffice Writer et l'enregistrer au format PDF.
Documents en tant que code
Utiliser Markdown comme langage d'écriture présente plusieurs avantages, y compris ce qui suit:
- 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 également tendance à se déplacer plus rapidement dans le document. De nombreux éditeurs, inclus
gedit,Vim, etEmacs, utiliser 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, comme idiot, vous pouvez facilement voir les différences entre deux versions du même fichier. Malgré cela, cela ne fonctionne vraiment que lorsque les fichiers sont en texte brut, puisque c'est avec cela qu'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, comme 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, peut extraire des 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 avec Intégration continue et déploiement continu (CI / CD), peut être généré automatiquement à chaque création du logiciel.
EN RELATION: Qu'est-ce que GitHub et à quoi sert-il?
Dernières pensées
Il y a beaucoup plus d'options et de fonctions à l'intérieur pandoc de ce que nous avons couvert ici. Les processus de conversion pour la plupart des types de fichiers peuvent être modifiés et ajustés. Pour plus d'informations, consultez les excellents exemples dans la publication officielle (et extrêmement détaillé) site pandoc.
