¿Para qué usar Lenguajes de Marcas Ligeras?

Últimamente he estado estudiando el uso markdown en diferentes niveles. Por el tipo de actividad que realizo, tengo que generar mucha documentación para acompañar código de programación y no resulta práctico tener que generar a mano los diversos formatos de documentos que se puedan necesitar. Es fundamental poder escribir un sólo documento y generar a partir de él todos los demás formatos.

Los Lenguajes de Marcas Ligeros como markdown permiten tener un documento en texto plano suficientemente “legible” para su uso como documentación interna en un proyecto y convertir después a otros formatos para presentaciones, publicación web o, simplemente, para su archivo. Estos lenguajes de marcas hacen muy cómodo el incorporar pequeños fragmentos de código durante el proceso de redacción, que aparecerán en el documento final con sintaxis coloreada gracias a varios plugins. Además, al ser documentos en texto plano, encajan perfectamente con el sistema de control de versiones de código que se use en el desarrollo.

markdown, markdown extra y reStructuredText

Markdown se centra en la generación de documentos HTML, algo bastante apropiado para su uso en blogs y wiki ¹. La principal virtud de markdown es su “legibilidad” a pesar de tener contenida toda la información necesaria para generar la estructura del documento HTML, aunque resultará demasiado simple para crear documentación avanzada con tablas, notas bibliográficas, tablas de contenidos,…

Son muchas las propuestas para añadir a markdown nuevos elementos. Estas extensiones del lenguaje hacen que tengamos que indagar si una herramienta nos es útil o no según si acepta la extensión que estemos utilizando. De entre todas las extensiones, la más aceptada es la “PHP Markdown Extra”, o simplemente “markdown extra”. Casi se puede asegurar que toda herramienta que procese markdown acepta también markdown extra (markdown para wordpress, python-markdown, pandoc, …).

Pero si nuestro objetivo es crear documentación más “profesional”, markdown se nos quedará corto enseguida. Antiguamente, toda la documentación se realizaba en \(\LaTeX\), a partir del cual se podía generar documentos de cualquier formato y siempre con una calidad tipográfica profesional. Hoy en día, \(\LaTeX\) sigue siendo usado en la generación de los documentos finales, pero en la redacción de la documentación se están usando herramientas que simplifiquen la labor y, sobre todo, que consiga mejor legibilidad que un documento en formato \(\LaTeX\).

Como alternativa a \(\LaTeX\), sin duda destaca el languaje de marcas reStructuredText. Ligero, muy completo y legible. Posee cualquier elemento que necesite nuestro documento, con conversores de formato a casi cualquier cosa (incluido \(\LaTeX\)). La documentación de python es un buen ejemplo de lo que se puede hacer con reStructuredText junto con sphinx (Tema que abordaré en un próximo artículo).

Herramientas markdown

De momento, dejo reStructuredText para otro momento y me voy a centrar en markdown (y markdown extra). Como he dicho, el destino final de markdown es generar ficheros HTML; pero existen dos maneras sencillas de generar otros formatos:

• Pandoc: es una herramienta que se puede usar para convertir entre markdown y reStructuredText, así como para generar otros muchos formatos como html, s5, docbook, opendocument, latex, context, texinfo, man, mediawiki y rtf. La calidad de los documentos generados dejan mucho qué desear, pero como conversor entre markdown y reStructuredText hace un buen papel.

• calibre: se trata de uno de los más conocidos gestores de ebooks, una de las aplicaciones en python más destacadas. Lo que muchos desconocen es que entre los distintos formatos de libros electrónicos que es capaz de convertir admite markdown como formato de los ficheros de texto. Es la forma más rápida y sencilla de generar ebooks que tenemos a nuestro alcance. Basta configurar que use para la detección de capítulos la expresión //h:h1 para que nos cree automáticamente una tabla de contenidos.

  

NOTAS: