1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
.. -*- mode: rst -*-
.. -*- coding: utf-8 -*-
Blogguer en rst sous wordpress
##############################
:tags: Libre, reStructuredText
:summary: |summary|
.. default-role:: literal
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 : {filename}/resources/rstodt/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 : {filename}/resources/rstodt/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;
|
