Lo que he aprendido: Markdown + pandoc para la ciencia

Chavales, me he venido arriba. He decidido abandonar Latex y pasarme a Markdown forever. Así. Los fanáticos de Latex pensaréis que estoy loca porque creéis que Latex es lo más mejor pero os equivocáis de parte a parte y os lo voy a demostrar.


Di NO a Latex

Latex es un engorro, hay que escribir un montonaco de letra para hacer cosas muy simples. ¿Qué es eso de escribir \textbf{} cuando quiero poner algo en negrita? Aparte de que no hay manera humana de leer del .tex directamente para editar o corregir cosas. Me paso la vida compilando, cambiando, compilando otra vez… Igual soy yo que soy zopenca, no descarto esa opción, pero me saca completamente de mis casillas.

Y no olvidemos mi parte favorita: hacer tablas. Gracias a Dios que hay cosas como esto porque si no es muerte y destrucción.

¡Hola Markdown!

En Markdown todo es fácil. ¿Que queremos poner algo en cursiva? pues lo ponemos entre asteriscos, ¿negrita? asteriscos dobles. ¿Un título? una almohadilla y ya. Pandoc tiene además un Markdown extendido que permite hacer algunas cosas más1, como referencias cruzadas o referencias bibliográficas, y que además nos permite usar Latex para, por ejemplo, meter ecuaciones2.

Configuremos la movida

Antes de nada os remito a mi miniserie de artículos sobre Emacs, Markdown, Pandoc y demás frikeces variadas, ya que todo lo que cuente aquí será una continuación de lo que ya conté allí:

  1. Emacs como editor de Markdown
  2. Emacs en Windows y la codificación UTF-8
  3. Cambiar el idioma y la plantilla en Pandoc
  4. Referencias bibliográficas en Markdown + pandoc
  5. Trucos para la bibliografía en pandoc

Dicho esto, pensemos qué necesitamos para poder escribir un documento científico. En mi caso concreto, los siguientes puntos son indispensables:

  1. Referencias cruzadas: poder citar imágenes, tablas, ecuaciones, capítulos o secciones fácilmente.
  2. Referencias bibliográficas: que sea sencillo citar desde nuestra base de datos (porque estáis usando una base de datos, ¿no? ¿NO?) y poder usar diferentes estilos de citas
  3. Ecuaciones y tablas: que queden bonitas y no quieras cortarte las venas cuando tengas que crear una.
  4. Índice: facilidades para crear una tabla de contenidos, índice de figuras e índice de tablas. Y que se actualicen ellos solos cada vez que se modifica algo en el documento.
  5. Código: poder escribir código con sintaxis resaltada para diferentes lenguajes y que aparezca con su correspondiente caption.
  6. Personalización: poder cambiar todo lo que se me ocurra hasta que el documento quede exactamente como yo quiero que quede (o como me exigen). Que esto no sea una labor digna de los constructores de las pirámides.
  7. Separación entre contenido y formato: con esto me refiero a que presentar el mismo contenido con diferentes formatos sea un juego de niños. Los que escribís papers para revista me entenderéis.
  8. Fiabilidad: que esté garantizado que el documento que guardo hoy sea exactamente igual que el que voy a abrir mañana. Parece obvio pero si habéis escrito un documento un poco largo en Word sabéis a lo que me refiero.

La combinación Markdown + pandoc cumple los 8 puntos. Para aprovechar su poder necesitamos:

  • Un editor de texto: cualquiera nos vale, yo uso Emacs porque soy fan de Richard Stallman
  • Instalar pandoc: hay para todos los sistemas operativos así que no os quejéis. Aquí está.
  • Un archivo de bibliografía: yo uso .bib porque uso Jabref para gestionar la bibliografía, básicamente porque tiene licencia GPL. Aquí tenéis el resto de formatos que se pueden utilizar.
  • Un archivo csl: para decirle a pandoc en qué estilo queréis la bibliografía. Aquí hay muchos.
  • Una plantilla .latex: pandoc creará el pdf según esta plantilla. Esta plantilla debe estar en C:\Users\USUARIO\AppData\Roaming\pandoc\templates en Windows y en $HOME/.pandoc/templates en GNU/Linux. Aquí tenéis más información al respecto.
  • Un terminal: el que os parezca, yo soy simple y uso cmd en Windows y bash en GNU/Linux.

Procedamos

