La opción Pandoc

Allá por los inicios del cursete de LaTeX hablé de Pandoc, una herramienta que transforma documentos de un formato a otro fácilmente y, sobre todo, bien. Comenté que Pandoc nos permitía escribir en Markdown y obtener un pdf de calidad porque por el medio usaba LaTeX. Hoy vamos a ver cómo se hace esto.

Si ya sabemos LaTeX para que vamos a aprender Pandoc ahora, me diréis. Pues porque tiene unas pocas ventajas que paso a listar:

Como todo no puede ser bueno, también tiene unas pocas desventajas:

Yo escribí mi tesis doctoral así, primero porque estoy loca y segundo porque me hago vieja y mis manos necesitan un descanso del ordenador. He de reconocer que ese es un caso muy extremo, pero este sistema es muy práctico para tomar notas rápidas y que el resultado final tenga buena pinta.

Instalación y uso

Hay varias maneras de instalar Pandoc, desde la sencillísima de tirar de repositorios o del paquete de Debian o Windows correspondiente a usar cabal, el gestor de paquetes de Haskell. Hay que tener en cuenta que la versión de los repos suele ser bastante antiguaHaciendo apt-cache search pandoc en Ubuntu 16.04 LTS he visto que lleva un Pandoc 1.16 y que si instalamos desde un paquete tendremos que reinstalar si queremos un Pandoc actualizado a tope.

Por esos motivos y porque siempre tengo la idea de aprender Haskell y luego nunca lo hago, yo instalé Pandoc y dos filtros que utilizo mucho mediante cabalRecordad añadir .cabal/bin al path si queréis llamar a Pandoc y sus filtros desde cualquier sitio sin dar la ruta completa.:

sudo apt-get install haskell-platform   # O equivalente según distro
cabal update                            # Actualizar lista de paquetes
cabal install pandoc                    # Instalar pandoc
cabal install pandoc-citeproc           # Instalar filtro de bibliografía
cabal install pandoc-crossref           # Instalar filtro de referencias cruzadas

Una vez que lo tenemos instalado, nos toca aprender a usarlo. Lo más raro de Pandoc es que se usa desde la terminal, nada que nosotros aguerridos latexianos no podamos dominar. En el caso más simple no tenemos más que darle el nombre del archivo de entrada y el de salida con su respectiva extensión:

pandoc INPUT.ext -o OUTPUT.ext

Ahora nos vamos a centrar en el caso de crear un pdf a partir de uno o varios archivos escritos en Markdown. Aparte de la opción -o que acabamos de ver hay otras que nos pueden resultar interesantes:

Todas estas cosas parecen complejas pero en la mayor parte de los casos usaremos el comando simple que mostraba al principio, montaremos nuestro contenido en un plis con Markdown y tendremos un documento final decente gracias al LaTeX intermedio.

¿Qué necesitamos?

Vamos a ver más en detalle qué nos hace falta para crear un pdf a partir de un Markdown. En esencia necesitamos:

Para hacernos la vida más fácil nos conviene:

No os preocupéis, enseguida diseccionamos las cosas nuevas: el Markdown, la plantilla, el YAML y el Makefile.

Markdown sabor Pandoc

Markdown es un viejo conocido de los que escribimos en el Internet, especialmente de los que usamos GitHub. Pandoc tiene un Markdown especial con más funcionalidades que el Markdown estricto, como notas al pie o la posibilidad de cambiar el tamaño de las imágenes, esto último en sus versiones más modernas. Va un resumen rápido:

# Título de primer nivel

## Título de segundo nivel

Lista numerada:

1. Ítem
1. *cursiva* o _cursiva_
1. **negrita**

Lista sin numerar:

* [enlace](url) o [enlace] o [enlace][ref]
* Texto[^nota]

[^nota]: Texto de la nota al pie
[enlace]: url
[ref]: url

### Título de tercer nivel

Imagen

![Texto alternativo](ruta a la imagen){width=porcentaje}

Tabla

------------
  x      y
----- ------
 0.1   1.3 
------------

Table: Aquí va el pie de tabla

$Ecuación inline$

$$Ecuación con línea propia$$

`Código inline`

Bloque de código

```haskell
-- Fibonacci!
  fib = 0 : 1 : zipWith (+) fib (tail fib)
```

Además, los filtros que mencionaba tienen una sintaxis propia para las referencias cruzadas y bibliografía. Van unos ejemplos:

# Sección {#sec:etiqueta}

