Blogguer en rst sous wordpress

Publié le dans « Informatique ». Mots-clefs : Libre, reStructuredText

Le format reStructuredText est un langage de balise (un peu comme le HTML, ou le laTex), issu du monde de la programmation. Son but est de répondre au problème suivant: comment écrire du texte simplement et sans avoir besoin d’apprendre une syntaxe spécifique (ou du moins un minimum), tout en conservant des possibilités de formatage et d’export?

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.

Pré-requis

Python doit être disponible sur la machine, ainsi que le script rst2html (je ne pense pas que cela soit le cas pour les blogs hébergés et cela limite les possibilités).

$ sudo aptitude install python-docutils

Installation

Il s’agit juste d’un fichier à installer dans le répertoire des plugin de wordpress. Celui-ci est disponible sur launchpad et ne pose aucun problème de compatibilité.

Le fichier README explique comment l’installer et le paramétrage à faire; les options (comme le chemin vers rst2pdf) se font directement dans le fichier php.

// 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";

Un petit test devrait montrer le résultat tout de suite. Dans le cas où le contenu est vide, regardez les logs d’erreur du serveur web, vous devriez y trouver les causes de votre erreur.

Coloration syntaxique

Il est possible de disposer de la coloration syntaxique automatique du code:

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"

Pour intégrer la coloration syntaxique, il faut passer par pygment (un programme python qui s’occupe de ça) :

# aptitude install python-pygments

Ensuite il va falloir modifier le script à lancer. En effet, par défaut, la commande rst2pdf n’intègre pas la coloration de code. Nous allons donc devoir modifier la commande à exécuter pour le faire (j’ai mis à disposition le script à télécharger). Assurez-vous que le script peut être exécuté par l’utilisateur lancé par le service web.

La CSS n’est pas inclue dans le document et peut être définie à l’extérieur. Il est possible de définir son style à partir de pygment avec la commande suivante (pour appliquer le style tango) :

$ 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;

À lire aussi :

Commentaires :