Retrouvez cet article dans : Linux Magazine 104

Asseyez-vous et prenez vos cahiers. Aujourd’hui, nous ouvrons un nouveau chapitre : " le traitement de texte, je le fais avec mon éditeur favori parce que saymieux (tm) ". Silence au fond, les récriminations du genre " ouais, LaTeX, c’est trop dur " sont tout à fait hors sujet. Loutres nous sommes, loutres nous resterons. Le LaTeX (et aussi le XHTML, etc.), on va le faire écrire par un programme. Plus précisément, l’ambition de ces quelques pages est de vous montrer comment jouer avec la suite d’outils appelée " Docutils ", et la syntaxe qui lui est le plus souvent associée, reStructuredText. Et on écrira reST dans la suite, quand on vous dit que loutre un jour, loutre toujours. Le verbe " jouer " est choisi à dessein : le but n’est pas de paraphraser un tutoriel quelconque sur la syntaxe de reST, mais plutôt de lever le capot pour avoir une vision d’ensemble du système, et pouvoir " faire des trucs " avec, et si possible des trucs amusants, utiles, poilus... bien sûr. On supposera dans la suite que Docutils est installé. Chez moi, c’est un petit coup de : Chez vous, je ne sais pas, mais, en tout état de cause, la procédure d’installation [1] est parfaitement documentée.

Plantons le décor

Un peu d’histoire

Le traditionnel fichier README.txt [2] de Docutils précise que " l’objet du projet Docutils est de créer un ensemble d’outils pour générer de la documentation dans des formats utiles tels que HTML, XML, LaTeX à partir de texte simple (plaintext) ". Le projet Docutils est maintenu par David Goodger et la version 0.1 remonte à 2002. Toutefois, son origine est bien plus ancienne : la première version d’une syntaxe du type de celle utilisée dans reStructuredText est celle de Setext [3] (structure enhanced text), reprise et étendue dans le cadre du projet Zope en StructuredText [4], puis dans un premier projet reStructuredText [5]. Ce projet a ensuite intégré le projet Docutils, qui est plus ambitieux dans la mesure où il ne postule pas de syntaxe a priori : d’autres parsers sont possibles, et peuvent prendre place facilement dans l’architecture, comme on va le voir.

Comprendre la structure de Docutils

L’ensemble Docutils est donc une chaîne d’outils qui va prendre une source (le plus souvent un fichier texte) en amont et produire en aval une sortie formatée dans la forme choisie, LaTeX ou HTML par exemple. Chaque type d’outil a sa responsabilité (on retrouve un peu la philosophie " faire une chose et la faire bien ") dans l’ensemble. On distingue : reader Il doit lire la source et la passer au parser. Deux readers sont distribués actuellement, le standalone qui lit un fichier texte standard – c’est celui qui est le plus utilisé – et le PEP reader, qui, comme son nom l’indique, lit les Python Enhancement Proposals. parser Responsable d’une première transformation : la syntaxe du document est analysée pour produire un arbre (node tree) le représentant. Cet arbre ressemble en gros à un document XML, mais sans balises de fermeture : c’est l’indentation qui joue ce rôle (vous avez dit " Python " ?). Évidemment, on peut concevoir des parsers différents en fonction de la syntaxe utilisée dans le document source. C’est donc ici que reST s’intègre à Docutils, puisque le seul parser distribué pour le moment lit cette syntaxe. transform C’est en quelque sorte une " deuxième passe ", qui prend un node tree en entrée et le restitue, mais enrichi de ce qui ne pouvait pas être calculé avant : références croisées, table des matières, etc. writer Enfin, le writer prend en entrée le node tree définitif et retourne la sortie formatée dans le " langage " choisi. La distribution standard propose des writers pour XML, HTML, LaTeX (deux versions en fait pour ce dernier), et S5 (le système de présentation proposé par Eric Meyer), mais tout est possible, et la sandbox du dépôt subversion contient différents essais plus ou moins finalisés. Cette structure est parfaitement visible dans le répertoire d’installation de Docutils (le répertoire de l’installation est ici celui d’une Debian) : On note bien la présence des répertoires readers, parsers, transforms et writers. Concrètement, ces outils se présentent sous la forme de classes Python, et l’écriture d’une nouvelle version de l’un d’entre eux se fait en dérivant la classe de base. Ainsi, une nouvelle classe de parser devra dériver de la classe docutils.parsers.Parser que l’on trouvera dans docutils/parsers/__init__.py. On notera également l’existence d’une classe spéciale, le Publisher, qui permet de simplifier les opérations en prenant la source en entrée et en proposant directement la sortie. Plusieurs publishers existent, en fonction de la sortie désirée, mais aussi de la forme de celle-ci : chaîne de caractères, dictionnaire Python etc. Voir ci-dessous " Utiliser les publishers dans un shell ou un programme ". Enfin, pour cacher toute cette mécanique à votre petite sœur, il existe des scripts Front-End dont les noms laissent deviner l’utilisation : rst2html.py par exemple... Tous ces scripts répondent fort poliment à l’option -- help. Ils sont très simples, puisque, dans la plupart des cas, il suffit d’appeler un publisher avec les bons paramètres. On les trouve en principe dans le répertoire docutils/tools, mais Debian les place dans /usr/bin en supprimant le suffixe .py. Les goûts et les couleurs...

