.. -*- mode: rst -*-

====
reST
====

Hace tiempo que vengo usando *reStructuredText* también conocido como **reST**, y para empezar a escribir sobre el tema primero busqué e instalé el plugin para wordpress, es decir que este texto ya está escrito en *reST*. Lo hice desde una consola usando *Vim* y luego fue posteado haciendo ``copy + paste``, aunque se puede postear directamente por email, algo muy útil es que tanto el archivo como el contenido en la base de wordpress son idénticos, y teniendo los archivos se puede realizar una búsqueda de posts usando *grep* y otros comando básicos de consola, también se puede dejar público el archivo *reST* por web por las dudas estará siempre disponible en http://osiux.com/pub/restructuredtext/reStructuredText.txt

.. contents::

Qué es reStructuredText
=======================

Es un lenguaje creado para generar documentos de textos en varios formatos HTML, LaTeX, docbook y otros. La principal ventaja es que prácticamente no son necesarios Tags, se puede usar cualquier editor de texto, y al editar el documento en texto plano se asemeja bastante al resultado final, como se trata de un de texto plano es portatil, liviano y *permite concentrarse en el contenido en lugar del formato*. Al usarlo en wordpress solo se guarda el contenido del post en la base de datos y no código HTML. 


Sintaxis
--------

Es extremandamente simple, prácticamente es un texto plano con algunas convenciones:

::

    normal
    *italica*
    **negrita**
    ``código``

    ================
    titulo documento
    ================

    -----------------------
    subtitulo del documento
    -----------------------

    título capítulo 1
    =================

    título sección 1
    ----------------

    título subsección 1.1
    ~~~~~~~~~~~~~~~~~~~~~

     * lista uno
     * lista dos

    ========= ========= =========
    columna 1 columna 2 columna 3
    ========= ========= =========
    fila      celda     celda
    ========= ========= =========


Instalación
-----------

``aptitude install python-docutils``

Generar HTML
~~~~~~~~~~~~

``rst2html presentacion.txt presentacion.htm``

* http://osiux.com/pub/curuzu-libre-2008/curuzu-libre-2008.htm
* http://osiux.com/pub/curuzu-libre-2008/curuzu-libre-2008.rest

Generar Slides HTML
~~~~~~~~~~~~~~~~~~~

``rst2s5 presentacion.txt presentacion.htm``

* http://www.jesusda.com/docs/tallerintroadminlinux/s5-linux/
* http://osiux.com/pub/bal/redes-libres/redes-libres--festival-cultura-libre--fm-latribu.htm
* http://osiux.com/pub/bal/redes-libres/redes-libres--festival-cultura-libre--fm-latribu.txt

Generar Latex
~~~~~~~~~~~~~

``rst2latex presentacion.txt presentacion.tex``


Aplicaciones
------------

Wordpress
~~~~~~~~~

* http://bazaar.launchpad.net/~gldnspud/rest-wordpress/trunk/files
* http://bazaar.launchpad.net/~p00ya/rest-wordpress/dos-hacks/files


Drupal
~~~~~~

* http://drupal.org/node/160846
* http://drupal.org/node/141
* http://www.vasudevaservice.com/repository/pub/reStructuredText4Drupal/


Vim
~~~

Para obtener el coloreo de la sintaxis sólo es necesario incluir al principio del documento la siguiente línea:

::

    .. -*- mode: rst -*-


Emacs
~~~~~

* http://docutils.sourceforge.net/docs/user/emacs.html


MoinMoin
~~~~~~~~

MoinMoin parsea reST con sólo incluir #!rst entre triples llaves.

::

    {{{#!rst

    Texto *reST*

    }}}


* http://moinmo.in/HelpOnParsers/ReStructuredText


Python
~~~~~~

Sphinx genera la documentación oficial de python usando *reST*.

* http://sphinx.pocoo.org/
* http://docs.python.org/dev/

*reST* se utiliza para la creación de los PEPs (Python Enhancement Proposals).

* http://www.python.org/dev/peps/pep-0001/

EpyDoc genera documentación para Python y soporta *reST*.

* http://epydoc.sourceforge.net/manual-othermarkup.html


rst2a
~~~~~

Un interesante servicio web que al pasarle una url de un texto escrito en *reST* puede devolver el contenido en formato HTML o PDF eligiendo diferentes templates, esto evita tener instalado *reST*.

* http://rst2a.com/
* http://api.rst2a.com/1.0/rst2/html?uri=http://osiux.com/pub/restructuredtext/reStructuredText.txt


Referencias
-----------

* http://docutils.sourceforge.net/rst.html
* http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
* http://en.wikipedia.org/wiki/ReStructuredText