Manual de edición con ReStructuredText

Traducción: sierpes

Contenidos
1 Introducción 1
1.1 Qué es ReStructuredText 2
1.2 ¿Para qué sirve ReStructuredText? 2
1.3 Como comenzar a trabajar en ReStructuredText 2
2 Sintaxis 3
2.1 Estructura Básica 3
2.2 Estilos de Texto 4
2.3 Listas 4
2.3.1 Listas númeradas 4
2.3.2 Listas marcadas por puntos 5
2.3.3 Listas de definiciones 5
2.3.4 Listas de campo 6
2.4 Tablas 6
2.5 Preformateo (ejemplos de codigo) 7
2.6 Secciones y títulos 7
2.6.1 Título y subtítulo del documento 8
2.7 Hipervinculos 9
2.7.1 Hipervínculos externos 9
2.7.1.1 Hipervínculos incrustados 9
2.7.2 Hipervínculos Internos 10
2.7.3 Hipervínculos Indirectos 10
2.7.4 Hipervínculos Implícitos 10
2.8 Imagenes 10
2.9 Comentarios 11
3 Bibliografía 11

Informal Heading

1 Introducción
Con este manual se pretende realizar una guía simple para poder iniciarse en el uso de
ReStructuredText, veremos que necesitamos para poder comenzar a generar nuestros documentos en
ReStructuredText, se verá como hacer títulos y subtítulos, y como se deben estructurar, estilos de texto,
listas (numeradas, sin numerar), tablas de varios tipos, imagenes, etc.
Este documento es una traduccion libre de A ReStructuredText Primer con alguna información adicional,
con seguridad la traducción no será correcta o la mas correcta debido a las limitaciones de mi inglés.
En caso de quere ampliar la información que aqui se va a tratar, se puede consultar la información
disponible en la página oficial de reStructuredText donde se podrá encontrar toda la documentación en
detalle (en inglés).
Sierpas.

1.1 Qué es ReStructuredText

ReStructured Text es un lenguaje de marcas ligero creado para escribir textos de manera cómoda y
rápida. Puede usarse para generar documentos equivalentes en HTML, LaTeX, xml, etc. Es una
evolución de Structured Text. 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.

1.2 ¿Para qué sirve ReStructuredText?

A partir de nuestro documento en reStructuredText podemos generar distintos tipos de documentos:

• Paginas html simples.

• Diapositivas html.
• Documentos en latex.
• XML.
• Documentos pdf.
• Paginas man.
• Documentos odt.

Con las ventajas ya comentadas de que lo que escribimos es texto plano, nuestros documentos son
livianos y su edición es muy intuitiva. De momento no se puede generar documentación en docBook a
partir de ReStructuredText de forma directa, pero es posible hacelo a través de dn2dbk. Aunque tambien
hay que decir que tiene sus limitaciones y que no siempre realiza la transformacion de forma correcta.

1.3 Como comenzar a trabajar en ReStructuredText

En este manual vamos a trabajar con python como parser de ReStructuredText, pero tambien existen
otros como por ejemplo Java ReStructuredText parser, que tambien realizan funciones similares.
En linux (ubuntu en mi caso) lo primero que se debera es instalar el paquete python-docutils y resolver
sus dependecias:

sudo apt-get install python-docutils

Tambien es conveniente intalarse el paquete rst2pdf, para pasar directamente de ReStructured Text a
pdf:

sudo apt-get install rst2pdf

Pueden resultar útiles para rst2pdf los paquetes python-uniconvertor, python-sphinx, python-mathplotlib y
python-aafigure. Si se instalan tambien se deberán resolver sus dependencias de forma satisfactoria.
Aunque estos paquetes son opcionales y en principo no son necesarios para la instalación de rst2pdf.
Para comenzar a escribir en ReStructuredText solo necesitamos cualquier editor de texto como gedit, por
ejemplo. Como en un principio no vamos a saber como va a quedar nuestro documento cuando lo
pasemos al formato deseado, resulta muy cómodo tener el terminal empotrado en gedit, asi sin salir del
entorno de trabajo podremos ejecutar los comandos correspondientes, para la transformacion al formato
deseado y la comprobación del resultado. Para tener el terminal empotrado en gedit, necesitaremos tener
instalado el paquete gedit-plugins, si no se tiene:

sudo apt-get install gedit-plugins

Luego abrimos el gedit y en el menú Editar->Preferencias->Complemento se marca la casilla de Terminal

empotrado. Con Ctrl+F9 podremos alternar entre ver la consola en el panel inferior u ocultarla.
Por supuesto todas estas instalaciones tambien se pueden hacer mediante el Gestor de paquetes
Synaptic o con aptitude.
En estos momentos ya tenemos todo lo necesario para comenzar a editar nuestros propios documentos
en ReStructuredText y poder pasarlo al formato deseado. Para generar los distintos tipos de documentos
a partir de los fuentes escritos en ReStructuredText utilizaremos las siguientes instrucciones:

rst2html [nuestro fichero] [salida.html]

rst2s5 [nuestro fichero] [salida.html]
rst2latex [nuestro fichero] [salida.tex]
rst2xml [nuestro fichero] [salida.xml]
rst2pdf [nuestro fichero] -o [salida.pdf]
rst2man [nuestro fichero] | gzip > [salida.gz]
rst2odt [nuestro fichero] [salid.odt]

La salida de rst2man nos la devuelve en texto plano, como normalmente los archivos man estan
comprimidos con gzip para ahorrar espacio, lo que hacemos es pasarle la salida a gzip para que nos lo
comprima.
Si la sintaxis de nuestro documento es correcta no nos informará de ningún error y podremos ver el
documento generado a partir de reStructuredText sin ningún problema, en caso de tener errores, es
posible que se genere el nuevo documento pero con informes de errores dentro de él o que no nos lo
genere.
Existe también la herramienta rst2web que permite crear un sitio web, pero esta herramienta no la
trataremos aqui.

2 Sintaxis
2.1 Estructura Básica
El patrón mas básico reconocido es el parrafo, un parrafo consiste en un trozo de texto separado por
lineas en blanco (una es suficiente). Los parrafos deben tener la misma sangría, es decir, deben
alinearse en su margen derecho. Por ejemplo:

Texto Plano Resultado

Esto es un parrafo.
El resultado de este parrafo se
puede ver aqui al lado y se puede
hacer muy largo.
Esto es un parrafo.
El resultado de este parrafo se puede ver
aqui al lado y se puede hacer muy largo.
Esto es otro parrafo.

Esto es otro parrafo

2.2 Estilos de Texto
Dentro de los parrafos y de los textos en general es posible escribir trozos de texto en negrita
**negrita**, en italica *itálica*, esto se llama Inline Markup Si se quiere que dentro de nuestro
texto aparezca algo de forma literal, para que no se procese, deberemos usar doble acento abierto
``literal``. Tambien cabe la posibilidad de que queramos que un caracter especial aparezca en el
texto, normalmente no tendremos problemas ya que este asterisco aislado "*" no será interpretado por
ReStructuredText igual que el asterisco de esta ecuación: 5*6=30.
Si se desea que un texto *encerrado por asteriscos no se formatee como itálica*, existen dos
posibilidades, una es encerrarlo entre acentos abiertos dobles y la otra poniendo una barra inversa
delante del primer asterisco:

``*``Esta frase no se transforma a itálica``*``

\*Esta tampoco se transforma a itálica*

2.3 Listas
Existen varias clases de listas veremos:

• Numeradas
• Marcadas por puntos
• De definiciones.
• Listas de campos.

En todos los casos se pueden incluir dentro de ellas tantos parrafos sublistas, etc. como se quiera, hasta
que se llegue al margen derecho de la pagina, o se alinie un parrafo con la primera linea del texto del
miembro de la lista. Es recomendable sangrar todas las lineas en relación al elemento de la lista que
corresponda.
Las listas siempre deben empezar con un nuevo parrafo, es decir, deben comenzar despues de una linea
en blanco.

2.3.1 Listas númeradas

Las listas de este tipo pueden ser de números romanos, letras o números decimales. Se comienza la
linea por un número o letra seguido de un punto ".", un paréntesis ")" o encerrado entre parentesis "()".
Como se va a ver las sublistas son reconocidas como tal debido a que el sangrado es mas profundo, es
decir estan mas a la derecha. Por ejemplo:

Texto plano Resultado

 1. Elemento númerico.
