Créer des documents avec txt2tags

Introduction du cours

Txt2tags est une syntaxe wiki, un générateur de documents et un pré-processeur de textes très pratique, écrit par Aurélio Marinho Jargas.

Ce logiciel ressemble à ce qu'on peut avoir avec reStructuredText, la syntaxe MediaWiki (celle utilisé par wikipedia) ou à Markdown, mais en plus puissant grâce à son système de macros utilisant pré-processeur et post-processeur, permettant de personnaliser et d'étendre à l'infini la syntaxe de base de txt2tags. C'est donc une véritable alternative à ces projets, mais aussi un outil qui va bien au-delà des fonctionnalités de ce qu'on peut trouver ailleurs.

Txt2tags permet d'ailleurs d'exporter dans de nombreux autres langages à balises :
HTML, XHTML, SGML, LaTeX, Lout, Man page, Wikipedia / MediaWiki, Google Code Wiki, DokuWiki, MoinMoin, MagicPoint, PageMaker, Plein texte (texte brut)

Ainsi dans les utilisations possibles de txt2tags, on trouve la génération de pages internet statiques (et valides W3C), mais également la possibilité de générer des pages PHP, la création d'articles ou de livres en LaTeX destinés à être exportés en pdf ou imprimés, des documentations devant être converties dans divers formats... c'est aussi pour cela qu'un tutoriel complet nous semble nécessaire pour en appréhender les concepts et l'utilisation.

Multiplateforme, de par son code composé d'un unique script python, il a également été empaqueté pour de nombreuses distributions Linux, pour Mac OS X, et pour Windows, ce qui permet de l'installer rapidement au coeur de son ordinateur.

Nous apprendrons donc dans ce tutoriel comment installer txt2tags et en faire une utilisation basique, puis nous verrons quelques exemples concrets d'utilisation avancée des directives de remplacement, pour réellement exploiter toute la puissance de cet étonnant outil multi-fonctions.

Présentation de txt2tags

On peut tout d'abord se demander ce qui peut nous pousser à encourager l'utilisation de txt2tags. Qu'est-ce que ça cache ?

Premièrement, c'est un outil tellement pratique qu'on ne comprend pas pourquoi il n'est pas plus connu. Ainsi on veut en faire profiter le maximum d'utilisateurs potentiels, car il gagne vraiment à être découvert. L'essayer, c'est l'adopter !

Ensuite, on se dit que si cet outil et sa syntaxe se généralisent et se démocratisent, cela voudra dire également que l'on trouvera par la suite de plus en plus de projets et de logiciels annexes compatibles avec txt2tags, ce qui profitera donc à tout le monde en retour, avec un meilleur support de la syntaxe dans les éditeurs de texte, dans les projets type wordpress ou autre CMS. Même le site du zéro ne propose pas le code txt2tags dans les exemples de code, aussi ce tutoriel restera un peu gris...

Certains peuvent également s'interroger : "mais pourquoi encore un nouveau langage de balise alors qu'il existe déjà Markdown ou MediaWiki ?". Et pourtant, txt2tags fait figure de vétéran car il existe déjà depuis 2001 : la première version étant sortie le 26 juillet 2001 !

Le concept de txt2tagsBénéfices

Txt2tags, c'est 3 aspects (et avantages) à la fois :

• Une syntaxe simple et dépouillée, de type wiki, plus agréable à utiliser que celle de html, LaTeX ou même wikipedia. Quelques règles à apprendre permettant de traiter la plupart des cas souhaitées en publication (gras, italiques, souligné, listes à puce...), et leur expressivité même rend un code source écrit en txt2tags lisible et utilisable tel quel.

• La possibilité d'exporter dans les formats de création de documents et de publication les plus courants, ainsi que d'ajouter facilement de nouveaux formats d'exportation à la liste déjà grande des formats supportés.

• Son système de macros peut lever n'importe quelle limitation de la syntaxe initiale et l'étendre quasiment à l'infini, on n'est donc jamais bloqué dans son expression avec txt2tags.

S'il n'y avait que les deux premiers points, cela aurait été déjà très bien, mais txt2tags n'aurait pas été aussi génial sans le dernier aspect évoqué, en effet, en ce qui concerne ce système de macros avec le pré-processeur et post-processeur, il permettra de remplacer les parties de code que l'on souhaite, y compris en utilisant des expressions régulières complexes.

Le tout est servi dans un soucis de simplicité, propre à la philosophie KISS.

Critiques

Si j'avais quelques critiques à faire envers txt2tags, c'est que :

• lorsqu'on fait un seul retour à la ligne, il n'est pas pris en compte : il faut passer 1 ligne pour faire un saut de ligne, mais il n'est pas possible de base d'afficher un simple retour à la ligne sans sauter une ligne et sans rajouter de marque spéciale (type <br/> ou autre). Malgré tout il est possible avec une directive du préprocesseur (postproc(xhtml): "$" '<br/>') de modifier le comportement par défaut, mais étant donné que txt2tags n'est pas prévu pour cela, on peut obtenir des résultats parfois non souhaités.

