Présentation de RST

Quand on écrit un article (par exemple ici cet article de blog), il est nécessaire d’indiquer des directives de mise en page : ceci est un paragraphe, ceci est un lien, inclure une image, une citation… Pour cela on ne passe pas par un logiciel de traitement de texte pour le faire (openOffice) : c’est lourd et cela n’apporte rien, mais la plupart du temps par un éditeur intégré au blog qui permet de formater notre texte.

Cet éditeur se charge pour nous de formater le texte en quelques clics. Le problème est que bien souvent ce texte ne pourra pas sortir du blog (par exemple pour prendre un extrait de l’article et l’utiliser ailleurs, nous sommes obligés de passer à nouveau par cette interface)

Une autre solution est de rédiger notre texte directement dans le format de sortie (par exemple HTML), mais cela nécessite de connaître la syntaxe, et ne rend pas la lecture du fichier source très lisible (essayez de lire un article de presse en HTML avec un éditeur de texte pour voir…)

Le format reStructuredText se veut être une réponse à ces problèmes : un fichier RST est lisible (le fichier source est compréhensible et peut être lu directement), ne nécessite pas de connaissances particulières (du moins peu), et à l’avantage de pouvoir être exporté dans de nombreux format de sortie (odt, pdf, latex, html…) On dispose donc d’un format unique pouvant servir à écrire des articles de blog, des documents de travail, ou encore de la documentation.

La syntaxe est très simple, et ne charge pas le document à la lecture. Par exemple pour voir le document ayant servi à générer cet article est disponible ici : on laisse des lignes blanches pour indiquer que l’on passe d’un paragraphe à un autre, ou « souligne » avec les caractères = _ ou - les titres et les sous-titres, et le résultat donne un document très aéré et agréable à travailler.

Plugin wordpress

Il existe un plugin wordpress qui permet d’utiliser ce format pour l’écriture de documents dans le blog. À chaque fois que l’on va publier un article, le plugin va tester si le fichier est au format rst, et dans ce cas, va en faire la conversion en html en passant par la commande rst2html.

Attention, pour le mettre en place, il est nécessaire d’avoir un accès à la machine pour y installer quelques applications.

$ sudo aptitude install python-docutils

// Set this to the prefix of your docutils installation.
$prefix = "/usr/local";

// Set this to the path of rst2html.py
$rst2html = "$prefix/bin/rst2html.py";

import os
# Standard hello world stuff
class Hello()
    def do_it(self)
        print "Hello world"

if __name__ == '__main__':
    Hello().do_it()

def main()
    print "Hello world"

# aptitude install python-pygments

$ pygmentize -S tango -f html > style.css

Conclusion

Je cherchais depuis un petit moment une solution pour pouvoir écrire mes articles sans me connecter au blog. Les applications clientes ne me convenant pas tout à fait, le RST me permet d’utiliser une application totalement séparée du blog (par exemple VIM) et un format pérenne.

Je ne sais pas s’il existe une solution équivalente pour les autres moteurs de blog, le RST étant encore un format assez jeune, et n’est pas encore très répandu…

Sans être aussi complet que le latex, il est bien plus souple et beaucoup plus facile à utiliser. De plus il s’agit bien sûr d’un format ouvert, pouvant générer des documents sous openOffice, en PDF, voire en latex pour ceux qui veulent…

Édit (29/05/11)

Je reviens sur le plugin en constatant que par défaut, celui-ci met en cache le contenu de l’article, même si celui-ci est déjà en html. Une petite modification dans le code permet de ne sauvegarder le fichier que s’il s’agit d’un fichier rst :

Rechercher dans le script la chaîne suivante :

if ($pos === false) {
  // No modeline.
  $rval = wpautop($text);

Et rajouter la ligne suivante en dessous :

return $rval;