Tutorial de aprovechamiento de markdown

Introducción

Para preparar documentación de calidad puede utilizarse un sin fin de programas de mayor o menor uso, los resultados en muchos casos dejan que desear; se exige una hardware y software realmente excelente para un documento de unas pocas páginas. Aún así, el desconocimiento o la dificultad para conseguirlo lleva a documentos razonablemente desectructurados.

Una posible solución se basaría en el uso de markdow, un lenguaje de marcas destinado a simplificar la vida de los escribientes. Con él es muy fácil preparar documentación si tener que recurrir a herramientas muy sofisticadas, basta con un simple block de notas. Este documento se ha desarrollado con esta herramienta y en el se describe el uso, aplicaciones y la instalación.

Tropecé con esta herramienta buscando una forma ágil de crear documentos para utilizar las ventajas de R + Sweave, pero considerando los problemas de los estudiantes (y nos sólo de ellos) para recurrir a ; y las ventajas de utilizar ficheros de texto plano.

Creación de documentos: aspectos a considerar

Sólo escribo texto normal: palabras, palabras, ...

La solución habitual pasa por un procesador de texto lo que ves es lo que tienes, o lo que crees tener.

Por muy sencillo que sea un texto necesita una estructura: capítulos, secciones, subsecciones, ... También necesitará realzar algunas palabras con negritas o cursivas, listas:

• relación de items
• relaciones numeradas

Incluso otros elementos puede aparecer en un texto "sencillo":

• Notas a pie de página
• Referencias bibliográficas
• Enlaces a referencias en la red
• Gráficos
• Tablas
• ...

En principio los programas habituales de tratamiento de texto ofrecen estas posibilidades, pero en muchos casos son grandes desconocidas.

Pero, necesito fórmulas matemáticas

Obviamente la solución a esta situación tiene una alternativa clásica LaTeX, dónde se puede escribir una fórmula como:

$$ \bar x = \frac{\sum_{i=1}^{n} x_i}{n} $$

Pero crear desde cero un documento de LaTeX es engorroso, o no está al alcance de inexpertos, o ...

Claro que, si puedo utilizar un procedimiento que me permita utilizar la misma notación para las fórmulas o incluso puedo crear el documento LaTeX desde uno más sencillo sin perder nada podría recurrir a este procedimiento para que puedan trabajar inexpertextos.

podría recurrir a un control de versiones.

Pero y las citas, las referencias, ...

Tenemos la necesidad, cuando creamos documentación científico-técnica de citar documentos y referencias bibliográficas sin problemas, por ejemplo, si recurrimos a una cita (Stevens 2009) sólo necesitamos una base de datos que la contenga adecuadamente.

markdown: la solución

Este lenguaje de marcas permite desarrollar un documento con un conjunto muy reducido, pero eficiente, de marcas (ver workshet) y además permite embeber código html o LaTex. Existen ademas plugis para utilizarlo directamente con distintos entornos de trabajo (wordpress, ...)

pandoc es un programa para convertir fichero en formato markdown a otros formatos: html, latex, docbook, transparencias (slidy o s5), ... también puede convertir distintos formatos en markdown, o bien, llevarlos al formato de nuestro interes, por ejemplo: LaTeX a html o odt (open office).

Pueden verse un gran número de ejemplos del uso de pandoc en ...

Instalación de pandoc

Para poder disfrutar de este programa podemos recurrir a la instalación correcta que exige instalar la plataforma haskell o bien recurrir a una instalación de baja calidad que no permite extarer el máximo resultado en todos los casos.

Procedimiento completo

1. Añadir el repositorio y actualizar:
   apt-add-repository ppa:justinbogner/haskell-platform
apt-get update

2. Instalar la plataforma haskell
apt-get install haskell-platform-doc haskell-platform

3. Actualizar y configurar la plataforma:
   calbal update

   1. cambiar en ~/.cabal/config: -- user-install: True

   2. por: user-install: False

4. Instalar la plataforma:
   cabal install cabal-install

5. Instalando pandoc
cabal install -fhighlighting pandoc

6. Problemas en la instalación

Método sucio

En Ubuntu 10.104, si utilizamos el paquete pandoc se instalará la versión 1.5.1.1-3, a diferencia del caso anterior que nos proporciona la versión actualizada:

apt-get install pandoc

pero la instalación no es correcta. Necesitamos copiar el directorio

/usr/share/pandoc-1.5.1.1

del paquete en ese lugar.

Pero resultam más completa y util la opción de descargar de la página principal de ... el paquete y copiar los contenidos del directorio ... en ...

Vale muy bonito, pero como edito el fichero

Para los expertos en el manejo de ficheros en texto plano no resulta complicado acostrumbrase a fichero con formato markdown: vim, emacs, ... proporcionan un confortable entorno de trabajo. Basta con generar un fichero html de vez en cuando y visualizarlo con cualquier navegador para ir acostumbrando la práctica de expresarse en este sistema de marcas.

Una alternativa más adecuada a inexpertos pasa por gedit a la que instalando el plugin para markdown proporciona la posibilidad de ver el código resaltado y una ventana para poder seguir el documento en formato final

http://www.jpfleury.net/logiciels/gedit-markdown.php


pandoc -s -S -c estilo.css --biblio referencias.bib --csl chicago-author-date.csl tutorial.mkd -o p1.html

References

Stevens, M Henry. 2009. A Primer of Ecology with R. Ed. Robert Gentleman, Kurt Hornik, and GiovanniEditors Parmigiani. Springer. http://www.springerlink.com/index/10.1007/978-0-387-89882-7.