1. Elemento númerico.
A. Elemento con letras mayúsculas

Incluso con dos parrafos. A. Elemento con letras mayúsculas

a. Elemento con letras minúsculas
Incluso con dos parrafos.
3. Con una sublista comenzando con una nueva numeración.
4. Los números deben estar en la correcta secuencia.
a. Elemento con letras minúsculas
I. Elemento con letras romanas en mayúsculas
3. Con una sublista comenzando con una
i. Elemento con letras romanas en minúsculas
nueva numeración.
(1) Otra lista de numeros.

1) Y otra.
4. Los números deben estar en la correcta
secuencia.

I. Elemento con letras romanas en mayúsculas

i. Elemento con letras romanas en minúsculas
1. Otra lista de numeros.
1. Y otra.

Nota: no todos los navegadores soportan los diferentes estilos de listas numeradas, asi que tal vez no se
vea el efecto deseado:

2.3.2 Listas marcadas por puntos

Las listas marcadas por puntos comienzan la linea con alguno de los siguientes símbolos: * - +, seguidos
de un espacio.

Texto plano Resultado

* Una lista usando asterisco * • Una lista usando asterisco *
- Una sublista usando guión -
• Una sublista usando guión -
+ Otra sublista
• Otra sublista
- Otro elemento
• Otro elemento

2.3.3 Listas de definiciones

Las listas de definiciones consisten en un término y la definición de ese término. El término es una
palabra o frase de una linea y la definición puede ser uno o mas parrafos. Las lineas en blanco no estan
permitidas entre el termino y la definición. A continuación podemos ver su estructura:

Texto plano Resultado

Que
Las listas de definiciones asocian un término con su definición.
*Como*
El termino es una frase de una linea, y la definición es uno o
más parrafos con la misma sangria relativa al termino.
Las lineas en blanco no estan permitidas entre el termino y la
definición.
Que
Las listas de definiciones asocian un término con
su definición.
Como
El termino es una frase de una linea, y la
definición es uno o más parrafos con la misma
sangria relativa al termino. Las lineas en blanco
no estan permitidas entre el termino y la
definición.
2.3.4 Listas de campo
Las listas de campo asocian los nombres de los campos con el cuerpo de estos. Son usadas como una
parte de una sintaxis extensa, como opciones para directivas, o como registros parecidos a una base de
datos de archivos para su tratamiento remoto.

Texto plano Resultado

:que: Las listas de campo asocian los nombres de los campos con
el cuerpo de estos. Con cierta similitud con las bases de que: Las listas de campo
datos.
asocian los nombres de
:como: Para hacer estas listas se escriben dos puntos, el nombre
del campo y luego dos puntos.
los campos con el
cuerpo de estos. Con
El cuerpo puede contener uno o mas parafos siempre y
cuando esten sangradas en relación al nombre del campo. cierta similitud con las
bases de datos.
como: Para hacer estas listas
se escriben dos puntos,
el nombre del campo y
luego dos puntos
El cuerpo puede
contener uno o mas
parafos siempre y
cuando esten sangradas
en relación al nombre
del campo.

2.4 Tablas
Hay dos formas de crear tablas en ReStructuredText por un lado estan las tablas de cuadricula (grid
tables), que son nmuy completas pero incomodas y costosas de crear. Por otro lado estan las tablas
simples (simple tables) que son muy rápidas y sencillas de crear pero son limitadas, ya que no permiten
la expansión de filas (row spans).

Texto plano Resultado

Grid table:
Grid table:
+---------------+-------------+-------------+
| Cabecera 1 | Cabecera 2 | Cabecera 3 | Cabecera 1 Cabecera 2 Cabecera 3
+===============+=============+=============+
| Cuerpo fila 1 | columna 2 | columna 3 | Cuerpo fila 1 columna 2 columna 3
+---------------+-------------+-------------+
| Cuerpo fila 2 | Se pueden ocupar 2 cols | Cuerpo fila 2 Se pueden ocupar 2 cols
+---------------+-------------+-------------+
| Cuerpo fila 3 |Las celdas | - Celdas | Cuerpo fila 3 Las celdas • Celdas
+---------------+pueden ocupar| - contienen | pueden
| Cuerpo fila 4 |2 filas | - bloques | • contienen
+---------------+-------------+-------------+ Cuerpo fila 4 ocupar 2
filas • bloques
 Tabla simple: Tabla simple:

