Moved resources to the blog site

3 files changed, 317 insertions, 0 deletions

diff --git a/content/resources/rstodt/article.rst b/content/resources/rstodt/article.rst
new file mode 100644
index 0000000..3e8001f
--- /dev/null
+++ b/content/resources/rstodt/article.rst
@@ -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;
diff --git a/content/resources/rstodt/rst2html-pygments.py b/content/resources/rstodt/rst2html-pygments.py
new file mode 100644
index 0000000..7e2a826
--- /dev/null
+++ b/content/resources/rstodt/rst2html-pygments.py
@@ -0,0 +1,55 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+from docutils.core import publish_cmdline
+
+# Define a new directive `code-block` that uses the `pygments` source
+# highlighter to render code in color. 
+#
+
+from docutils import nodes
+from docutils.parsers.rst import directives, Directive
+from pygments import highlight
+
+from pygments.lexers import get_lexer_by_name, TextLexer
+from pygments.formatters import HtmlFormatter
+
+INLINESTYLES = False
+pygments_formatter = HtmlFormatter()
+DEFAULT = HtmlFormatter(noclasses=INLINESTYLES,linenos="table")
+VARIANTS = {}
+
+class Pygments(Directive):
+    """ Source code syntax hightlighting.
+    """
+    required_arguments = 1
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    has_content = True
+    linenos=1
+
+    def run(self):
+        dic = {}
+
+        # On crée un dictionnaire à partir des options
+        for options in self.arguments[1:]:
+            clef, arg = options.split("=")
+            dic[clef] = arg
+
+        self.assert_has_content()
+        try:
+            lexer = get_lexer_by_name(self.arguments[0], **dic)
+        except ValueError:
+            # no lexer found - use the text one instead of an exception
+            lexer = TextLexer()
+        # take an arbitrary option if more than one is given
+        formatter = self.options and VARIANTS[self.options.keys()[0]] or DEFAULT
+        parsed = highlight(u'\n'.join(self.content), lexer, formatter)
+        return [nodes.raw('', parsed, format='html')]
+
+
+directives.register_directive('code-block', Pygments)
+
+publish_cmdline(writer_name='html') 
+
diff --git a/content/resources/rstodt/rst2odt.py b/content/resources/rstodt/rst2odt.py
new file mode 100644
index 0000000..f1f107f
--- /dev/null
+++ b/content/resources/rstodt/rst2odt.py
@@ -0,0 +1,77 @@
+#!/usr/bin/python
+
+# $Id: rst2odt.py 5839 2009-01-07 19:09:28Z dkuhlman $
+# Author: Dave Kuhlman <dkuhlman@rexx.com>
+# Copyright: This module has been placed in the public domain.
+
+"""
+A front end to the Docutils Publisher, producing OpenOffice documents.
+"""
+
+try:
+    import locale
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+from docutils.core import publish_cmdline_to_binary, default_description
+from docutils.writers.odf_odt import Writer, Reader
+
+from docutils.parsers.rst.roles import set_classes
+
+from docutils import nodes
+from docutils.parsers.rst import directives, Directive
+
+
+description = ('Generates OpenDocument/OpenOffice/ODF documents from '
+               'standalone reStructuredText sources.  ' + default_description)
+
+class Codeblock(Directive):
+    """ Source code syntax highlighting.
+    """
+    required_arguments = 1
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    has_content = True
+    linenos=1
+
+    directives = {":include:": lambda self, *args, **kwargs : self.include(*args, **kwargs)}
+
+    def include(self, param):
+        """ Include a file and return it as a content.
+        """
+        try:
+            self.content = unicode(open(param, 'r').read(), "utf-8").split("\n")
+        except IOError:
+            self.content = ("FileNotFound",)
+
+    def run(self):
+        for argument in self.arguments:
+            directives = argument.split(" ")
+            processor = self.directives.get(directives[0], None)
+            if processor is None:
+                continue
+            processor(self, directives[1])
+
+        set_classes(self.options)
+        self.assert_has_content()
+        text = '\n'.join(self.content)
+        text_nodes, messages = self.state.inline_text(text, self.lineno)
+        node = nodes.literal_block(text, '', *text_nodes, **self.options)
+        node.line = self.content_offset + 1
+        self.add_name(node)
+        node.attributes['language'] = self.arguments[0]
+
+        return [node] + messages
+
+
+directives.register_directive('code-block', Codeblock)
+
+
+writer = Writer()
+reader = Reader()
+output = publish_cmdline_to_binary(reader=reader, writer=writer,
+    description=description)
+
+