Ahora que tenemos todo perfectamente configurado nos toca crear el documento en sí. Esta parte tiene tres etapas: la redacción del documento, la asignación de las variables y la compilación del mismo.

1. Escribir el documento

Esto es lo fácil, solo recordar lo siguiente:

Tablas: podemos ponerles un caption si hacemos esto:

-----------
 x     y   
--- -------
 1  -1.3666

 2  -0.9967
-----------

Table: Aquí va el caption

Citas bibliográficas: simplemente ponemos [@key] en el texto. Hay que acordarse de hacer una última sección que se llame Referencias o similar bajo la cual nos escribirá las referencias bibliográficas.

Referencias cruzadas y ecuaciones: de momento yo uso sintaxis de Latex para esto, si alguien tiene una idea mejor que comente.

Código: si queremos código con sintaxis resaltada hacemos3:

```lenguaje
el código va aquí
```

Índice, lista de figuras y lista de tablas: estas opciones las podemos controlar con el bloque YAML, os lo cuento en el siguiente apartado.

2. Añadir un bloque YAML

Antes de compilar nos queda añadir un bloque YAML al principio del documento con todas las variables de la plantilla que queramos asignar, un ejemplo sería:

---
title: Título del documento
autor: Nombre del autor
bibliography: referencias.bib
csl: estilo.csl
toc: true # Añadir índice
lof: true # Añadir lista de figuras
lot: true # Añadir lista de tablas 
---

Si el archivo es muy largo o queremos reutilizar estos metadatos podemos guardarlos en un archivo aparte con extensión .yaml.

3. Compilar

Por último le pedimos a pandoc que nos cree el documento final, lo básico para un documento que se tenga que compilar con una plantilla personalizada y que tenga referencias bibliográficas sería:

pandoc input.md --filter pandoc-citeproc 
  --template=plantilla -o output.pdf

Si tenemos un archivo yaml simplemente lo añadimos como entrada:

pandoc input.md metadata.yaml --filter 
  pandoc-citeproc --template=plantilla -o output.pdf

Pero podéis jugar con muchas opciones, está todo muy bien explicado en la documentación de pandoc


Pues hasta aquí hemos llegado hoy, cuando tenga una plantilla perfecta para escribir la tesis os la pondré por aquí para la veáis. Hasta entonces un saludo 😀

Más

Un repositorio de GitHub con todo lo necesario para escribir la tesis en Markdown y la entrada del blog correspondiente

Sobre generar plantillas

Un tutorial sobre Markdown + pandoc

Postureo académico o por qué no debes usar todo esto si no lo necesitas

Bonus: una cosa chula


NOTA: Espero que se capte el humor de toda esta entrada. A mí Latex me encanta4, hace tiempo que dejé de escribir en editores de texto tipo Word (y su fantástico editor de ecuaciones) y soy megafan de Donald Knuth. Aun así hay que reconocer que esta combinación de Markdown + pandoc permite hacer lo mismo que Latex y deja unos archivos mucho más legibles. Hay que guerrear un poco con la configuración, eso sí, pero luego se ahorra uno mucho tecleo.


  1. Aquí tenéis un buen resumen 
  2. Podemos usar sintaxis de Latex para lo que nos parezca porque pandoc por dentro usa Latex para pasar de Markdown a pdf. 
  3. Todavía no sé ponerle un caption a los trocitos de código ni citarlos luego, pero todo se andará. 
  4. Si no lo creéis mirad aquí y aquí 
Anuncios

7 pensamientos en “Lo que he aprendido: Markdown + pandoc para la ciencia

  1. Pingback: Lo que he aprendido: makefile para pandoc | Onda Hostil

  2. Pingback: Lo que he aprendido: referenciando imágenes en Markdown | Onda Hostil

  3. Pingback: Lo que he aprendido: Pandoc 1.16 y sus nuevas funcionalidades | Onda Hostil

  4. Pingback: Lo que he aprendido: crear una lista de símbolos en Latex sin enloquecer | Onda Hostil

  5. Pingback: Lo que he aprendido: escribiendo un artículo científico en Latex y Markdown | Onda Hostil

  6. Pingback: Lo que he aprendido: cita en la primera página de la tesis | Onda Hostil

  7. Pingback: Compilación: escribir la tesis | Onda Hostil

¡Opina sin miedo! (Puedes usar Markdown)

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s