Curso no convencional de LaTeX: 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:

  • El documento es legible incluso antes de compilar.

  • Podemos usar cualquier editor de texto, cosa que también ocurre con LaTeX pero que exige un proceso de compilación más complejo.

  • Tecleamos menos, ya que Markdown es un lenguaje mucho más escueto que LaTeX. Podemos suplir las carencias de Markdown mezclando LaTeX alegremente por ahí y usando filtros.

  • No nos deja archivos auxiliares por ahí, los borra una vez hecha la transformación. Solo nos quedan el Markdown inicial y el pdf final.

  • Tenemos la opción de obtener diferentes formatos finales, lo que nos permite, por ejemplo, montar una web y sacamos un pdf a partir de los mismos archivos.

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

  • Necesitamos más archivos, si es un documento complejo nos vendrá bien un Makefile.

  • Instalarlo puede ser un poco lío, sobre todo los filtros.

  • Tenemos que saber LaTeX (pero ya sabemos ¿no?), Markdown (que se aprende en diez minutos) y Pandoc (otros diez minutos).

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 antigua1 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 cabal2:

sudo apt-get install haskell-platform   # O equivalente según sistema operativo
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:

  • --latex-engine = COMPILADOR: nos permite elegir el compilador de LaTeX. Como sabemos, el compilador elegido afecta a cómo se establecen el idioma y las fuentes.

  • --variable, -V: controla el comportamiento de la plantilla que LaTeX utiliza para pasar de Markdown a pdf asignando valores a las diferentes variables. Un ejemplo es establecer el tipo de documento, que se hace con -V documentclass=book. Estas variables se pueden introducir mediante un bloque YAML en el propio archivo Markdown o en un archivo .yaml como veremos un poco más abajo.

  • --number-sections, -N: numera las secciones.

  • --top-level-division=[part|chapter|section]: indica si la división de mayor jerarquía es la parte, el capítulo o la sección. Se establece automáticamente si definimos el tipo de documento.

  • --table-of-contents, --toc: añade un índice al documento. Esta opción también puede controlarse desde el bloque YAML, la pongo como ejemplo de la flexibilidad que tiene el programa.

  • --template=RUTA: indica el camino a la plantilla que debe seguir para dar formato al documento.

  • --filter FILTRO: añade funcionalidades adicionales incluidas en un filtro. Los filtros que he mencionado en la instalación, pandoc-citeproc y pandoc-crossref, sirven respectivamente para gestionar las referencias bibliográficas y las referencias cruzadas sin tener que recurrir a sintaxis de LaTeX.

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:

  • Archivos escritos en Mardown con extensión md

  • Pandoc y una distribución de LaTeX

  • Una consola

  • Si vamos a tener referencias bibliográficas, un archivo con la bibliografía y un estilo de bibliografía csl. Nuestro amado .bib nos vale perfectamente para la primera labor y tenemos estilos csl a patadas en la web de Zotero.

  • Una plantilla si la que usa por defecto no nos gusta

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

  • Un archivo YAML para las variables

  • Un Makefile y make

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!


Suena:


  1. Haciendo apt-cache search pandoc en Ubuntu 16.04 LTS he visto que lleva un Pandoc 1.16 
  2. Recordad añadir .cabal/bin al path si queréis llamar a Pandoc y sus filtros desde cualquier sitio sin dar la ruta completa. 
Anuncios

¡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