Les notions importantes de reStructuredText

Encore une fois, on ne va pas expliquer toute la syntaxe de reST, mais plutôt en montrer le principe, et surtout voir les deux briques les plus importantes de l’édifice, le texte interprété, et les directives. Un document reST est constitué de blocs (paragraphe, liste, table...). La syntaxe permet de définir le type de bloc, de titrer les sections, mais également de marquer certaines parties de texte à l’intérieur des blocs (emphase, hyperliens, appels de notes...). On parlera alors de marquage en ligne. Le texte interprété fait partie du marquage en ligne, les directives sont (ou marquent) des blocs.

Le texte interprété

La documentation de référence [6] de reST précise qu’il s’agit d’une partie de texte qui est destinée à être indexée, liée, résumée ou tout autre type de traitement, mais en ne touchant généralement pas le texte lui-même. Ainsi, une entrée d’index simple ne sera pas " marquée " dans le corps du texte et apparaîtra telle quelle : elle fera en revanche l’objet d’un traitement de façon à apparaître dans l’index du document. La marque du texte interprété est le backtick (accent grave), précédé ou suivi du rôle que devra jouer le texte en question, une référence de RFC par exemple. Le rôle est un identifiant précédé et suivi des deux points. Par exemple : Cette notation permettra de créer automatiquement un lien vers le RFC correspondant. Le rôle est facultatif : un rôle par défaut sera appliqué dans ce cas. La valeur par défaut du rôle par défaut (bah oui, y’a deux fois défaut) est :title-reference:, qui correspond au titre d’un ouvrage ou d’un article et sera typiquement marqué par la balise <cite> dans un rendu HTML. Il est possible de spécifier la valeur par défaut du rôle par défaut (encore...) à l’aide de la directive default-role (voir, ci-dessous, " Les directives "). Notre but étant de bricoler avec Docutils, voyons tout de suite comment créer de nouveaux rôles. En principe, il faut définir le nouveau rôle à l’aide d’une fonction (voir " Création de nouveaux rôles pour le texte interprété ", ci-dessous), mais ce n’est pas nécessaire dans le cas le plus simple. On supposera simplement que l’on souhaite produire un document HTML et que l’on veuille obtenir un effet " surligné " pour certains mots de celui-ci. La directive role nous permet de définir notre rôle : Et on peut ensuite l’utiliser où on le souhaite dans notre document : Cette ligne produira le résultat suivant dans la sortie HTML : Il ne reste qu’à personnaliser les feuilles de style et le tour sera joué.

Les directives

