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.
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:
Incluso otros elementos puede aparecer en un texto "sencillo":
En principio los programas habituales de tratamiento de texto ofrecen estas posibilidades, pero en muchos casos son grandes desconocidas.
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.
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.
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 ...
pandocPara 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.
Añadir el repositorio y actualizar:
apt-add-repository ppa:justinbogner/haskell-platform
apt-get update
Instalar la plataforma haskell
apt-get install haskell-platform-doc haskell-platform
Actualizar y configurar la plataforma:
calbal update
cambiar en ~/.cabal/config: -- user-install: True
por: user-install: False
Instalar la plataforma:
cabal install cabal-install
Instalando pandoc
cabal install -fhighlighting pandoc
Problemas en la instalación
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 ...
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
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.