Introducción a Asciidoc y Asciidoctor (3): artículo académico

| | Este post es la continuación a intro-asciidoctor-2.html |

Objetivo

En este post veremos cómo crear un artículo "académico" en Pdf.

| | Por académico quiero decir que desarrollaremos un texto que contendrá diferente contenido como gráficos (inventados), formulas matemáticas (sin ningún sentido) etc, que den una idea de loque sería un caso real. |

| | Aquí para ver la versión HTML, o aquí para ver laversión PDF del documento final. Ambas versiones parten del mismo documento adoc que analizaremos a continuación y que puedes ver aqui (texto plano) |

Cabecera

En un documento .adoc las primeras líneas hasta encontrar una en blanco,contienen numerosa información respecto del mismo. Así, por ejemplo:

• La primera línea comienza con un = y es donde indicamos el título del documento, y si en esa misma línea incluimos: otro texto, entonces otro texto es el subtítulo.

• La siguiente línea está reservada para indicar el autor

• En la tercera indicamos la fecha

Estas tres líneas son opcionales, aunque aconsejo por lo menos indicar el título.

Antes de llegar a la primera línea en blanco que indicaría fín de cabecera, podemos especificar numerosos atributos del documento, como por ejemplo si queremos que tenga una tabla de contenidos, la posición de esta, qué tipo de documento es, variables globales, si queremos iconos, y un largo etcetera

Así pues nuestro artículo tendrá las primeras líneas:

= Título del artículo
[e-mail]
v0.0.0.0.1, 2020-01-18
:toc:
:icons: font
:stem: latexmath

Secciones

A continuación comenzaría nuestro artículo, el cual iremos organizando en secciones, párrafos, etc.

Una sección se indica mediante el signo `=' concatenado tantas veces como nivel de sección queramos crear. Por ejemplo


== Seccion 1
=== SubSeccion 1.1
==== Subseccion 1.1.1
== Seccion 2


Como el título es el nivel 1 es el que lleva un único =

Las secciones son importantes para organizar el texto y son marcadores para la generación de la tabla de contenido (TOC)

Texto y elementos

En este post no voy a describir todos los elementos que puedes usar en el texto. Te remito a la página principal donde están explicados completamente y con ejemplos: https://asciidoctor-docs.netlify.com/asciidoc/1.5/

A modo de resumen indicar que:

• podemos remarcar texto en negrita, subrayado, itálica, etc

• embeber imágenes, vídeos, etc

• crear enlaces a documentos tanto internos como externos

• crear tablas con una libertad absoluta sobre tamaños, formatos y contenido

Stem

Como nuestro artículo va a contener fórmulas es necesario activarlo en la cabecera del documento mediante el atributo :stem: . Asciidoctor tiene un par de procesadores para fórmulas: LaTex y AsciiMath y en este caso vamosa usar por defecto LaTex indicandolo en el atributo :stem: latexmath

Para incluir una formula en nuestro documento podremos hacerlo mediante un bloque inline (en el mismo párrafo)o con un bloque individual si queremos indicar varias líneas de fórmulas:

La solución a stem:[a*x^2 + b*x +c = 0] se obtiene ... (bloque inline)

O con un bloque:

[stem]

---

k_{n+1} = n^2 + k_n^2 - k_{n-1}

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

---

Generación

Una vez que tenemos nuestro documento preparado sólo tenemos que generar el documento final(en realidad este proceso lo repetirás muchísimas veces hasta tener soltura)

En una consola donde esté el documento ejecutaremos:

asciidoctor articulo.adoc y obtendremos en ese mismo directorio un fichero articulo.html completo, tal quepuedes abrirlo con el navegador sin necesitar ningún otro archivo.

Para generar la versión pdf ejecutaremos:

asciidoctor -b pdf articulo.adoc y obtendremos un fichero articulo.pdf

| | El backend de pdf necesita tener instaladas una serie de dependencias si vas a usar fórmulas como en esteejemplo. Si estás interesado no dudes en decirmelo y lo explico en más detalle. |

Conclusión

Generar un artículo de opinión, redacción o una revisión de un producto, por poner unos ejemplos, de calidad tanto HTML como Pdf es realmente fácil con Asciidoctor y cuentas con todas las ventajas que ya hemos visto(texto plano, versionable, revisable, trabajo en grupo, etc)