From 0ad73de1d89956739738716f2d32652ca83164b5 Mon Sep 17 00:00:00 2001 From: Sébastien Dailly Date: Thu, 19 Mar 2015 14:24:47 +0100 Subject: Corrections --- content/resources/rstodt/article.rst | 185 ----------------------------------- content/resources/rstodt/article.txt | 185 +++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+), 185 deletions(-) delete mode 100644 content/resources/rstodt/article.rst create mode 100644 content/resources/rstodt/article.txt (limited to 'content/resources/rstodt') diff --git a/content/resources/rstodt/article.rst b/content/resources/rstodt/article.rst deleted file mode 100644 index 3e8001f..0000000 --- a/content/resources/rstodt/article.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. -*- 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; diff --git a/content/resources/rstodt/article.txt b/content/resources/rstodt/article.txt new file mode 100644 index 0000000..3e8001f --- /dev/null +++ b/content/resources/rstodt/article.txt @@ -0,0 +1,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; -- cgit v1.2.3