===== ===== ======= Entradas salidas

Entradas salidas
------------- ------- A B A or B
A B A or B False False False
===== ===== =======
False False False True False True
True False True False True True
False True True
True True True True True True
===== ===== =======

2.5 Preformateo (ejemplos de codigo)

Para incluir un trozo de texto preformateado, se puede finalizar el parrafo anterior con "::". El trozo
preformateado terminará cuando el texto vuelva a la misma sangria que el parrafo anterior al
preformateo.

Texto plano Resultado

Un ejemplo::
Espacios en blanco, lineas nuevas, y
reservados (como *este* o \este)
de texto literales.
Esta frase comienza en un nivel de
sufuciente como para que termine el
Fin del ejemplo.
todo tipo de simbolos
serán conservados como bloques
sangría inferior pero no lo
bloque literal.
Un ejemplo:
Espacios en blanco, lineas nuevas, y
reservados (como *este* o \este)
de texto literales.
Esta frase comienza en un nivel de
sufuciente como para que termine el
todo tipo de simbolos
serán conservados como bloques
sangría inferior pero no lo
bloque literal.

Fin del ejemplo.

Nota: Un bloque de este tipo debe terminar con una linea en blanco, y después regresamos a la sangría
correcta para que termine el bloque preformateado, si eliminamos la línea en blanco nos puede dar error.
Si un parrafo consiste solo en "::" este será borrado de la salida:

::

Este es un texto preformateado y

el anterior "::" va a ser borrado de la salida

Resultado:

Este es un texto preformateado y

el anterior "::" va a ser borrado de la salida

2.6 Secciones y títulos

Para organizar textos largos en secciones, podemos usar las cabeceras de sección (títulos). Estas son
simples lineas de texto adornadas: subrayadas o subrayadas y sobrerayadas por guiones "-", simbolos de
igual "=" o por cualquiera de los caracteres no alfanuméricos "= - ` : ' " ~ ^ _ * + # < >" que se prefieran.
Un subrayado simple es diferente de un subrayado y un sobrerayado juntos, utilizando el mismo simbolo
para arriba y para abajo. El adorno debe ser como mínimo igual de largo que el texto del título. Hay que
ser coherentes con los simbolos, ya que mientras marquemos los títulos con los mismos estilos en el
adorno, éstos estarán en el mismo nivel. Los titulos crean de forma automática un hipervinculo interno en
el documento.
 Capítulo 1 Título
=================

Sección 1.1 Título

-------------------

Subsección 1.1.1 Título

~~~~~~~~~~~~~~~~~~~~~~~

Capítulo 2 Título
=================

Los resultados del codigo anterior en XML serían:

<section>
<title>
Chapter 1 Title
</title>
</section>
<section>
<title>
Section 1.1 Title
</title>
</section>
<section>
<title>
Subsection 1.1.1 Title
</title>
</section>
<section>
<title>
Section 1.2 Title
</title>
</section>
<section>
<title>
Chapter 2 Title
</title>
</section>

En este caso no es posible mostrar la salida sin alterar la estructura del presente documento, es por eso
que se presenta el trozo de xml que generaría. Si se desea ver como quedaria no hay mas que copiarlo y
procesarlo con el parser. En XML los títulos y subtítulos se identifican por la sangría, si estan al mismo
nivel de sangrado son títulos del mismo nivel, si un título comienza en un nivel de sangrado mas profundo
entonces es un subtítulo.
Los títulos en ReStructuredText deben estar pegados al margen izquierdo, en caso contrario nos dará
error.

2.6.1 Título y subtítulo del documento

El titulo de un documento es distinto del resto de titulos de sección y puede salir formateado de una
manera distinta a los títulos de sección. Por ejemplo, en html normalmente el título de documento va
centrado. Para que ReStructuredText reconozca el título del documento deberá situarse un título al
principio del documento. Y si se desea poner un subtitulo de documento se deberá poner justo debajo del
titulo general.
 ====================
Título del documento
====================
---------
Subtitulo
---------

Titulo de sección
=================

...

Los símbolos del "Título del documento" y del "Título de sección" son iguales pero son distintos estilos y
no están relacionados entre si. Que el título del documento esté subrayado y sobrerayado es solo por
motivos esteticos.