Como dicen en [@claveBibliográfica] o incluso en @claveBibliográfica

![Pie de figura](ruta){#fig:etiqueta}

Tal y como se ve en @fig:etiqueta

$$ ecuación $$ {#eq:etiqueta}

La ecuación @eq:etiqueta

Plantilla personalizada

Pandoc realiza la conversión de archivos mediante una plantilla para cada tipo de formato. Hemos dicho que para pasar de Markdown a pdf utiliza LaTeX, podemos extraer la plantilla correspondiente haciendo:

pandoc -D latex > plantilla.latex

Al abrirla veremos que contiene LaTeX de toda la vida y que, por lo tanto, sabemos adaptarla a nuestro gusto.

Lo único así raro son las cosas que van entre símbolos de dólar y que no son ecuaciones sino variables. Entre ellas la más importante es $body$, donde Pandoc mete el contenido de nuestros Markdowns una vez los ha convertido a LaTeX.

Metadatos YAML

Todas las variables que aparecen en la plantilla se sustituyen con los valores o metadatos que enviamos con la opción -V, en un bloque YAML dentro de un archivo Markown o en un archivo YAML aparte.

Un bloque YAML real tiene una pinta como esta:

---
# Datos
title: Título 
author: Nombre
lang: es

# Control
toc: True

# Formato
documentclass: book
geometry:
- top=1in
- bottom=1in
- right=0.5in
- left=1.5in
mainfont: LiberationSans
fontsize: 12pt

# Bibliografía
bibliography: referencias.bib
csl: formato.csl
link-citations: true
---

Se puede añadir este bloque al inicio de nuestro Markdown o guardarlo en un archivo aparte que incluiremos como entrada para Pandoc:

pandoc datos.yaml input.md -o output.pdf

Es importante que aunque tengamos los datos en un archivo aparte mantengamos los guiones alrededor, ya que como Pandoc concatena todos los archivos de entrada no sabrá que es un bloque YAML sin ellos.

Makefile

Si juntamos todo lo visto hasta ahora nos damos cuenta de que la orden para invocar a Pandoc puede ser muy larga. Ahí es donde nos resulta útil un Makefile, un archivo que contiene las instrucciones para compilar determinada cosa, en nuestro caso para convertir los Markdowns en pdfs.

Yo no os voy a explicar cómo hacer un Makefile, básicamente porque no sé, os dejo un ejemplo con varios archivos de entrada y filtros que podéis adaptar y un par de referencias sobre el tema. Lo único que sé es que debe tener esta estructura:

variable = contenido

objetivo:
	órdenes indentadas un tabulador
	$(referencia a variable)

Mi Makefile habitual suele parecerse a este, la gente que sabe de ordenadores lo hará mucho mejor:

# Archivos markdown

FILES = INPUT_1.md INPUT_2.md

# Creación de pdf
# - La barra sirve para partir la orden 
# - El filtro crossref debe ir antes de citeproc
# - Opción -N para numerar secciones

all: 
	pandoc \
	--filter pandoc-crossref \
	--filter pandoc-citeproc \
	--template=./PLANTILLA.latex \
	-N \
	$(FILES) METADATOS.yaml \
	-f markdown -o OUTPUT.pdf

# Eliminar output

clean:
	rm OUTPUT.pdf

# Por si hay algún archivo que se llame clean

.PHONY: clean

Ahora solo nos hace falta llamar a make:

make       # Crear el pdf
make clean # Borrar el pdf

Reflexión final

En este capítulo he intentado dar a conocer otra herramienta relacionada con LaTeX y que me parece tremendamente útil. No creo que sea un sustituto para el LaTeX puro y duro pero me parece interesante para escribir documentos rápido y que tengan una apariencia elegante. Otro uso a tener en cuenta es obtener salidas variadas a partir de nuestro LaTeX, que sé yo, para los que tengáis jefes raros que solo lean documentos en Word.

Como siempre, yo intento dar una visión general del tema, para aprender más os dejo las referencias.

Referencias

Manual de Pandoc

Sustainable Authorship in Plain Text using Pandoc and Markdown

Pandoc’s markdown

pandoc-citeproc

pandoc-crossref

Sinopsis del formato markdown para pandoc (pdf)

Zotero Style Repository

make en la Wikipedia

Compilación, Linkado y Makefiles en C en Free Hacks!

Anterior: Abramos la caja de herramientas, Siguiente: Mi esquema de trabajo [Contenido]