Introducción a Asciidoc y Asciidoctor (1)

Aunque todo el ecosistema de Asciidoctor funciona también en Windows yo no lo uso, así que en esta entrada todo lo que explique sobre instalación, ejemplos y demás será bajo Linux

He añadido un pequeño comentario sobre cómo usarlo en Windows 10.

Ecosistema

Asciidoc es un formato para documentos de texto usado para escribir notas, articulos, libros, páginas web, manpages, blogs, presentaciones orientado a su transformación en html, pdf, epub, etc ( http://asciidoc.org )

Con esta definición lo primero que pensarás es que es otro Markdown y que para eso ya te quedas con este que es muy usado y lo soporta Github. Sin embargo, aunque ambos, como algún otro, están orientados a documentar en texto plano las diferencias son enormes.^[1]

Se podría decir que Asciidoc define las reglas sintácticas sobre los elementos del documento pues especifica dónde va el título, el autor, los párrafos, etc

Si te suena o has usado reStructuredText entonces puedes ver a asciidoc como otra alternativa a este.

Asciidoctor (https://asciidoctor.org) es una implementación , un programa, un ejecutable, que es capaz de leer documentos asciidoc y conventirlos a html5, docbook, pdf, etc. Como ves son parecidos, e incluso confusos, pero son dos cosas diferentes: uno podríamos verlo como las especificaciones y al otro como un traductor

Para complicar más la cosa, existe una implementación llamada asciidoc , igual que las especificaciones, pero que su última actualización es del 2013. Así, cuando en este documento hable de asciidoc estaré hablando de las especificaciones y no de esta implementación.

La implementación asciidoctor está desarrollada en Ruby pero existen otras implementaciones como:

asciidoctorJ, un jar de java que puedes ejecutar desde la línea de comando o integrarlo en tu aplicación
asciidoctor-js, un paquete Node en javascript al estilo del de Java

Estas 3 implementaciones (y a lo mejor alguna más que no conozca) son fáciles de instalar y están destinadas a ser ejecutadas por línea de comando o integradas en un proceso de construcción de software.

Instalación

Si usas Ruby, Asciidoctor se puede instalar como una gema:

gem install asciidoctor

O bien puedes instalarlo como paquete del sistema operativo:

sudo apt-get install asciidoctor

Si no quieres instalar dependencias de Ruby y prefieres utilizar la implementación en Java puedes descargar el jar de su web o si tienes SdkMan como gestor de aplicaciones, puedes instalarlo fácilmente:

sdk install asciidoctorj

Windows 10

Si utilizas Windows 10 existe una forma de instalar asciidoctorj mediante Chocolatey (https://chocolatey.org/), un gestor de paquetes para este sistema operativo.

En primer lugar deberás instalar Chocolatey mediante una consola PowerShell como administrador y ejecutar:

`Set-ExecutionPolicy Bypass -Scope Process -Force; `
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Después de cerrar y volver a abrir la consola PowerShell (como administrador) podrás instalar asciidoctorj ejecutando

choco install asciidoctorj

NO uses Notepad de Windows para editar los ficheros .adoc (y mucho menos Word) pues añaden caracteres de control al inicio del fichero incompatibles con asciidoctor. Usa Notepad++ , VSCode, Atom, o similar

Ejemplo básico

Abre un editor de texto plano (recuerda ni Word ni LibreOffice son editores de texto plano) como notepad, gedit, vi o nano y escribe:

ejemplo.adoc

= El titulo : el subtitulo
jorge.aguilera@puravida-software.com

(debes dejar un espacio en blanco entre el email y esta linea)

== Una sección

*Todo* lo que ven tus ojos algún día _sera_ tuyo

Guarda el documento como ejemplo.adoc y desde una línea de comando nos situamos donde esté el documento y ejecutamos:

asciidoctor ejemplo.adoc ( o asciidoctorj ejemplo.doc si usamos la versión java)

Si todo ha ido bien debería haberse generado un documento ejemplo.html que puedes abrir con un navegador y comprobar que es un documento html5 completo y que se ha generado sin necesidad de tener conocimientos de maquetar html

Editores

La sintáxis de asciidoc es muy completa y extensa pero a la vez muy sencilla por lo que una vez practicado con ella serás capaz de memorizar gran parte de ella así que no deberías necesitar más que un editor plano.

Sin embargo hay editores y/o plugins para diferentes IDEs que nos pueden ayudar a escribir en asciidoc. A modo de ejemplo dispones:

AsciidocFX (requiere Java)
IntelliJ (requiere instalar un plugin)
VSCode (requiere instalar un plugin)

De forma general, y aunque estos editores tengan la opción de generar el html (o el pdf, etc) es importante entender que estos editores trabajan sobre el adoc y que nosotros podremos ejecutar la generación del documento utilizando todas las opciones que ofrecen.