Un aper­çu de Pan­doc

Dans un billet pré­cé­dent, je par­lais des avan­tages du Mark­down dans les pro­ces­sus de conver­sion vers des for­mats de sor­tie comme HTML et LaTeX. Il se trouve que Mas­si­mi­lia­no Domi­ni­ci, pas­sé maître dans l’usage de Pan­doc, a publié en 2013 un article remar­quable foca­li­sant jus­te­ment sur les fonc­tion­na­li­tés de Pan­doc du point de vue des objec­tifs de publi­ca­tion HTML et LaTeX (PDF).

Pré­sen­ta­tion

Avec l’autorisation de l’auteur, je pro­pose une tra­duc­tion fran­çaise de cet article qui ne man­que­ra pas d’intéresser ceux qui hésitent encore à fran­chir le pas de la ligne de com­mande avec Pan­doc ou tout sim­ple­ment ceux qui ne connaissent pas encore ce logi­ciel.

Cet article de Mas­si­mi­lia­no Domi­ni­ci est paru sous le titre « An over­view of Pan­doc », TUG­boat 35:1, 2014, pp. 44 – 50. Ori­gi­nel­le­ment publié sous « Una pano­ra­mi­ca su Pan­doc », Ars­TEX­ni­ca 15, avril 2013, pp. 31 – 38. Tra­duc­tion de l’anglais par Chris­tophe Masut­ti, avec l’aimable auto­ri­sa­tion de l’auteur. Licence du docu­ment : CC By-Sa.

Vous trou­ve­rez sur ce dépôt GIT les sources qui ont ser­vi à la com­po­si­tion et à la com­pi­la­tion du docu­ment, en uti­li­sant Pandoc’s Mark­down. Il est pos­sible de télé­char­ger direc­te­ment la ver­sion PDF. Le fichier README.md contient les lignes de com­mandes des­ti­nées aux sor­ties vou­lues.

Intro­duc­tion

Pan­doc est un logi­ciel écrit en Has­kell dont le but est de faci­li­ter la conver­sion entre plu­sieurs lan­gages de bali­sage légers et des for­mats de docu­ments « finaux » les plus répan­dus1. Sur le site du pro­gramme2, Pan­doc est décrit comme une sorte de « cou­teau suisse » ser­vant à conver­tir dif­fé­rents for­mats ; en réa­li­té il est capable de lire de simples fichiers écrits en LaTeX ou en HTML ; mais il est d’une moindre uti­li­té lorsqu’il s’agit de conver­tir des docu­ments LaTeX com­por­tant des construc­tions non-tri­viales défi­nies par l’utilisateur ou par des exten­sions (packages) dédiés.

Selon moi, Pan­doc montre sa véri­table uti­li­té lorsqu’il s’agit d’obtenir quelques for­mats de sor­tie à par­tir d’une seule source, comme dans le cas d’un docu­ment pour le web (HTML), pour l’impression (PDF via LaTeX) ou pour être lu sur tablette ou liseuse (EPUB). Dans ces cas, on peut pen­ser qu’écrire le docu­ment dans un for­mat enri­chi (par ex. LaTeX) et le conver­tir ensuite vers d’autres lan­gages bali­sés pose sou­vent des pro­blèmes signi­fi­ca­tifs à cause des dif­fé­rentes « phi­lo­so­phies » qui sous-tendent chaque lan­gage. Au lieu de cela, il est conseillé de choi­sir dès le départ un lan­gage « neutre » de par sa concep­tion. Un bon can­di­dat pour ce rôle est un lan­gage de bali­sage léger, en par­ti­cu­lier Mark­down, brillam­ment inter­pré­té par Pan­doc.

Dans cet article, nous allons briè­ve­ment abor­der le concept de « lan­gage de bali­sage léger » en nous réfé­rant par­ti­cu­liè­re­ment à Mark­down (sec­tion 2), puis nous exa­mi­ne­rons Pan­doc plus en détail (sec­tion 3) avant d’en tirer nos conclu­sions (sec­tion 5).

Les lan­gages de bali­sage légers

Avant d’entrer dans le vif du sujet, il est pré­fé­rable d’écrire quelques mots à pro­pos des lan­gages de bali­sage légers (LML) en général[@Wikipedi2013]. Ils sont conçus avec pour objec­tif expli­cite de mini­mi­ser l’impact des ins­truc­tions de bali­sage sur le docu­ment, en insis­tant par­ti­cu­liè­re­ment sur la lisi­bi­li­té du texte par un être humain même lorsque celui-ci ne connaît pas les (quelques) conven­tions que le pro­gramme adopte pour for­ma­ter le docu­ment.