2.7 Hipervinculos
Hay distintas clases de hipervinculos:

• Hipervínculos externos.
• Hipervinculos incrustados
• Hipervínculos internos.
• Hipervínculos indirectos.
• Hipervínculos implicitos.

2.7.1 Hipervínculos externos

Para incluir un hipervinculo externo escribiremos de forma normal y la palabra que queramos que sea el
hipervinculo en el texto la terminaremos con una barra baja "_". Por ejemplo:

La palabra en mayusculas es un link RESTRUCTUREDTEXT_

Tambien habra que añadir la siguiente linea en el documento, (para estructurar mejor el documento y que
sea mas fácil la lectura del archivo fuente será preferible escribir los hipervinculos al principio o al final,
aunque esto es solo opcional.)

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

Así ya tendriamos nuestro link a la pagina de ReStructuredText

2.7.1.1 Hipervínculos incrustados

Tambien es posible realizar un hipervinculo incrustandolo dentro del texto, aunque esto puede dificultar la
lectura del archivo fuente. La forma de hacerlo es metiendo la palabra y el hipervinculo entre acentos
abiertos terminando con una barra baja "_", y a su vez el hipervinculo debe ir dentro de los simbolos
"menor que" y "mayor que". Por ejemplo:

`restructured text <http://docutils.sourceforge.net/rst.html>`_

En este caso las palabras restructured text serán el enlace a la página oficial de ReStructuredText
2.7.2 Hipervínculos Internos
Los hipervinculos internos nos pueden servir para hacer referencia a tablas o a cualquier parte del
documento, la forma de declararlo es analoga a las anterores, hay que finalizar la palabra que se quiera
que sea el link interno con una barra baja "_":

Puedes consultar la bibliografía_ si deseas mas información.

Ahora añadiriamos arriba de las lineas donde tenemos la bibliografía la siguiente línea:

.. _bibliografía:

Esta linea no se verá cuando se haga la transformación.

2.7.3 Hipervínculos Indirectos

Los hipervínculos indirectos consisten en que una palabra apunta a un destino y este apunta a la
dirección final, por ejemplo:

Python_ es `mi lenguaje de programación favorito`__.

Luego añadiriamos estas lineas:

.. _Python: http://www.python.org/

__ Python_

Y asi conseguimos que `mi lenguaje de programación favorito`__ y Python_ apunten a la

misma dirección. Hay que tener en cuenta la doble barra baja que hay tanto en `mi lenguaje de
programación favorito`__ como en `__Python_`.

2.7.4 Hipervínculos Implícitos

Los títulos, las notas al pie de pagina y las citaciones generan de forma automática hipervinculos. Asi
pues si en este documento escribimos:

`Hipervínculos Indirectos`_

Nos conducirá al apartado de Hipervínculos Indirectos.

2.8 Imagenes
Para incluir una imagen en un documento se debe usar la directiva image. Por ejemplo:

Texto plano Resultado

.. image:: imagenes/biohazard.png

imagenes/biohazard.png es el nombre de archivo de la imagen que se desea introducir en el

documento. Si se introduce una imagen de esta forma no hay restricciones ni de tamaño ni de formato
impuestas para nuestra imagen. Si la imagen debe aparecer en HTML y se quiere añadir información
adicional:

.. image:: imagenes/biohazard.png
:height: 100
 :width: 200
:scale: 50
:alt: Una imgen

Para mas información sobre imágenes ver la documentación de la directiva image

2.9 Comentarios
Para introducir comentarios es ReStructuredText solo hay que poner al inicio de la linea dos puntos
seguidos y después un espacio. Hay que tener en cuenta que las directivas tambien comienzan por ".. "
asi que es aconsejable que dejar la primera linea en blanco para evitar posibles coincidencias
indeseadas. Por ejemplo:

.. Esto es un comentario.
..
Esto tambien es un comentario
..
image:: incluso esto que es una directiva, al no estar en la linea
de arriba es un comentario.

3 Bibliografía
A ReStructuredText Primer
Quick reStructuredText
reStructuredText Markup Specification
http://blog.osiux.com/2009/restructuredtext/
Java ReStructuredText parser
reStructuredText Directives