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.

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

Explicando la complejidad ciclomática mediante gráficos

Como una imagen vale más que mil palabras, esta es la mejor forma que he encontrado de  explicar a mis compañeros que es al complejidad ciclomática de forma rápida,concisa y sobre todo impactante.

En primer lugar, una pequeña introducción

La Complejidad Ciclomática (en inglés, Cyclomatic Complexity) es una métrica del software que proporciona una medición cuantitativa de la complejidad lógica de un programa.

El resultado obtenido en el cálculo de la complejidad ciclomática define el número de caminos independientes dentro de un fragmento de código y determina la cota superior del número de pruebas que se deben realizar para asegurar que se ejecuta cada sentencia al menos una vez, (es decir, mira if, else, for, while, etc)

En segundo lugar donde la pueden visualizarla en el Sonar

En el Sonar esto se puede ver en el cuadrado denominado “Complexity“:


Donde podemos observar que tenemos 2.6 de media por método y 9.9 de media por clase (cifras ambas muy engañosas). Ya que si pulsamos sobre métodos (por ejemplo) podemos ver que hay métodos que suben hasta un valor de 61 en la complejidad ciclomática.

Explico un poco lo que significan esas cifras

Si tenemos en cuenta el siguiente ranking:

  • 1-10       Programa Simple, sin mucho riesgo.
  • 11-20     Más complejo, riesgo moderado.
  • 21-50     Complejo, Programa de alto riesgo.
  • 50           Programa no testeable, Muy alto riesgo.

Pues podemos ver que hay métodos que superan el “peor escenario imaginable”. Supongo que los números os indican poco, pero si miráis este gráfico en el que se pinta el flujo de un método con una complejidad ciclomática de 48, pues acojona un poco (ojo, insisto que es flujo de un solo método):

Y en último lugar una imagen (el incentivo definitivo) que muestra gráficamente que puede significar ese número

 

 

NOTA:

La imagen ha sido creada a partir del programa Understand una aplicación de SciTools que nos permite realizar un análisis estático del código. No es gratuita, es de pago, pero tiene una versión de pruebas de 15 días. ¿conocéis de alguna otra herramienta que permita realizar este tipo de gráficos?.

Un saludo.

Explicando la complejidad ciclomática mediante gráficos