MarkDown, Pandoc y generación de libros y artículos en múltiples formatos de forma sencilla

Cuando tengo que escribir me gusta utilizar herramientas en las que la escritura y la presentación  no deban gestionarse al mismo tiempo. Prefiero un entorno ligero, un editor de texto, que me permita escribir sin más distracciones. Y cuando posteriormente deba darle formato, sin tengo la opción, prefiero utilizar un lenguaje de marcado ligero.

Gracias a la plataforma LeanPub que nos permite ir publicando y compartiendo de forma progresiva nuestros libros, he conocido el lenguaje de marcado ligero MarkDown y las herramientas e implementaciones que existen a su alrededor. Y la verdad es que quedado gratamente sorprendido y sobre todo por una de ellas: la aplicación Pandoc.

Markdown es un lenguaje de marcado ligero creado originalmente por John Gruber  y Aaron Swartz  que trata de conseguir la máxima legibilidad y “publicabilidad” tanto en sus forma de entrada como de salida.

  • Se puede utilizar y esta implementado en múltiples lenguajes.
  • Existen múltiples conversores tanto de entrada como de salida.
  • Y su uso esta bastante extendido como lenguaje de edición en algunos gestores de contenidos (CMS).
La guía oficial de la sintaxis MarkDown
La guía oficial de la sintaxis MarkDown

Para profundizar en su sintaxis os recomiendo:

Estos son algunos ejemplos de su sintaxis, que supongo os sera muy familiar si en alguna ocasión habéis utilizado un Wiki.


# Esto es un H1
## Esto es un H2
### Esto es un H3