Ces lan­gages sont uti­li­sés prin­ci­pa­le­ment dans deux domaines : la docu­men­ta­tion de code (reStruc­tu­red­Text, Ascii­Doc, etc.) et la ges­tion de conte­nus pour le web (Mark­down, Tex­tile, etc.). En ce qui concerne la docu­men­ta­tion de code, l’usage d’un LML est un bon choix, puisque la docu­men­ta­tion est inter­ca­lée dans le code lui-même, donc elle doit être facile à lire par un déve­lo­peur par­cou­rant le code ; mais en même temps, il doit être pos­sible de la conver­tir dans des for­mats de pré­sen­ta­tion (tra­di­tion­nel­le­ment en PDF ou HTML, bien qu’aujourd’hui beau­coup d’IDE intègrent diverses solu­tions pour visua­li­ser la docu­men­ta­tion interne). En ce qui concerne les conte­nus web, on insiste plu­tôt sur la faci­li­té d’écriture pour l’utilisateur. Beau­coup de sys­tèmes de ges­tion de conte­nus (CMS) pro­posent aujourd’hui des plu­gins pour un ou plu­sieurs de ces lan­gages, et il en est de même pour les géné­ra­teurs de sites sta­tiques3 qui sont habi­tuel­le­ment construits sur la base de l’un d’entre eux et four­nissent sou­vent des solu­tions pour les autres. Les dia­lectes wiki peuvent être consi­dé­rés comme des ins­tances de LML.

La « légé­re­té » concrète d’un LML dépend gran­de­ment de son objec­tif final[@Kielhorn2011;@MacFarlane2013]. En géné­ral, un LML conçu pour la docu­men­ta­tion de code sera plus com­plexe et moins lisible que celui conçu pour de la ges­tion de conte­nus web qui, en retour, sera sou­vent dans l’incapacité d’un bali­sage séman­tique géné­ral. Une illus­tra­tion para­dig­ma­tique de cette seconde caté­go­rie est le Mark­down qui, dans sa ver­sion ori­gi­nale, reste rigou­reu­se­ment proche de l’approche mini­ma­liste des pre­miers LMLs. La cita­tion sui­vante de son auteur, John Gruber[@Gruber2013], explique son inten­tion lorsqu’il a conçu Mark­down :

Mark­down est pré­vu pour être facile à lire et facile à écrire autant que faire se peut. Tou­te­fois, on insis­te­ra par-des­sus tout sur la lisi­bi­li­té. Un docu­ment for­ma­té en Mark­down doit être publiable tel quel, en texte brut, sans qu’il puisse sem­bler être bali­sé avec des tags ou des ins­truc­tions de for­ma­tage.4

Le seul for­mat de sor­tie ciblé par l’implémentation de réfé­rence de Mark­down est le HTML ; en effet, Mark­down per­met l’insertion de code HTML. Gru­ber a tou­jours col­lé à ce pos­tu­lat ini­tial et a tou­jours refu­sé d’étendre le lan­gage au-delà de ses spé­ci­fi­ca­tions ori­gi­nales. Cette pos­ture est la cause d’une pro­li­fé­ra­tion de variantes, à tel point que chaque implé­men­ta­tion consti­tue une ver­sion « amé­lio­rée ». Des sites célèbres comme GitHub, Red­dit et Stack Over­flow, tous com­portent leur propre saveur de Mark­down ; et c’est aus­si valable pour les pro­grammes de conver­sion comme Mul­ti­Mark­down ou Pan­doc lui-même, qui intro­duit aus­si de nou­veaux for­mats de sor­tie. Il n’est pas utile ici d’examiner en détail ces dif­fé­rentes ver­sions ; le lec­teur pour­ra se faire une idée des règles basiques de for­ma­tage en se repor­tant aux tableaux 1 et 2.

Bien sûr, dans l’implémentation de réfé­rence, il n’y a pas de sor­tie LaTeX, j’en ai donc fait la tra­duc­tion la plus logique. Dans les sec­tions sui­vantes, nous allons voir com­ment Pan­doc fonc­tionne en pra­tique.

Syn­taxe Mark­down : élé­ments de niveau en-ligne
Élé­ment Mark­down LaTeX HTML
Liens

