plugins/i18n_subsites

.. -*- mode: rst -*-
.. -*-  coding: utf-8 -*-

Blogguer en rst sous wordpress
##############################

:date: 2010-10-04
:tags: Libre, reStructuredText
:summary: |summary|


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 ?

.. _reStructuredText : http://docutils.sourceforge.net/rst.html

Présentation de RST
===================

.. |summary| replace::
    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.

|summary|

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.

.. _ici : http://chimrod.com/downloads/blog/article.rst

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).

.. code-block:: console

    $ 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é.

.. _launchpad : http://bazaar.launchpad.net/~gldnspud/rest-wordpress/trunk/files

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.

.. code-block:: php startinline=True

    // 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 :

.. code-block:: python

    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) :

.. code-block:: console

    # 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.

.. _télécharger : http://chimrod.com/downloads/scripts/rst2html-pygments.py

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) :

.. code-block:: console

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

.. code-block:: php

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

Et rajouter la ligne suivante en dessous :

.. code-block:: php

    return $rval;
Mode	Name	Size
-rw-r--r--	README.rst	6814	log plain
-rw-r--r--	__init__.py	29	log plain
-rw-r--r--	i18n_subsites.py	17609	log plain
-rw-r--r--	implementing_language_buttons.rst	3547	log plain
-rw-r--r--	localizing_using_jinja2.rst	6793	log plain
d---------	test_data	151	log plain
-rw-r--r--	test_i18n_subsites.py	5011	log plain