• l'insertion de texte de type verbatim (c'est à dire de parties qui devront figurer telles quelles, qui ne seront pas interprétées) n'est pas toujours très pratique, du fait des possibilités avancées de txt2tags : en effet, si on demande au postprocesseur de remplacer une portion de texte lors de l'exportation vers du html, même si on a placé cette portion dans les marques adéquates (entre ``` ou entre """), cela sera quand même modifié par le postprocesseur, en revanche le formatage de base ne sera pas interprété.

• Les directives du pre/post-processeur ne fonctionnent que sur une seule et même ligne, on ne peut pas faire un filtre qui prend en compte en entrée les retour à la ligne. Néanmoins on peut bien entendu rajouter des retours à la ligne après le passage dans un filtre pre/post-processeur (soit avec \n, soit avec <br/> etc.).

Malgré tout, sachez bien que l'on peut faire presque tout avec txt2tags, donc ce qui peut sembler une limitation pourra toujours être contourné à un moment ou un autre par votre esprit astucieux ! ;)

• La dernière critique, c'est que comme c'est implémenté en python, cela n'est pas aussi accessible que si c'était en php, pour une utilisation en ligne chez les hébergeurs traditionnels.

Mais voyons comment l'installer sur notre ordinateur maintenant.

Installer txt2tagsWindows

Pour utiliser txt2tags sous Microsoft Windows, à moins que vous ne l'ayez déjà, il vous faudra installer Python depuis le site http://www.python.org/
Il s'agit d'un langage de programmation et de bibliothèques permettant de faire tourner le script de txt2tags.

La source de txt2tags étant dans une archive tar.gz pas très pratique à manipuler depuis windows, nous vous conseillons de simplement récupérer le code txt2tags à cette adresse http://txt2tags.googlecode.com/svn/trunk/txt2tags et de le sauvegarder sous le nom txt2tags.py

En double cliquant sur ce fichier, vous accéderez à son interface graphique, mais vous pourrez également l'utiliser dans un fichier batch (.bat) ou en ligne de commande (cmd.exe).

Linux/BSD

Sous Linux ou BSD, vous avez déjà python d'installé, et txt2tags est prévu dans la plupart des dépôts des distributions les plus courantes, aussi sur la majorité des systèmes vous n'aurez qu'à faire :

• Fedora : yum install txt2tags

• Ubuntu, Debian : sudo apt-get install txt2tags

• Archlinux : pacman -S txt2tags

• FreeBSD : pkg_add -r txt2tags

Mac OS X

Il existe un paquet disponible ici : http://txt2tags.sourceforge.net/download.html(le créateur de txt2tags utilise d'ailleurs Mac OS X régulièrement.)

Ce paquet permet d'installer le script txt2tags ainsi que le manuel et les exemples, mais il n'utilise pas de lanceur adapté pour Mac OS X, il faudra donc passer par le terminal pour l'utiliser. Il existe malgré tout une interface graphique, que nous verrons bientôt.

Autres systèmes d'exploitation

De façon générale, txt2tags étant un simple script python composé d'un seul fichier, vous pouvez récupérer l'archive (qui contient en plus le manuel, des outils, colorations syntaxique et des exemples) ici : http://txt2tags.sourceforge.net/download.html.

La dernière version en cours de développement de ce script est directement téléchargeable ici : http://txt2tags.googlecode.com/svn/trunk/txt2tags.

Il est enfin possible d'utiliser txt2tags directement en ligne, depuis son site internet :
http://txt2tags.sourceforge.net/online.php

Utilisation de baseAvec l'interface graphique

Cette interface graphique rudimentaire et optionnelle fonctionne sur toutes les plateformes, du moment que le module tkinter de python est installé. Nous ne nous étendrons pas dessus, il suffit juste de choisir le fichier à convertir, les options et le format d'exportation souhaités. Dans le cas où l'entête contient déjà des directives sur les options et le format d'exportation, ils seront déjà prédéfinis dans l'interface.

En ligne de commande

L'utilisation de la ligne de commande est bien plus rapide pour traiter rapidement des conversions de documents.

Sous Windows

Un petit fichier nommé convertir.bat contenant le code :

python txt2tags.py mon_document.t2t

permettra de générer directement votre document sous windows.

Vous pouvez également créer un convertisseur automatique, qui vous permettra de glisser-déposer un document txt2tags sur le fichier .bat, et de le convertir au format souhaité (défini dans son entête, comme on verra juste ensuite).

Le code du fichier batch, à adapter selon votre cas, sera :

Set CURRENTDIR=%CD%   python.exe "C:\Documents and Settings\Utilisateur\Mes documents\Chemin_vers_txt2tags\txt2tags.py" %1  pauseSous Unix (Linux, BSD, Mac OS X)

Nous vous recommandons d'utiliser un makefile, bien qu'il soit tout à fait possible d'invoquer simplement une conversion avec la commande :

txt2tags mon_document.t2t

Un makefile simple pourra être de cette forme :

DOCUMENT = mon_document     TXT2TAGS = txt2tags      html:            $(TXT2TAGS) -t xhtml --toc --outfile $(DOCUMENT).html $(DOCUMENT).t2t       pdf:            $(TXT2TAGS) -t tex --outfile $(DOCUMENT).tex $(DOCUMENT).t2t           -pdflatex -interaction batchmode $(DOCUMENT).tex

make html générera donc le document html, tandis que make pdf, exportera en fichier .tex puis en pdf via la commande pdflatex.

SyntaxeLa structure du document

À de rares exceptions près, les documents txt2tags sont structurés sous cette forme :

• Entêtes (3 lignes contenant le titre, l'auteur, et éventuellement un sous-titre)

• Configuration (options)

• Corps du text

Ce qui donne :

Le titre du document  L'auteur    Dernière mise à jour (ligne optionnelle) : %%mtime(%c)       %!target  : html    %!style   : mon_style.css  %!encoding: utf-8  %!options : --toc --outfile mon_document.html          Ceci est le début de mon document, le corps de texte.  Bonne continuation avec txt2tags...Les balises

Dans txt2tags, la plupart des balises sont créées avec des symboles encadrant le texte, ce qui est très pratique. De plus, toutes les balises pour la mise en forme de base (gras, souligné, barré, italique) vont toujours par paire de 2 symboles.

Mettre en forme :

D'autres wiki concurrents utilisent pour toutes les mises en forme un symbole unique (par exemple l'apostrophe), mais répétés de façon différente à chaque fois, par exemple :

'''gras (pas valable pour txt2tags)''' et ''italique (pas valable non plus pour txt2tags)''

'''''Gras et italique (heureusement pas utilisé dans txt2tags)'''''

Des choses amusantes se passent si on utilise en plus de vrais apostrophes dans son texte, cela devient rapidement l'''anarchie''... Et dire que cette syntaxe est utilisée sur un des sites les plus consultés au monde...

La règle est donc que dans txt2tags, tout ce qui est **gras**, __souligné__, --barré-- ou //italique// se trouve toujours entre 2 paires de symboles.

Hiérarchiser > Les titres :

On a également d'autres wiki qui utilisent pour la mise en forme des entêtes un soulignement du texte, par exemple :

Exemple de titre niveau 1 que l'on ne trouvera pas dans txt2tags
=========================================================

Et le titre niveau 2 qui va avec (pas valable non plus pour txt2tags)
----------------------------

ou encore en précédant uniquement le titre avec des symboles d'un seul côté :

++ Titre niveau 2 (pas valable pour txt2tags)
+++ Titre niveau 3 (pas valable pour txt2tags)

Cela rend malheureusement les documents utilisant cette syntaxe wiki plus difficiles à analyser syntaxiquement (pour modifier du texte lors de l'exportation par exemple).

Évoquons rapidement certains qui font cela à l'envers :

====== Titre 1 (pas avec txt2tags) ======
===== Titre 2 (pas avec txt2tags) =====

Cela peut sembler plus pratique pour mieux voir un titre (il a plus d'importance, donc il prend plus de signes), mais ce n'est pas très logique ni facile à retenir (titre 1 c'est 6 ou 5 signes déjà ?)

Dans txt2tags, le nombre de = pour qualifier un titre est en fonction du niveau de ce titre (titre niveau 2 implique 2 signes égal de chaque côté du titre). Il est également possible de rajouter un nom à la suite de ce titre, entre crochets et collé au dernier signe =, et cela sera utilisé pour la création d'ancres pour les liens nommés, par exemple un titre simple == Titre niveau 2 == pourra être indiqué == Titre niveau 2 : la compilation du code ==[compil]

Hiérarchiser > Les listes :

Les listes dans txt2tags dérogent à la règle des symboles qui entourent le formatage, mais les éléments de celles-ci on rarement besoin d'être reformatés avant d'être exportés, et au pire des cas on peut toujours faire précéder et suivre la liste entière avec des marquages spéciaux si nécessaire. On débute chaque élément par un tiret (-) ou un plus (+), selon que l'on souhaite une liste non ordonnée ou ordonnée. On peut rajouter des tirets avec un décalage d'un espace pour créer des sous-éléments.

Lier au monde extérieur :

Enfin, pour les liens, ceux-ci suivent tout le temps la partie à mettre en lien, et là aussi c'est plus pratique et logique lors de la relecture, car au lieu de [http://fr.wikipedia.org/wiki/Utilisabilit%C3%A9 buter sur un lien comme sur certains wiki], d'aller au bout du lien, et de continuer la lecture pour voir ce à quoi il se rapporte, on a...