[link](http:// exemple.net)

\href{link}{http:// exemple.net}

<a href="http://exam ple.net/">link</a>

Emphase

_emphase_
*emphase*

\emph{emphase} \emph{emphase}

<em>emphase</em> <em>emphase</em>

Emphase forte

__strong__
**strong**

\textbf{strong} \textbf{strong}

<strong>strong</strong> <strong>strong</strong>

Ver­ba­tim

« printf()«

\verb!printf()!

<code>printf()</code>

Images

![Alt](/chemin/ vers/img.jpg)

\includegraphics {img}

<img src="/chemin/vers /img.jpg" alt="Alt" />

Syn­taxe Mark­down : élé­ments de niveau bloc
Élé­ment Mark­down LaTeX HTML

Sec­tion

# Titre #
## Titre ##

\section{Titre} \subsection{Titre}

<h1>Titre</h1> <h2>Titre</h2>

Cita­tion

> Ce paragraphe est une citation

\begin{quote} Ce paragraphe est une citation \end{quote}

<blockquote><p> Ce paragraphe est une citation </p></blockquote>

Liste d’item

* Tulipe
* Rose
* Lys

\begin{itemize} \item Tulipe \item Rose \item Lys \end{itemize}

<ul> <li>Tulipe</li> <li>Rose</li> <li>Lys</li> </ul>

Liste énu­mé­ra­tive

1. Chaise
2. Banc
3. Table

\begin{enumerate} \item Chaise \item Banc \item Table \end{enumerate}

<ol> <li>Chaise</li> <li>Banc</li> <li>Table</li> </ol>

Ver­ba­tim

Paragraphe
grep -i \$ <file

Paragraphe
\begin{verbatim} grep -i \$ <file \end{verbatim}

<p>Paragraphe</p>
<pre><code> grep -i \$ <file </code></pre>

Un aper­çu de Pan­doc

Comme men­tion­né en intro­duc­tion, Pan­doc est en pre­mier lieu un inter­pré­teur de Mark­down avec plu­sieurs for­mats de sor­tie : HTML, LaTeX, ConTeXt, Doc­Book, ODF, OOXML, d’autres LMLs comme Ascii­Doc, reStruc­tu­red­Text et Tex­tile (la liste com­plète figure sur le site offi­ciel). Pan­doc peut aus­si conver­tir, avec de sérieuses res­tric­tions, un fichier source LaTeX, HTML, Doc­Book, Tex­tile ou reStruc­tu­red­Text dans un des for­mats ci-des­sus men­tion­nés. De plus, il étend la syn­taxe Mark­down en y intro­dui­sant de nou­veaux élé­ments et en per­son­na­li­sant les élé­ments déjà pré­sents dans la ver­sion de réfé­rence.

Les exten­sions à la syn­taxe Mark­down

De par sa concep­tion, Mark­down four­ni un nombre très limi­té d’éléments. Tableaux, notes de bas de page, for­mules et réfé­rences biblio­gra­phiques n’ont pas de bali­sage spé­ci­fique en Mark­down. Dans l’intention de l’auteur, tout bali­sage qui excède les limites du lan­gage doit être expri­mé en HTML. Pan­doc conserve cette approche (et pour des sor­ties LaTeX et ConTeXt, il per­met l’insertion de code TeX) mais rend cela non-néces­saire dans la mesure où il intro­duit beau­coup d’extensions qui donnent à l’utilisateur un bali­sage propre pour chaque élé­ment men­tion­né ci-des­sus. Dans les para­graphes sui­vants, nous allons nous pen­cher sur ces exten­sions.

Meta­don­nées

Les méta­don­nées comme le titre, l’auteur, la date peuvent être indi­quées au début du fichier, dans un bloc texte, pré­cé­dées du carac­tère %, comme dans l’exemple sui­vant :

 % Titre
 % Premier auteur ; second auteur
 % 17/02/2013

Le conte­nu de chaque élé­ment peut être absent à condi­tion que leurs lignes res­pec­tives soit lais­sées vides (sauf s’il s’agit du der­nier élé­ment, c’est-à-dire la date).

 % Titre
 % 
 % 17/02/2013

 % 
 % Premier auteur ; second auteur
 % 17/02/2013

 % Titre
 % Premier auteur ; second auteur

Depuis la ver­sion 1.12, le sup­port des méta­don­nées a été sub­stan­tiel­le­ment amé­lio­ré. Pan­doc accepte main­te­nant des blocs de méta­don­nées au for­mat YAML5, déli­mi­tés par une ligne de trois tirets (---) au des­sus et une ligne de trois tirets (---) ou trois points (...) en des­sous. Cela donne à l’utilisateur un haut niveau de flexi­bi­li­té dans la confi­gu­ra­tion et l’utilisation de variables uti­li­sées dans des modèles (tem­plates, voir sec­tion 3.1.9).

YAML struc­ture les méta­don­nées de manière hié­rar­chique, ce qui per­met d’obtenir une gra­nu­la­ri­té fine. L’utilisateur peut construire son fichier source avec le code sui­vant :

 ---
 author:
 - name: Premier auteur
 - affiliation: Première affiliation
 - name: Second auteur
 - affiliation: Seconde affiliation
 ---

Et dans le modèle, on peut indi­quer une liste d’auteur avec, le cas échéant, leurs affi­lia­tions :

 $for(author)$
 $if(author.name)$
 $author.name$
 $if(author.affiliation$ ($author.affiliation$)
 $endif$
 $else$
 $author$
 $endif$
 $endfor$

Comme nous le ver­rons dans la sec­tion 3.1.7, un bloc YAML peut aus­si être uti­li­sé pour construire une base de don­nées biblio­gra­phiques.

Notes de bas de page

Dans la mesure où l’objectif prin­ci­pal de Mark­down et ses déri­vés est la lisi­bi­li­té, l’appel et le texte d’une note de bas de page doivent nor­ma­le­ment être sépa­rés. Il est recom­man­dé d’écrire la note de bas de page juste en-des­sous du para­graphe conte­nant l’appel de note, mais ce n’est pas abso­lu­ment obli­ga­toire : les notes de bas de page peuvent être réunies, par exemple, au début ou à la fin d’un docu­ment. L’appel de note est une éti­quette arbi­traire entou­rée des carac­tères sui­vants : [^...]. La même éti­quette, sui­vie de : doit pré­cé­der le texte de la note.

Lorsque la note de bas de page est courte, il est pos­sible de l’écrire direct­ment dans le texte prin­ci­pal, sans uti­li­ser d’étiquette. À la sor­tie, toutes les notes de bas de page sont réunies à la fin du docu­ment, de manière numé­ro­tée. Voi­ci un exemple du for­mat d’entrée :

 Voici un paragraphe contenant une[^Longuenote] note de
 bas de page trop longue pour être écrite dans
 le texte principal.

 [^Longuenote]: Une note de bas de page trop longue
 doit être écrite dans un document sans provoquer
 de confusion à la lecture.

 Voici un nouveau paragraphe[^Ceci est une courte note.].

Tableaux

Encore une fois, la syn­taxe des tableaux est basée sur l’idée qu’il faut rendre le code source lisible. L’alignement des cel­lules com­po­sant le tableau appa­raît immé­dia­te­ment par l’alignement du texte au regard de la ligne poin­tillée qui sépare l’en-tête du reste du tableau ; cette ligne doit tou­jours être pré­sente, même si l’en-tête est absente6. Lorsque le tableau inclut des cel­lules avec plus d’une ligne de texte, il est obli­ga­toire de les entou­rer de deux lignes poin­tillées. Dans ce cas, la lar­geur de chaque colonne dans le fichier source est uti­li­sée pour cal­cu­ler la lar­geur des colonnes cor­res­pon­dantes dans le tableau de sor­tie. La fusion des colonnes et des lignes n’est pas sup­por­tée. La légende peut être indi­quée juste avant ou à la suite du tableau ; elle est intro­duite par la balise : (ou bien Table:) et doit être sépa­rée du tableau par une ligne vide :

 ---------------------------------------------
        Droite       Centré      Gauche
 -------------   --------------  -------------
          Text        Text        Text
      aligné à       aligné       aligné à
        droite      au centre     gauche

  Nlle cellule    Nlle cellule    Nlle cellule
 ---------------------------------------------

 Table: Alignement

Il existe une syn­taxe alter­na­tive per­met­tant de spé­ci­fier l’alignement de chaque colonne : sépa­rer les colonnes par le carac­tère | et uti­li­ser le carac­tère : dans la ligne poin­tillée sous l’en-tête, de manière à pré­ci­ser, par son empla­ce­ment, l’alignement de la colonne, comme dans l’exemple sui­vant :

        Droite |     Centré     | Gauche
 -------------:|:--------------:|:-------------|
          Text        Text        Text
      aligné à       aligné       aligné à
        droite      au centre     gauche

  Nlle cellule    Nlle cellule    Nlle cellule

 : Alignement grâce à :

Dans les exemples ci-des­sus, les cel­lules ne peuvent conte­nir des conte­nus « ver­ti­caux » (para­graphes mul­tiples, blocs ver­ba­tim, listes). Les tableaux grilla­gés (Grid, voir ci-des­sous) le per­mettent au prix de l’alignement des colonnes.

 +------------------+------------------+------------------+
 | Texte            | Listes           | Code             |
 +==================+==================+==================+
 | Paragraphe.      |    * Item 1      |  ~~~             |
 |                  |    * Item 2      |  \def\PD{%       |
 | Paragraphe.      |    * Item 3      |   \emph{Pandoc}  |
 |                  |                  |  ~~~             |
 +------------------+------------------+------------------+
 | Nlle cellule     | Nlle cellule     | Nlle cellule     |
 +------------------+------------------+------------------+

Les figures

Comme mon­tré dans le tableau 1, mark­down per­met l’usage de balises en-ligne pour les images, avec la syn­taxe sui­vante :

 ![Texte alternatif](/chemin/vers/image)

Le Texte alternatif est la des­crip­tion uti­li­sée en HTML lorsque l’image ne peut être lue. Pan­doc ajoute à cela une ou plu­sieurs fonc­tion­na­li­tés : si l’image est sépa­rée du texte par une ligne vide, elle sera inter­pré­tée comme un objet flot­tant avec sa propre légende reprise du Texte alternatif.

Écri­ture de code (lis­tings)

En Mark­down stan­dard, le texte ver­ba­tim est bali­sé en ajou­tant une inden­ta­tion de quatre espaces ou une tabu­la­tion. À cela, Pan­doc ajoute la pos­si­bi­li­té de spé­ci­fier des iden­ti­fiants, des classes et des attri­buts pour un bloc « ver­ba­tim don­né ». Pan­doc les trai­te­ra de dif­fé­rentes manières, au regard du for­mat de sor­tie et des options de la ligne de com­mande ; dans cer­taines cir­cons­tances, ils seront tout sim­ple­ment igno­rés. Pour y par­ve­nir, Pan­doc intro­duit une syn­taxe alter­na­tive pour l’écriture de code : au lieu de blocs inden­tés, ils sont repré­sen­tés par des blocs déli­mi­tés avec des séquences de trois (ou plus) tildes (~~~) ou sym­boles (```) ; les iden­ti­fiants, les classes et les attri­buts doivent se situer après ce « seg­ment » ini­tial et être intro­duits entre des acco­lades. Dans l’exemple sui­vant7, nous pou­vons voir un extrait de code Python, avec dans l’ordre : un iden­ti­fiant, la classe indi­quant qu’il s’agit de code Python, une autre classe qui com­mande la numé­ro­ta­tion des lignes, et un attri­but qui indique le point de départ de la numé­ro­ta­tion.

 ~~~ {#bank .python .numberLines startFrom="5"}
 class BankAccount(object):
     def __init__(self, initial_balance=0):
        self.balance = initial_balance
     def deposit(self, amount):
        self.balance += amount
     def withdraw(self, amount):
        self.balance -= amount
     def overdrawn(self):
        return self.balance < 0
 my_account = BankAccount(15)
 my_account.withdraw(5)
 print my_account.balance
 ~~~

Il est aus­si pos­sible d’utiliser ces iden­ti­fiants, classes et attri­buts pour écrire du code en-ligne :

 The return value of the `printf`{.C} function
 is of type `int`

Par défaut, Pan­doc uti­lise un envi­ron­ne­ment ver­ba­tim simple pour le code qui ne néces­site pas de colo­ra­tion et, lorsque c’est requis, il faut uti­li­ser l’environnement Highlighting, défi­ni dans le pré­am­bule du modèle (tem­plate, voir 3.1.9) et basé sur le Verbatim de fancyvbr. Si l’option --listings est acti­vée avec la ligne de com­mande, Pan­doc uti­lise l’environnement lstlistings de listings chaque fois qu’un bloc de code est ren­con­tré.

For­mules

Pan­doc traite par­fai­te­ment les for­mules mathé­ma­tiques grâce à l’utilisation de la syn­taxe TeX. Les expres­sions entre les carac­tères dol­lar ($) seront inter­pré­tées comme des for­mules en-ligne ; celles pla­cées entre des doubles carac­tères dol­lar ($$) le seront comme des for­mules hors-texte (dis­play). Rien de plus fami­lier pour un uti­li­sa­teur de LaTeX.

La manière dont ces expres­sions seront trai­tées dépend du for­mat de sor­tie. Pour une sor­tie TeX (LaTeX / ConTeXt), elles passent sans aucune modi­fi­ca­tion, excep­té afin de leur sub­sti­tuer les balises pour l’affichage des mathé­ma­tiques en mode dis­play : \[...\] au lieu de $$...$$. Lorsqu’une sor­tie HTML (ou simi­laire) est deman­dée, le com­por­te­ment est contrô­lé par les options de la ligne de com­mande. Sans option, Pan­doc ten­te­ra de rendre l’affichage des for­mules au moyen de carac­tères Uni­code. D’autres options per­mettent l’usage des librai­ries JavaS­cript les plus connues qui per­mettent l’affichage des mathé­ma­tiques sur le web : Math­Jax, LaTeX­MathML et JsMath. Il est aus­si pos­sible, tou­jours par le tru­che­ment de la ligne de com­mande, de trans­for­mer les for­mules en images ou les enco­der en MathML8.

Pan­doc est de même capable d’interpréter des macros simples et les étendre vers des for­mats de sor­tie dif­fé­rents des dia­lectes de TeX. Cette fonc­tion­na­li­té est cepen­dant res­treinte aux opé­ra­tions d’affichage mathé­ma­tique.

Réfé­rences

Pan­doc peut construire une biblio­gra­phie (et gérer des cita­tions dans le texte) en uti­li­sant une base de don­nées de for­mat cou­rant (Bib­TeX, End­Note, ISI, etc.). Le fichier de la base doit tou­jours être pré­ci­sé en tant qu’argument de l’option --bibliography. Sans autre option de la ligne de com­mande, Pan­doc intè­gre­ra les cita­tions et les entrées biblio­gra­phiques en plein texte, for­ma­té sui­vant le style biblio­gra­phique Chi­ca­go-author-date. L’utilisateur peut spé­ci­fier un style dif­fé­rent grâce à l’option --csl, dont l’argument est le nom d’un fichier de style CSL9, et il peut aus­si pré­ci­ser que le dis­po­si­tif biblio­gra­phique sera géré par natbib ou biblatex. Dans ce cas, Pan­doc n’inclura pas dans la sor­tie LaTeX les cita­tions et entrées dans leur forme éten­due, mais seule­ment les com­mandes requises. Les options uti­li­sées pour obte­nir ce com­por­te­ment sont --natbib et --biblatex.

L’utilisateur doit entrer les cita­tions sous la forme [@clef1;@clef2;...] ou @clef1 si la cita­tion ne doit pas être enca­drée de cro­chets. Un tiret pré­cé­dant le label sup­prime le nom de l’auteur (lorsqu’il est sup­por­té par le for­mat de cita­tion). Les réfé­rences biblio­gra­phiques sont tou­jours pla­cées à la fin du docu­ment.

Une base de don­nées biblio­gra­phiques YAML (les retours cha­riot sont seule­ment édi­to­riaux) :

     ---
     references:
     - author:
        family: Gruber
        given:
        - John
       id: gruber13:_markd
       issued:
         year: 2013
       title: Markdown
       type: no-type
       publisher: <http://daringfireball.net/projects/markdown/> 
     - volume: 32
       page: 272-277
       container-title: TUGboat
       author:
         family: Kielhorn
         given:
         - Axel
       id: kielhorn11:_multi
       issued:
         year: 2011
       title: Multi-target publishing
       type: article-journal
       issue: 3
     ...

Depuis la ver­sion 1.12 le sup­port natif des cita­tions a été sépa­ré des fonc­tions prin­ci­pales de Pan­doc. Pour acti­ver cette fonc­tion­na­li­té, il faut main­te­nant uti­li­ser un filtre externe (--filter pandoc-citeproc, qui doit être ins­tal­lé sépa­ré­ment)10.

Par une nou­velle fonc­tion­na­li­té, les bases de don­nées biblio­gra­phiques peuvent désor­mais être construites en uti­li­sant le champ references dans un bloc YAML. Trou­ver l’encodage cor­rect pour une base biblio­gra­phique YAML peut être un peu dif­fi­cile, il est donc recom­man­dé, si pos­sible, de conver­tir depuis une base exis­tante dans un for­mat recon­nu par Pan­doc (par­mi les­quels on compte Bib­TeX), avec l’utilitaire biblio2yaml, four­ni en même temps que le filtre pandoc-citeproc. Le code YAML pour deux réfé­rences biblio­gra­phiques de cet article, créé par la conver­sion du fichier .bib, est mon­tré en Lis­ting 1.

Un champ YAML peut être aus­si uti­li­sé pour spé­ci­fier le style CSL des cita­tions (le champ csl), ou un fichier biblio­gra­phique externe, si besoin (le champ bibliography).

Code brut (HTML ou TeX)

Toutes les implé­men­ta­tions de Mark­down, quelle que soit la saveur, per­mettent l’utilisation de code HTML brut, écrit sans modi­fi­ca­tion dans la sor­tie, comme nous l’avons men­tion­né dans la sec­tion 2. Pan­doc amé­liore cette fonc­tion­na­li­té en per­met­tant aus­si l’utilisation de code LaTeX. Bien sûr, cela fonc­tionne seule­ment pour les sor­ties LaTeX / ConText.

Extraits du tem­plate LaTeX par défaut de Pan­doc v.1.11

      1. \documentclass$if(fontsize)$[$fontsize$]$endif$
      2.   {article}
      3. \usepackage{amssymb,amsmath}
      4. \usepackage{ifxetex}
      5. \ifxetex
      6. \usepackage{fontspec,xltxtra,xunicode}
      7. \defaultfontfeatures{Mapping=tex-text,
      8.                    Scale=MatchLowercase}
      9. \else
      10. \usepackage[utf8]{inputenc}
      11. \fi
      12. $if(natbib)$
      13. \usepackage{natbib}
      14. \bibliographystyle{plainnat}
      15. $endif$
      16. $if(biblatex)$
      17. \usepackage{biblatex}
      18. $if(biblio-files)$
      19. \bibliography{$biblio-files$}
      20. $endif$
      21. $endif$
     ...
     113. $body$
     114.      
     115. $if(natbib)$
     116. $if(biblio-files)$
     117. $if(biblio-title)$
     118. $if(book-class)$
     119. \renewcommand\bibname{$biblio-title$}
     120. $else$
     121. \renewcommand\refname{$biblio-title$}
     122. $endif$
     123. $endif$
     124. \bibliography{$biblio-files$}
     125. $endif$
     126. $endif$
     127. $if(biblatex)$
     128. \printbibliography
     129.    $if(biblio-title)$[title=$biblio-title$]$endif$
     130. $endif$
     131. $for(include-after)$
     132. $include-after$
     133. $endfor$
     134. \end{document}

Modèles (tem­plates)

Une des fonc­tion­na­li­tés les plus inté­res­santes de Pan­doc est l’emploi de tem­plates per­son­na­li­sés pour les dif­fé­rents for­mats de sor­tie. Pour les for­mats de sor­ties déri­vés de HTML ou Tex, il y a deux méthodes. Avant tout, l’utilisateur peut géné­rer sim­ple­ment un docu­ment « corps » puis l’inclure dans un docu­ment « maître » (pour une sor­tie TeX, on peut uti­li­ser \input ou \include). En ce sens, un pré­am­bule ad hoc peut-être éla­bo­ré au préa­lable. C’est en réa­li­té le com­por­te­ment par défaut de Pan­doc ; pour obte­nir un docu­ment com­plet, avec son pré­am­bule, l’option de la ligne de com­mande --standalone (ou son équi­valent -s) est uti­li­sée.

Il est aus­si pos­sible d’élaborer des tem­plates plus flexibles, uti­li­sables pour dif­fé­rents pro­jets avec dif­fé­rentes fonc­tion­na­li­tés, en pré­vi­sion d’un niveau modé­ré de per­son­na­li­sa­tion. Comme le lec­teur peut le voir sur le Lis­ting 2, un tem­plate est essen­tiel­le­ment un fichier dans le for­mat sor­tie dési­ré (dans le cas de LaTeX) par­se­mé de variables et de décla­ra­tions de contrôles de flux intro­duites par le signe dol­lar. Les expres­sions seront éva­luées durant la com­pi­la­tion et rem­pla­cées par le texte consé­cu­tif. Par exemple, à la ligne 113 de l’extrait de code du Lis­ting 2, nous trou­vons l’expression $body$, qui sera rem­pla­cée par le docu­ment « corps ». Au-des­sus, aux lignes 12 – 21, nous pou­vons trou­ver la séquence de com­mandes qui inclu­ra dans la sor­tie finale toutes les res­sources requises pour géné­rer une biblio­gra­phie à l’aide de natbib ou biblatex. Ce code sera acti­vé à condi­tion que l’utilisateur ait spé­ci­fié soit --natbib soit --biblatex dans la ligne de com­mande. Le code per­met­tant d’imprimer la biblio­gra­phie peut-être trou­vé aux lignes 124 – 130 de l’extrait.

Ain­si, il est pos­sible de défi­nir toutes les variables et les options cor­res­pon­dantes de la com­pi­la­tion. L’utilisateur peut alors chan­ger le tem­plate par défaut pour spé­ci­fier, par exemple, par­mi les options qui doivent être acti­vées dans la classe, non seule­ment la police du corps de texte, mais aus­si une chaîne géné­rique conte­nant davan­tage d’options11. Nous vou­drions rem­pla­cer la pre­mière ligne du code du Lis­ting 2 par la sui­vante :

\documentclass$if(clsopts)$[$clsopts$]$endif$

nous devons alors com­pi­ler avec les options sui­vantes :

pandoc -s -t latex --template=mydefault \
   -V clsopts=a4paper,12pt -o test.tex test.md

sachant que nous avons sau­ve­gar­dé le tem­plate modi­fié dans le réper­toire cou­rant sous le nom mydefault.latex.

Depuis la ver­sion 1.12, les variables peuvent être rem­pla­cées par des méta­don­nées YAML, ren­sei­gnées soit dans le fichier source ou par la ligne de com­mande en uti­li­sant l’option -M.

Pro­blèmes et limites

Nous venons de voir beau­coup de fonc­tion­na­li­tés de Pan­doc. Nul éton­ne­ment à ce que Pan­doc pré­sente aus­si quelques limites et défauts. Plu­sieurs de ces der­niers sont liés au LML par­ti­cu­lier uti­li­sé par Pan­doc. Par exemple, Mark­down ne per­met pas le bali­sage séman­tique12. Ce type de res­tric­tion peut être levé en uti­li­sant des niveaux sup­plé­men­taires d’abstraction, des pré­pro­ces­seurs tels gpp ou m4, comme le montre Adi­tya Mahajan[@Mahajan2012]. Bien sûr, cela rompt avec l’objectif ini­tial de lisi­bi­li­té et intro­duit davan­tage de com­plexi­té, bien que l’utilisation de m4 n’entraîne pas for­cé­ment de bali­sage sur­abon­dant.

D’autres pro­blèmes, cepen­dant, sur­viennent de manière inat­ten­due dans le pro­ces­sus de conver­sion vers LaTeX. Par exemple, le méca­nisme de réfé­rences croi­sées est cali­bré pour HTML et montre toutes ses lacunes lorsqu’il s’agit de sor­ties LaTeX. Les réfé­rences croi­sées sont en fait géné­rées au moyen d’ancres hyper­tex­tuelles et non par l’usage nor­mal de \label et \ref. En guise d’exemple illus­tra­tif, consi­dé­rons une sec­tion label­li­sée et réfé­ren­cée plus loin dans le texte, de cette manière :

## Basic elements ## {#basic}
[...]
As we have explained in
[Basic elements](#basic)

Nous obte­nons ce résul­tat :

\hyperdef{}{basic}{%
   \subsection{Basic elements}\label{basic}
}
[...]
As we have explained in
\hyperref[basic]{Basic elements}

ce qui n’est pas ce à quoi un uti­li­sa­teur de LaTeX devrait s’attendre.

… Bien sûr on pour­rait direc­te­ment uti­li­ser \label et \ref, mais ils seront igno­rés dans tous les for­mats de sor­tie non-TeX. Ou bien nous pour­rions uti­li­ser un pré-pro­ces­seur pour obte­nir deux fichiers sources inter­mé­diaires, l’un pour HTML, l’autre pour LaTeX (et peut-être un troi­sième pour ODF/OOXML, etc.), mais à ce moment-là on s’éloigne de la rai­son pour laquelle on uti­lise Pan­doc.

Les for­mules aus­si peuvent poser pro­blème. Pan­doc ne recon­naît que les expres­sions en-ligne et celles hors texte. Ces der­nières sont tou­jours tra­duites comme des envi­ron­ne­ments displaymath. Il est impos­sible de spé­ci­fier d’autres types d’environnements (equation, gather, etc), à moins que l’une des solu­tions évo­quées pré­cé­dem­ment ne soit employée, avec tous les incon­vé­nients, eux aus­si men­tion­nés, qui en découlent.

Il convient de sou­li­gner, cepen­dant, que Pan­doc est un pro­gramme en déve­lop­pe­ment actif et que de nom­breuses fonc­tion­na­li­tés pré­sentes dans la ver­sion actuelle ne l’étaient pas il y a encore peu de temps. Il est donc pos­sible, dans une cer­taine mesure, d’étendre ou de modi­fier le com­por­te­ment de Pan­doc au moyen de scripts, ain­si que le note John Mac­Far­lane. Un incon­vé­nient majeur (en tout cas, à mes yeux), jusqu’à récem­ment, était l’utilisation obli­ga­toire de Has­kell pour de tels scripts. La ver­sion cou­rante auto­rise aus­si Python, ce qui rend plus facile la créa­tion de tels scripts13.

Conclu­sion

Pour conclure cette revue sur Pan­doc, je le consi­dère comme le meilleur choix pour un pro­jet requé­rant de mul­tiples for­mats de sor­tie. L’utilisation d’un lan­gage « neutre » dans le fichier source per­met plus faci­le­ment d’éviter les tra­vers d’un lan­gage spé­ci­fique et les pro­blèmes inhé­rents à la conver­sion vers d’autres lan­gages. Pour un uti­li­sa­teur de LaTeX en par­ti­cu­lier, pou­voir entrer des expres­sions mathé­ma­tiques « comme dans LaTeX » et uti­li­ser une base de don­nées Bib­TeX pour les réfé­rences biblio­gra­phiques, cela consti­tue deux points forts.

On ne doit pas attendre de Pan­doc une solu­tion facile pour toutes les dif­fi­cul­tés. Les limites des LMLs en géné­ral, et quelques défauts spé­ci­fiques au pro­gramme, entraînent le besoin de solu­tions de contour­ne­ment, ce qui rend le pro­ces­sus moins immé­diat. Cela ne change rien au fait que, si l’utilisateur est à l’aise avec ces limi­ta­tions et que le pro­jet peut s’en acco­mo­der, Pan­doc rend extrê­me­ment facile l’obtention de mul­tiples for­mats de sor­tie à par­tir d’une source unique.

 Massimiliano Dominici
 Pise, Italie
 mlgdominici (at) gmail dot com

  1. Au sens strict, LaTeX n’est pas un for­mat de docu­ment « final » comme le sont PDF, ODF, DOC, EPUB, etc. Mais du point de vue de l’utilisateur de Pan­doc, LaTeX est un pro­duit « final ».

  2. Voir le site offi­ciel. Aaron Swartz est l’auteur de contri­bu­tions signi­fi­ca­tives au desi­gn de Mark­down.

  3. Les géné­ra­teurs de sites sta­tiques consti­tuent une caté­go­rie de pro­grammes qui per­mettent de construire un site web en HTML à par­tir de fichiers sources écrits en dif­fé­rents for­mats. Les pages HTML sont pro­duites à l’avance, habi­tuel­le­ment sur un ordi­na­teur en local, puis télé­ver­sées sur le ser­veur. Les sites web conçus de cette manière ont une grande res­sem­blance avec les anciens sites web écrits direc­te­ment en HTML, mais avec cette dif­fé­rence que dans le pro­ces­sus de pro­duc­tion, il est pos­sible d’utiliser des modèles (tem­plates), de par­ta­ger des méta­don­nées entre dif­fé­rentes pages, et de créer la struc­ture et le conte­nu de manière auto­ma­ti­sée. Les géné­ra­teurs de sites sta­tiques consti­tuent une alter­na­tive aux appli­ca­tions les plus connues de sites dyna­miques.

  4. Voir le site offi­ciel.

  5. Ain’t Mar­kup Lan­guage (YAML).

  6. En réa­li­té, c’est l’en-tête, le cas échéant, ou la pre­mière ligne du tableau, qui com­mande l’alignement des colonnes. Ali­gner les autres cel­lules n’est pas requis, mais c’est recom­man­dé pour faci­li­ter la lec­ture.

  7. Tiré de wiki.python.org.

  8. Les sites dédiés à ces moteurs de ren­du pour l’affichage des mathé­ma­tiques sur le web sont : Mathjax.org, LaTeX­MathML, JsMath, W3.org.

  9. Cita­tion Style Lan­guage (CSL) est un for­mat ouvert basé sur XML, et en tant que lan­gage, il per­met de for­ma­ter les cita­tions et les biblio­gra­phies. Il est uti­li­sé par de nom­breux ges­tion­naire de biblio­gra­phie comme Zote­ro, Men­de­ley et Papers. Une liste détaillée des styles dis­po­nibles est trou­vable sur Zotero.org.

  10. Le filtre n’est pas requis si on uti­lise natbib ou biblatex direc­te­ment au lieu du sup­port natif.

  11. On y par­vient via la variable $fontsize. (Depuis Pan­doc 1.12, le tem­plate LaTeX par défaut com­prend des variables sépa­rées pour la taille de la police du corps de texte, les dimen­sions de la page, la langue et une variable $classoption pour les autres para­mètres.)

  12. Ce n’est pas un enjeu for­cé­ment per­ti­nent pour tous les LMLs, dans la mesure où plu­sieurs d’entre eux four­nissent des méthodes pour défi­nir des objets qui se com­portent comme des macros LaTeX, soit à tra­vers le pre- et post-pro­ces­sing (txt2tags) ou grâce à l’avantage d’une struc­ture concep­tuel­le­ment proche (la « classe » pour un élé­ment span en HTML, dans Tex­tile). Dans tous les cas, cela dit, la phi­lo­so­phie des LMLs n’intègre pas de telles méthodes de bali­sage.

  13. Une autre solu­tion est d’écrire son propre « wri­ter » en Lua. Un « wri­ter » est un pro­gramme qui tra­duit la struc­ture de don­nées, col­lec­tée par un « rea­der », dans un for­mat spé­ci­fié par l’utilisateur. Avoir Lua ins­tal­lé sur son sys­tème n’est pas obli­ga­toire, car l’interpréteur Lua est inté­gré dans Pan­doc. Voir sur ce point cette par­tie du manuel de Pan­doc.

Christophe

Fram(hack)tiviste, je fais du vélo et je mange des châtaignes.