[Esto es un enlace](https://jbravomontero.wordpress.com)

**Esto es negrita**

_Esto también es cursiva_

Lista numerada (ordenada)

1. Este es el primer elemento
2. Este es el segundo elemento
3. Este es el tercer elemento

Lista de puntos (desordenada)

* Un elemento de la lista
* Otro elemento de la lista
* El tercer elemento de la lista

Imagenes

![Con titulo](pictures/avatar.png)

Tablas

| Elemento | Cantidad | Precio |
| :------- | :------: | -----: |
| Item 1   | 15       | 150    |
| Item 2   | 3250     | 23,65  |

Para Windows hay varios editores pero yo he encontrado uno que funciona estupendamente, es el MarkdownPad.

Editor Markdown para Windows.
Editor Markdown para Windows.

No es necesario, pero si queréis os permite ir escribiendo y de forma simultanea ir viendo en la derecha el resultado en formato HTML. Aunque evidentemente cuenta con la opción de no mostrar el visualizador HTML para evitar las distracciones durante el duro proceso de escribir un artículo, un libro, etc.

Pero yo buscaba algo que me permitiese:

  • Escribir con comodidad y una sintaxis ligera. Tengo mucha experiencia en XML y editores de XML pero no deja de ser farragoso.
  • Y en diferentes ficheros para luego permitir:
    • Combinar de forma fácil el resultado en un único documento de presentación.
    • La documentación colaborativa.
    • Obtener varios formatos de salida.

Y he encontrado todo esto y mucho más en esa maravilla de herramienta que se llama Pandoc que ha sido desarrollada por un filósofo de la Universidad de Berkeley llamado John MacFarlane. Y que es lo que hace Pandoc para ser tan estupendo.

  • Pues lo primero que funciona. Me ha funcionado todo a la primera.
  • Y lo segundo, pues que le pasas a Pandoc un archivo fuente cualquiera de los que soporta Markdown, reStructuredText, etc y lo puedes convertir a LaTex, HTML simple, PDF, DocBook, OpenDocument, docx, rtf, man, texto plano y hasta tres tipos diferentes de presentaciones en HTML; y mi lista se queda corta, cortísima. Aquí hay un diagrama ilustrando su poder:
Pandoc input output
Pandoc input output

Su instalación en Windows ha sido muy sencilla. Como me interesaba sobre todo el tema del PDF, mi instalación a consistido en 2 aplicacioens:

Para probarlo os he subido un zip que os podéis bajar con:


pandoc codigo_duplicado_muerto_java.md -o codigo_duplicado_muerto_java.pdf
pandoc codigo_duplicado_muerto_java.md -o codigo_duplicado_muerto_java.docx
pandoc codigo_duplicado_muerto_java.md -o codigo_duplicado_muerto_java.html
pandoc -s codigo_duplicado_muerto_java.md -o codigo_duplicado_muerto_java.tex
pandoc -s -S -w docbook codigo_duplicado_muerto_java.md -o codigo_duplicado_muerto_java.db

  • que permite de un sola vez varias realizar todas las transformaciones:
    • A PDF.
    • A Word.
    • A HTML
    • A Tex.
    • A Docbook.
    • etc.

NOTA: Tener cuidado de que las imágenes estén en la ruta adecuada.

Ejemplo de la transformación en formato Word.
Ejemplo de la transformación en formato Word.

El fichero, codigo_duplicado_muerto_java.md no lo he escrito directamente en este lenguaje, sino que lo he obtenido a partir del html original también utilizando Pandoc (aunque luego lo he tenido que modificar por las rutas de las imágenes):


pandoc -s -r html https://jbravomontero.wordpress.com/2012/12/28/reduciendo-el-tamano-del-codigo-de-un-proyecto-java/ -o codigo_duplicado_muerto_java.md

En resumen, dos herramientas estupendas y que funcionan a la perfección para escribir y transformar nuestros documentos.

Y también y ya termino me encanta porque se puede utilizar para la escritura colaborativa utilizando por ejemplo un control de versiones. Por ejemplo,  el famoso libro Pro Git

Pro -Git - Book

Esta escrito utilizando markdown, estando todo sus capítulos y traducciones organizados en Gitub, permitiendo por tanto escribirlo, mantenerlo y traducirlo de forma colaborativa. Eso si, desconozco el mecanismo por el cual terminan convirtiéndolo a los diferentes formatos de salida, aunque me parece que todos ellos serían posibles con Pandoc.

Un saludo.

Anuncios
MarkDown, Pandoc y generación de libros y artículos en múltiples formatos de forma sencilla

¿Que dos cosas le pediría a un programador?


Bueno dos cosas, entre otras muchas cosas. Pero sin duda les pediría y preguntaría:

  1. ¿Si en su carrera profesional han llegado a implantar un proyecto?. Es decir, han llegado a ponerlo en producción y liberarlo con éxito para que los usuarios los utilicen en su vida diaria.
  2. ¿Si han desarrollado algún proyecto para usuarios que lo van a utilizar porque les gusta o interesa y no por obligación?. Es decir, no un proyecto para un usuario de intranet de empresa que tienen la obligación de utilizarla si o si.

Y en ambos casos: ¿cual ha sido el resultado?. Aunque este es un aspecto un poco menos importante.

Si una persona en su vida profesional me responde afirmativamente a las dos preguntas anteriores me generara mucha más confianza como profesional que otros.

Liberar un proyecto no es una tarea fácil. El que crea que ya ha terminado un proyecto cuando los usuarios todavía no lo están utilizando de forma habitual se equivoca. El objetivo del proyecto es precisamente ponerlo en producción y que el usuario lo utilice.

Que las personas que trabajan en el proyecto sean capaces de tener esto claro no es una tarea sencilla. Y no lo digo por decir, estoy actualmente en un proyecto en el que prácticamente nadie a puesto un proyecto en producción. Y algunos de ellos son gente que ya llevan 6 años o más trabajando. Pero son personas que en sus 6 o más años de vida laboral no han hecho más que saltar de proyecto en proyecto y de empresa en empresa y nunca han terminado nada. Les falta por tanto ese “toque”, esa “mentalidad” que te permite “terminar” el proyecto. Son personas para las cuales termina el proyecto cuando se van o los cambian, no cuando lo entregan. Y esto termina suponiendo un montón de problemas.

La respuesta afirmativa a la segunda pregunta me garantiza calidad y preocupación por lo que estas haciendo. Me garantiza que has tenido que pensar en el usuario y que te lo estas intentando ganar con la aplicación: porque es usable, porque va rápida, porque esta llena de funcionalidades que te agradan, etc.

!! Que diferentes serían muchos proyectos en los que he trabajado!! para intranets de algunas empresas, si no viésemos al usuario de la aplicación como un empleado que tiene que usarla si o si. Que parece que le puedes colocar cualquier cosa. Los usuarios de aplicaciones de Internet no se andan con tonterías: si no funciona no la utilizan y ya esta. Te dejan ahí con dos palmos de narices. Los tienes que cuidar y ofrecer lo mejor de lo mejor.

En resumen, me gustaría trabajar con gente:

  • Que sepa que el objetivo del proyecto es un “producto” puesto en producción y funcionando.
  • Que debemos hacer la aplicación como si fuésemos a cobrar por ella y por tanto, cuidando y mimando al usuario.

Siempre nos estamos quejando (con razón en muchos casos) de otros elementos que interfieren en el proyecto, cuando todavía queda mucho por mejorar en nosotros mismos.

El otro día leía en twitter “Con la tecnología actual se pueden hacer las cosas mejor y mucho más rápido ” y estoy seguro y convencido de que es así.

¿Que dos cosas le pediría a un programador?

Algunos consejos para ser un buen programador.

Hoy solo os dejo 2 enlaces. Dos enlaces que me han encantado y que están relacionados con las aptitudes de un buen programador y con lo que debería hacer a lo largo de su vida profesional para conseguirlo.

Los 4 pilares del buen programador

http://www.contentedcoder.com/2012/08/the-four-pillars-of-good-software.html

En el primer artículo, nos explica que para ser un buen programador no podemos conformarnos simplemente con escribir código, que debemos preocuparnos por:

  • La calidad.
  • La corrección.
  • La productividad.
  • La performance.

El conjunto de estas 4 pilares determinará si se es o no un buen programador y lo más recomendable es estar en la intersección de esos 4 puntos.

Aprende a programar en 10 años

http://loro.sourceforge.net/notes/21-dias.html

En el segundo artículos, el autor Peter Norvig, se mofa un poco de los libros que dicen enseñar un lenguaje de programación en 7 o 21 días.

Según el autor, algunos investigadores (Hayes , Bloom) han mostrado que toma aproximadamente diez años desarrollar habilidades en cualquiera de una amplia variedad de áreas y por tanto en la programación.

Nos recomienda que debemos hacer durante estos diez años:

  • Interésate en la programación.
  • Habla con otros programadores.
  • Programa.
  • Si quieres, dedica cuatro o cinco años en una universidad (o más en una escuela de graduados).
  • Trabaja en proyectos con otros programadores.
  • Trabaja en proyectos después que otros programadores. Proponte entender un programa escrito por otra persona.
  • Aprende por lo menos una media docena de lenguajes de programación.
  • Involúcrate en un plan de estandarización de algún lenguaje.
  • etc.

Me parece muy acertada la parte en la que dice:  “Sé el mejor programador en algunos proyectos; sé el peor en otros. Cuando eres el mejor, tienes que poner a prueba tus habilidades para liderar un proyecto y para inspirar a otros con tu visión. Cuando eres el peor, aprendes lo que los maestros hacen, y aprendes lo que a ellos no les gusta hacer (pues te ponen a hacerlo por ellos)”.

En definitiva 2 grandes artículos que nos pueden ayudar a ser mejores programadores.

Adiós.

Algunos consejos para ser un buen programador.

Liberalizar datos públicos

En los últimos meses estamos asistiendo a la liberación de datos públicos en todo el mundo, con casos como el de data.gov en EEUU o el de data.gov.uk en UK.

La idea es exponer los datos públicos que obran en su poder de forma reutilizable, con el fin de que terceros puedan crear servicios derivados de los mismos.  Como consecuencia, los conjuntos de datos expuestos se ofrecen bajo licencias de propiedad abiertas, que permiten su redistribución, reutilización y aprovechamiento con fines comerciales.

En España se estan empezando a dar los primeros pasos.

Y la comunidad Internet ha comenzado recientemente una campaña para sensibilizar a la administración y al publico en general sobre la necesidad de disponer de estos datos: http://www.abredatos.es.

Es un concurso para crear aplicaciones que hagan uso de datos públicos y sean un servicio al ciudadano.  Hay 5.000 euros en premios; y será el 17 y 18 de abril. El objetivo del concurso es generar debate en torno a la necesidad de que los organismos públicos proporcionen sus datos de forma accesible para permitir su uso y reutilización por parte de los ciudadanos.

Si duda un tema importante y que va a dar mucho juego en en los próximos meses/años: datos publicos + aplicaciones basadas en esos datos.

Liberalizar datos públicos