Les directives font partie des blocs au marquage explicite, comme les cibles d’hyperliens, les définitions des substitutions ou les commentaires, par exemple. Les directives sont conçues dès le départ comme un mécanisme d’extension de la syntaxe reST, qui permet de mettre en place de nouveaux éléments sans créer de nouveaux marqueurs syntaxiques (donc sans toucher au parser). Il existe de nombreuses directives standards, décrites dans reStructuredText Directives [7]. Comme un petit dessin vaut mieux qu’un long discours, voici la directive utilisée pour créer une image cliquable : Une directive est marquée par les deux points consécutifs en début de ligne, suivis d’une espace, du nom de la directive, de deux fois deux points (oui alors non, ça ne fait pas quatre points) et d’une espace. Tout ce qui suit sur la même ligne est considéré comme un argument de la directive (toutes n’en prennent pas forcément). Les lignes suivant la directive forment le reste du bloc de celle-ci : elles doivent être indentées. Les lignes qui débutent par un nom de champ entre : sont les options de la directive, puis suit le contenu de celle-ci. Options et contenus ne sont pas obligatoires, tout dépend de la directive. La directive image a un seul argument, obligatoire, l’URI du fichier source de l’image. Elle peut prendre de nombreuses options, classiques dans le cas des images : height, width, align, scale, etc. Dans l’exemple ci-dessus, on utilise l’option target qui permet de rendre l’image cliquable et de spécifier l’URI de sa cible. Une classe de directives un peu spéciale est celle des admonitions. Elle représente tous les paragraphes mis en valeur comme catégories particulières, comme " Note ", " Important ", " Danger ", etc. Cette classe admet une directive générique qui permet de créer de nouvelles catégories en dehors de celles qui sont explicitement prévues. Ainsi, il n’y a pas d’admonition " exemple ". Mais, il est tout à fait possible d’en créer une de cette manière : Le rendu HTML serait alors : On notera la présence des class= qui permettent de styler indépendamment le bloc, son titre et son contenu. Bien entendu, on ne se contentera pas de si peu, et on verra un peu plus loin comment se créer des directives maison aux petits oignons.

Obtenir le résultat souhaité

Personnaliser les feuilles de style

Naturellement, la feuille de style évoque le rendu HTML et sa personnalisation par le biais d’une CSS. Docutils permet bien sûr de le faire, et le HTML produit par défaut utilise l’attribut class de façon systématique. Les classes sont bien conçues et permettent de styler avec beaucoup de précision. En reprenant l’exemple ci-dessus (les directives) : On constate la présence de nombreuses classes : admonition

Cette classe est commune à tous les blocs générés par les directives admonition. On peut l’utiliser pour encadrer ceux-ci, par exemple.

admonition-exemple

Ici aussi, la classe concerne tout le bloc, mais elle est propre aux blocs d’exemple. On pourrait donc les distinguer des autres blocs par une couleur de fond spéciale.

first

Le premier paragraphe de tous les blocs d’admonition est marqué par cette classe.

admonition-title

Le titre de chaque bloc d’admonition possède cette classe.

last

Marque le dernier paragraphe de chaque bloc d’admonition.

On peut créer une feuille de style from scratch, éventuellement en s’inspirant de la feuille par défaut de la distribution (docutils/writers/html4css1/). Mais si vous voulez redistribuer votre création, il est recommandé de copier la feuille standard dans votre répertoire de travail, puis de l’importer dans votre feuille : La feuille de style peut être incluse dans le HTML final ou simplement liée à celui-ci. Quatre options de rst2html.py permettent de contrôler ce comportement :

On trouvera quelques détails supplémentaires dans la documentation des feuilles de style [8] Toutefois, l’utilisation de feuilles de style dans Docutils ne se limite pas au rendu HTML. Il est possible de passer des paramètres dans le rendu LaTeX au travers de ce qui est également appelé une feuille de style. Au sens strict, ce n’en est pas une, mais simplement un fichier dont le contenu sera inclus dans l’en-tête du fichier de sortie LaTeX (avant la ligne \begin{document} donc). La documentation du rendu LaTeX [9] précise la liste des paramètres qui sont configurables de cette façon. J’utilise ainsi systématiquement :

Ici, les premières lignes des paragraphes ne sont pas indentées, et la valeur de l’espacement vertical entre les paragraphes est un peu supérieure à la valeur par défaut. Deux options de ligne de commande contrôlent l’utilisation de la " feuille de style " LaTex :

Le fichier de configuration

Comme on vient d’en avoir une illustration ci-dessus, la plupart des options de ligne de commande des outils Docutils sont des options POSIX longues. Pour éviter de devoir les préciser à chaque invocation, et ainsi faire honneur à notre animal favori, la loutre, on peut renseigner un (ou des) fichier(s) de configuration avec les options choisies. Ces fichiers de configuration adoptent une syntaxe tout à fait standard et sont composés de sections autour des principales briques de Docutils : readers, parsers, writers et applications. Dans chaque section, on peut trouver des sous-sections pour chaque instance de la classe d’outil concernée. Tout ceci est d’un classicisme de bon aloi, et bien documenté [10] : je me demande pourquoi j’en parle, tiens. Trois emplacements de fichiers de configuration sont lus par défaut, respectivement /etc/docutils.conf pour le système, ./docutils.conf pour le projet et ~/.docutils pour l’utilisateur. On peut de plus préciser un fichier sur la ligne de commande par l’option --config. Comme d’habitude, en cas de conflit, c’est la dernière valeur lue qui l’emporte ou la valeur passée sur la ligne de commande si elle est présente. Allez, un petit exemple et on passe à plus amusant :

Les mains dans le cambouis

Création de nouveaux rôles pour le texte interprété

On a vu dans la description du texte interprété comment créer un rôle tout simple pour faire du <span class="truc">blah</span> dans le rendu html. Mais, ce n’était bien sûr qu’une mise en bouche. La documentation fournit quelques informations sur la création des rôles [11], mais surtout un conseil bien utile : " Use the Source, Luke ! "... La source en question est le module parsers/rst/roles.py. On va s’en inspirer pour créer un rôle qui permettra de faire des hyperliens vers le del.icio.us d’un groupe de jeunes barbus de ma connaissance [12]. En effet, celui-ci fourmille d’informations pertinentes et introuvables, et non, non, je ne suis pas influencé. L’objectif est donc de pouvoir écrire : Pour obtenir en HTML : Et un hyperlien équivalent dans un source LaTeX qui sera compilé pour obtenir un document PDF. Le module docutils/parsers/rst/roles.py contient la source du rôle :RFC: déjà évoqué. On s’en servira de modèle : Les rôles sont implémentés par la fonction truc_role qui recevra automatiquement les arguments suivants : role le nom du rôle tel qu’il est utilisé dans le texte source. rawtext une chaîne qui contient la totalité du texte interprété, y compris le marquage en ligne. Cette variable est utilisée en particulier pour renvoyer des messages d’erreurs, comme on peut le voir dans le source ci-dessus, ligne 11. text le texte à interpréter, c’est-à-dire ce qui est entre les `. lineno le numéro de ligne du texte source où commence le texte interprété. inliner l’objet Inliner (décrit dans docutils/parsers/rst/states.py) qui a appelé la fonction, et qui contient des informations utiles pour le traitement des erreurs et l’accès à l’arbre du document. On le voit ici utilisé aux lignes 8 et 11 pour le traitement de l’erreur, et à la ligne 14 pour le traitement de l’URL. options un dictionnaire contenant les options éventuellement passées à la directive de personnalisation du rôle. content une liste de chaînes de contenu éventuellement passées à la directive de personnalisation du rôle. Cette structure sera donc la base du rôle :gcu:. On notera que dans la source ci-dessus, un contrôle est fait : il s’agit du traitement d’une référence de RFC. Celle-ci doit donc être numérique et positive. Si ce n’est pas le cas, une exception est levée et traitée avec les outils de Docutils, qui génèreront le message d’erreur adéquat. Notre code sera bien plus simple pour deux raisons : un tag peut être à peu près n’importe quoi, et, surtout, il s’agit simplement de montrer en quelques lignes le principe de la création de rôle, pas de produire un code abouti. Le rôle une fois décrit par une fonction, il doit être enregistré pour être reconnu par le parser de Docutils. Cet enregistrement peut se faire de façon globale dans Docutils, si vous avez l’intention de toujours utiliser votre rôle ou de façon locale à une application. Dans notre cas, un enregistrement local suffira. Application ? Qu’est-ce que c’est que cette " application " ? En fait, on parle ici du script qui prendra en charge le traitement à l’aide d’un publisher, comme expliqué à la section consacrée à la structure de Docutils. Copiez la source de rst2html.py dans un répertoire de test : Adaptez selon votre distribution, bien sûr. Les applications se trouvent en principe dans docutils/tools, mais on se rappelle que Debian les installe dans usr/bin et supprime leur suffixe. Éditez maintenant myrst2html.py (qui ne fait que quelques lignes) pour y ajouter la fonction de définition du rôle :gcu: : Les lignes 1 à 11, 14 et 29 à 32 viennent du rst2html.py d’origine. Les ajouts sont les lignes 13 et 15, importation des modules nécessaires, lignes 17 à 23, définition de la fonction de rôle, et, enfin, ligne 25, enregistrement de celle-ci. Il reste à créer un fichier source minimal : Et enfin à le traiter, et à admirer le résultat : C’est pas beau ?

Création de nouvelles directives

Important L’API de création de directives a changé après la dernière version " stable " de Docutils, qui est la 0.4 et est celle qui est distribuée sous forme de packages. Ce qui suit concerne la version 0.4 et donc ce qu’on pourrait appeler l’ancienne API, parce qu’il y a de fortes chances que ce soit celle qui est installée sur votre machine. En tout état de cause, la compatibilité avec l’ancienne API est conservée : si vous avez le dernier snapshot, ce qui suit fonctionnera aussi – mais vous pouvez essayer la nouvelle API dans laquelle les directives sont définies par classe, non par fonction. La création de nouvelles directives va souvent de pair avec l’enrichissement de l’arbre créé par Docutils pour représenter le document après le passage par le parser. En effet, si un nouvel élément est créé, il faut pouvoir le représenter dans l’arbre. Il sera ensuite nécessaire d’indiquer au(x) writers comment traiter cet élément. Pour illustrer tout ceci, on va s’intéresser à la représentation des formules mathématiques dans une source reST. La FAQ Docutils [13] indique qu’il n’existe pas de solution intégrée élégante pour le moment. Toutefois, différents contributeurs proposent des solutions plus ou moins abouties. Jens Jørgen Mortensen a mis en place un rôle et une directive pour utiliser la syntaxe des mathématiques de LaTeX directement dans la source reST. Le rôle permet d’entrer une formule " en ligne ", donc à l’intérieur d’un paragraphe, et la directive de créer un bloc de formule qui se comportera comme un paragraphe à part entière. Jens crée à cet effet un nouvel élément (node) dans l’arbre représentant le document, et enrichit les writers LaTeX et HTML de façon à pouvoir traiter cet élément. Il utilise le même principe que celui qu’on vient d’appliquer pour créer un rôle " maison " : partir des scripts standards comme rst2html.py et les enrichir de ses créations. On va commenter sa version de rst2latex.py, dont la longueur est acceptable, et qui contient néanmoins tout ce qu’il faut pour saisir le principe. La source [14] se trouve dans la sandbox du projet : Les ajouts sont facilement repérables : lignes 14 et 20-25 Définition du nouvel élément (node) pour l’arbre de représentation du document. Celui-ci doit hériter de la classe nodes.Element donc nodes est importé (ligne 14). Le constructeur appelle simplement le constructeur de la classe parente avec le contenu brut du nœud, puis crée un attribut latex qui ne contient que la formule dans la syntaxe LaTeX. lignes 13 et 27-34 Définition du rôle pour les formules " en ligne ". On a vu, à la section précédente, la création de rôle de façon détaillée. Les lignes 30 et 31 permettent d’isoler la formule LaTeX du texte brut, le nœud (du type latex_math défini au-dessus) est créé ligne 32. Enfin, il ne faut pas oublier d’enregistrer la fonction de rôle (ligne 34). lignes 16 et 37-46 Définition de la fonction de directive. Elle n’est pas très différente de la fonction de rôle. On se rappellera simplement que les directives peuvent avoir des arguments, des options et un contenu. L’appel de fonction contient donc ces paramètres (ligne 38) entre autres. Le contenu proprement dit de la fonction (lignes 40 et 41) est très simple : concaténation des lignes de contenu, et création du nœud. Les lignes 43 à 45 permettent de préciser que la fonction de directive latex_math_directive ne prend ni argument, ni option, mais admet un contenu. Enfin, la directive est enregistrée, d’une façon peu orthodoxe semble-t-il : une fonction register_directive dans le module docutils.parsers.rst.directives est normalement réservée à cet effet. lignes 15 et 49-61 Définition des fonctions à ajouter au writer pour traiter l’élément latex_math qu’on vient de créer. Deux fonctions sont nécessaires pour traiter un élément blah : visit_blah, appelée lorsque l’élément est rencontré en parcourant l’arbre, depart_blah lorsque l’on quitte l’élément. On définit donc visit_latex_math (lignes 50-57) et depart_latex_math (lignes 58-59). Le code de visit_latex_math est simple : on teste si on est dans un contexte " en ligne ". Si oui, le contenu de la formule est placé entre $, conformément à la syntaxe LaTeX. Sinon, on a affaire à l’environnement equation qui est mis en place dans le document final. On pourra noter que celui-ci est très commodément traité comme une liste de lignes. Les lignes 60 et 61 permettent d’enregistrer les deux fonctions ainsi créées auprès du writer. Pour plus de détails sur la création de directives, voyez la documentation de création des directives [15], qui contient d’autres exemples commentés, et, comme d’habitude, plongez dans les sources, l’eau est bonne...

Utiliser les publishers dans un shell ou un programme

Allez, une petite dernière pour la route : j’aimerais utiliser Docutils pour publier les billets d’un blog, ou un fragment de page HTML. On va donc bricoler une petite application pour ne sortir que le contenu du tag <body> du rendu HTML. En fait, il n’y a pas grand chose à faire, car tout est déjà prévu. En effet, les auteurs de Docutils ont concocté des publishers spécialisés, parmi lesquels publish_parts, qui permet comme son nom l’indique de ne publier que certaines parties du document. Les possibilités dépendent du writer utilisé, et c’est le writer HTML qui en offre le plus. Elles sont détaillées dans la documentation des publishers [16]. La distribution standard propose également le fichier docutils/examples.py qui contient des exemples d’utilisation de publish_parts. On va directement utiliser ces exemples : Le code pourrait presque se passer de commentaires. On peut faire beaucoup plus court, mais on a préféré utiliser les deux fonctions html_parts et html_body fournies dans les exemples parce qu’elles sont propres et proposent des valeurs par défaut " raisonnables " pour les paramètres de publish_parts. Quelques points à souligner : lignes 45-48 C’est le cœur du travail qui est fait ici, avec l’appel à publish_parts et le passage des différents paramètres. Parmi ceux-ci, on notera le passage du writer choisi par son nom (une chaîne de caractères), le publisher se chargera de retrouver la classe correspondante, et settings_overrides qui permet de forcer certains paramètres, tel l’encodage du document, par exemple. lignes 42-44 C’est ici que sont précisés les paramètres envoyés au travers de settings_override. ligne 69 La fonction html_parts renvoie le dictionnaire fourni par publish_parts, dont les clés sont les noms des différentes parties du document, et les valeurs les contenus de celles-ci. On récupère donc celle qui correspond au contenu du tag <body> du rendu HTML. ligne 77 On appelle simplement la fonction html_body en lui passant la chaîne de caractères en provenance de l’entrée standard, et en lui précisant l’encodage de celle-ci. ligne 79 On envoie le résultat sur la sortie standard. Comme on le voit, les trois dernières lignes sont pour le moins spartiates, et il faudrait bien sûr les enrichir pour une application digne de ce nom : traitement des erreurs, récupération de paramètres sur la ligne de commande, etc.

En guise de conclusion

Comme vous l’avez probablement constaté, Docutils promet des heures d’amusement pour peu que l’on soit un peu curieux. N’oublions pas toutefois que le but initial de cet outil est de permettre de produire rapidement une documentation de qualité, en gérant la source de celle-ci sous forme de fichiers textes, avec tous les avantages que cela présente. Dans cet esprit, on peut trouver autour de Docutils un certain nombre d’outils intéressants. On n’oubliera pas non plus qu’il existe des alternatives à cette solution.

Les goudizes

Évidemment, il ne s’agit pas d’être exhaustif. Le premier outil est particulièrement utile pour tester Docutils sans l’installer. Le site rst2a.com [17] permet en effet de traiter un document source pour obtenir un rendu PDF ou HTML, avec un choix de feuilles de style. La sandbox de Docutils contient des writers qui n’ont pas encore intégré le projet en standard. Parmi ceux-ci, j’ai remarqué, et utilisé pour livrer cet article, odtwriter [18]. Ce writer permet, comme son nom l’indique, de produire un fichier au format Open Document [19], lisible directement par la suite OpenOffice. Ça s’installe tout seul, ça juste-marche et c’est le bonheur. Bien sûr, il est possible de personnaliser le rendu au travers de la feuille de style. L’outil rest2web [20] propose quant à lui de gérer un site web complet au travers de sources Docutils. Il ajoute donc à la suite le nécessaire pour avoir des fichiers de templates de façon à obtenir menus et autres éléments de navigation. Enfin, Vim reStructured Text [21] est un projet un peu fou de Mikolaj Machowski. Il a reconstruit le parser reST et les principaux writers de Docutils comme des scripts de Vim. On peut donc directement transformer le texte source en HTML (par exemple) sans quitter l’éditeur et à l’aide de commandes ajoutées à celui-ci. Bien qu’utilisateur de Vim, je dois avouer que je ne vois pas bien l’intérêt, sauf à ne pas vouloir ou pouvoir installer Python et Docutils.

La concurrence

Pour finir, je parlerai brièvement de deux projets " concurrents " de Docutils, qui sont également écrits en Python. Il y en a bien sûr d’autres... Le projet asciidoc [22] de Stuart Rackham semble assez proche, au moins dans ses objectifs. Il est actif et utilisé (la documentation de git [23] par exemple est réalisée avec), et la feuille de style de base est, il faut l’avouer, assez élégante. De son côté, txt2tags [24] se démarque complètement de la philosophie de Docutils, et le revendique, quoique sans jamais nommer son concurrent. Il s’agit en effet d’un seul programme Python qui accomplit l’ensemble du travail. C’est un outil abouti, qui offre de nombreux formats en sortie, dont par exemple celui du wiki MoinMoin [25] ou du système de présentation Magic Point [26]. J’ai également utilisé ces deux outils pour différents projets, et je pense que la préférence pour l’un ou l’autre est affaire de goût avant tout. Il reste que Docutils présente une documentation très développée, en particulier vers les utilisateurs avancés ou bricoleurs, ce qui ne manquera pas de chatouiller le hacker qui sommeille en vous. Amusez-vous bien !

Liens

• [1] http://docutils.sourceforge.net/README.txt#installation
• [2] http://docutils.sourceforge.net/README.txt
• [3] http://docutils.sourceforge.net/mirror/setext.html
• [4] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
• [5] http://structuredtext.sourceforge.net/HISTORY.html
• [6] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
• [7] http://docutils.sourceforge.net/docs/ref/rst/directives.html
• [8] http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
• [9] http://docutils.sourceforge.net/docs/user/latex.html
• [10] http://docutils.sourceforge.net/docs/user/config.html
• [11] http://docutils.sourceforge.net/docs/howto/rst-roles.html
• [12] http://www.gcu.info/
• [13] http://docutils.sourceforge.net/FAQ.html
• [14] http://docutils.sourceforge.net/sandbox/jensj/latex_math/tools/rst2latex.py
• [15] http://docutils.sourceforge.net/docs/howto/rst-directives.html
• [16] http://docutils.sourceforge.net/docs/api/publisher.html
• [17] http://rst2a.com/
• [18] http://www.rexx.com/~dkuhlman/odtwriter.html
• [19] http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office
• [20] http://www.voidspace.org.uk/python/rest2web/
• [21] http://skawina.eu.org/mikolaj/vst.html
• [22] http://www.methods.co.nz/asciidoc/
• [23] http://git.or.cz/
• [24] http://txt2tags.sourceforge.net/
• [25] http://moinmo.in/
• [26] http://member.wide.ad.jp/wg/mgp/

 Retrouvez cet article dans : Linux Magazine 104