Creación y publicación de documentos con AsciiDoc / AsciiDoctor

Los ficheros fuente de AsciiDoc son ficheros de texto que (como todos los ficheros de texto) se crean y manipulan con un editor de textos.

En relación con el fichero fuente ha de tenerse en cuenta que:

El documento lo procesaremos usando el programa asciidoctor (para obtener una versión HTML, DocBook o ManPage) o asciidoctor-pdf (para obtener una versión PDF). Ambos programas se ejecutan, en principio, desde una terminal. Para ejecutar el programa conversor, en una terminal hay que escribir

Por ejemplo:

procesará el fichero denominado «MiFichero.adoc» y generará un nuevo fichero llamado «MiFichero.html» que podrá ser visualizado con cualquier programa visor de páginas web.

Y si lo que queremos obtener es un fichero PDF habría que escribir:

Lo hasta ahora dicho es lo imprescindible para empezar a trabajar con AsciiDoc. Más adelante (XX) se volverá a hablar del procesado del documento, pero con mucho más detalle.

Los atributos de documento son una especie de variables o palabras clave que almacenan un valor que queda así asociado al nombre del atributo. Este valor puede referirse a algún metadato del documento (por ejemplo, el título, o el nombre del autor), o indicarle al programa procesador cómo debe procesar el documento: si debe o no tener índice, si las secciones deben o no numerarse, qué tipo de documento se debe generar, etc.

Desde la perspectiva de AsciiDoc, un documento consiste en un conjunto de bloques de texto apilados verticalmente, uno sobre otro, y separados unos de otros por una o más líneas en blanco. A estos efectos, para AsciiDoc son bloques los párrafos, los títulos de las secciones, las tablas, las listas ordenadas o desordenadas, etc.

Los bloques, por su parte, son de distinto tipo. AsciiDoc identifica el tipo de cada bloque por el carácter o caracteres inicial. Y así, por ejemplo, si un bloque (es decir: una línea con texto precedida de una línea vacía) empieza con la secuencia "==" seguida de uno o más espacios en blanco, AsciiDoc sabrá que ese bloque es un título de Nivel 1, y lo formateará de acuerdo con ello. Pero si el bloque empieza con un guión seguido de un espacio en blanco, AsciiDoc asumirá que se trata de una lista desordenada. Y si el bloque empieza con el texto "WARNING:" escrito con mayúsculas y terminado con ":", AsciiDoc asumirá que se trata de una admonición, etc…​ Hay muchos tipos distintos de bloque, y lo que aquí interesa es señalar que AsciiDoc identifica el tipo de cada concreto bloque fijándose en cómo empieza el bloque. Los bloques normales que no empiezan con ningún carácter o secuencia especial, serán tratados como párrafos ordinarios de texto.

Lo interesante de los bloques está en que en AsciiDoc todo bloque puede tener:

Un elemento en línea es un fragmento de texto dentro de un bloque, que debe formatearse de cierta manera. Por ejemplo: si queremos indicar que cierta palabra o frase debe ir en cursiva, o en negrita, o se debe escribir en color azul…​ Todos esos fragmentos de texto formateados de manera diferente a como se ha de formatear el bloque en el que se encuentran son lo que AsciiDoc llama Elementos en línea.

En los elementos en línea es preciso indicar expresamente dónde empiezan y dónde acaban. Para ello se usa uno o dos símbolos al principio y al final del fragmento. El símbolo a usar depende del tipo de elemento en línea de que se trate. Por ejemplo: para indicar que un fragmento de texto ha de ir en cursiva, hay que encerrarlo entre guiones bajos:

Los elementos en línea también pueden tener atributos, los cuales también se indican entre corchetes al principio del elemento. Por ejemplo:

El título del documento se introduce, normalmente, en la primera línea del fichero que no sea un comentario o una línea en blanco, mediante una línea (línea de título) que tiene la siguiente forma:

Es decir:

Sobre la distinción entre título y subtítulo hay que tener en cuenta que:

La segunda línea de la cabecera del fichero (línea de autor) recoge el nombre y correo electrónico del autor o autores. El formato de esta línea es el siguiente:

El nombre intermedio y el correo electrónico, son optativos, y, si hubiera más de un autor, los nombres de los distintos autores — siguiendo el esquema que se acaba de indicar para cada uno de ellos — se incluirán en la misma línea, uno tras otro, separados entre sí por un punto y coma:

Si alguno de los elementos del nombre del autor (por ejemplo, el apellido) consta de más de una palabra, las distintas palabras que lo componen se deben separar entre sí, no por un espacio en blanco, sino por un guión bajo.

Por ejemplo:

La tercera línea del encabezado (línea de revisión) se dedica a recoger los datos relativos a la versión (o revisión) del documento y su fecha. Su formato es el siguiente:

De estos tres elementos sólo el primero es obligatorio:

Por ejemplo, si en la línea de revisión hemos escrito:

AsciiDoc extraerá los siguientes metadatos de esta línea:

En relación con el título del documento AsciiDoc predefine los siguientes atributos:

Si sólo hay un autor del documento, los metadatos del mismo, que AsciiDoc extrae de la línea de autor, son los siguientes:

Si hubiera más de un autor, al nombre de cada uno de estos atributos se le añade la secuencia «_<n>» donde «n» representa el número de autor de que se trate; y así, por ejemplo, author_1 recogería el nombre completo del primer autor, y lastname_3, el apellido del tercer autor.

Si asignamos un valor a author y no asignamos expresamente ningún valor a los demás atributos que recogen el nombre del autor, AsciiDoc los calculará a partir del nombre del autor. De la misma manera, si asignamos valor a firstname, middlename y lastname, pero no asignamos ningún valor concreto a author, AsciiDoc lo calculará a partir del valor de dichos atributos. Pero si asignamos expresamente algún valor a todos los atributos, AsciiDoc no realizará ningún ajuste, incluso aunque el contenido de estos atributos sea inconsecuente.

Tratándose de nombres españoles, es conveniente tener en cuenta que:

Hay cuatro atributos relacionados con la línea de revisión: El valor de los tres primeros lo extrae AsciiDoc automáticamente a partir de la línea de revisión, si la hay, mientras que el cuarto tiene un valor predefinido.

Por defecto AsciiDoc genera automáticamente, para cada sección del documento, sea del nivel que sea, e incluso aunque se trate de una sección especial o de una falsa sección, un atributo ID que sirve para identificar el punto en el que empieza la sección como lugar de destino de un hipervínculo.

Para generar el ID AsciiDoc parte del título de la sección, y le aplica las siguientes transformaciones:

Por ejemplo, el título de esta sección es «IDs automáticos de las secciones». Aplicando las reglas que se acaban de exponer, el ID de la misma sería:

Hay dos atributos que nos permiten influir en cómo se calcula el ID automático de una sección:

Y así, por ejemplo, si en el preámbulo de nuestro documento añadimos:

El ID automático de esta sección pasaría a ser el siguiente:

Trabajar con IDs automáticos no siempre es fácil. En primer lugar porque para utilizarlos debemos tomarnos el trabajo de calcular el ID de la sección con la que deseamos enlazar. Pero, sobre todo, porque si después de haber establecido un enlace a una sección a partir de su ID generado automáticamente, modificamos el documento y cambiamos en algo, por poco que sea, el título de la sección …​ Nuestro enlace pasará a estar apuntando a un ID inexistente.

Por ello creo que son preferibles los IDs manuales que no cambian aunque modifiquemos el título de la sección; y por ello yo suelo desactivar la generación automática de IDs escribiendo en el preámbulo del documento

AsciiDoc admite tres sintaxis distintas con las que podemos asignar un ID manual a una determinada sección:

AsciiDoc contiene dos atributos que activan dos funcionalidades de las que no consigo averiguar la utilidad y que sólo se me ocurre designar como autoenlaces.

Mi consejo a los lectores que sientan curiosidad por estos autoenlaces es que activen dichos atributos y comprueben el resultado. Si averiguan cuál es su utilidad práctica, les agradecería que me lo hicieran saber.

Cuando AsciiDoc procesa el fichero fuente, conforme va leyéndolo, aplica las siguientes acciones a todos los párrafos de texto que no sean párrafos literales:

Es decir: el texto del párrafo se reduce a una sola línea. Esto permite a AsciiDoc recomponer el párrafo para ajustarlo a la anchura que haya de tener en el fichero final.

Los saltos de línea normales (también llamados blandos), como acabamos de ver, se suprimen para permitir a AsciiDoc reorganizar correctamente los párrafos. Por ello, para asegurarnos de que cierto salto de línea existente en el fichero fuente, sea mantenido en el fichero de salida, hay que convertirlo en un salto de línea duro. Ello se puede hacer de varias maneras:

El atributo de documento hardbreaks-option produce el mismo efecto que hardbreaks, pero está diseñado para incluirse en la cabecera del documento consiguiendo así que absolutamente todos los saltos de línea del mismo se interpreten como saltos de línea duros.

Además de la sustitución de espacios en blanco, tabuladores y saltos de línea, en el texto normal se aplican las siguientes sustituciones adicionales:

Para aplicar cierto formato tipográfico a uno o más caracteres consecutivos del párrafo se encierra el texto a formatear entre dos marcas que indican el inicio y el fin del fragmento que debe recibir el formato. En tal caso al texto encerrado entre estas marcas de formato se le considera un elemento en línea y a este tipo de formateo se le llama formateo en línea.

Las marcas de formato son las siguientes:

Cuando el formato de carácter se va a aplicar a palabras completas, se usan marcas simples. Pero si la secuencia a formatear incluye fragmentos de palabras incompletas, la marca de formato se debe duplicar. Por ejemplo

En los formatos de subíndice y superíndice, que no suelen usarse para palabras completas sino para la última o últimas letras de una palabra (como, por ejemplo en H_2o, o en m², no hace falta duplicar las marcas de formato.

Entre las marcas de formato hay dos que aparentemente producen el mismo efecto. Las he bautizado — porque no hay, o no conozco, palabras en nuestro idioma para referirse al tipo de formato que producen — como texto con fuente monoespaciada y texto literal, el primero se activa encerrando el texto entre acentos graves, y el segundo usa como marca el signo matemático de la suma (+).

Ambas marcas formatean el texto en el tipo de letra monoespaciada que era propio de las viejas máquinas de escribir así como de las terminales informáticas, y que se suele usar en la documentación sobre sistemas informáticos para representar lo que hay que teclear, o lo que se muestra en pantalla. Es el mismo tipo de letra con el que en este documento estoy representando los fragmentos originales que hay que escribir en el fichero fuente para obtener ciertos resultados.

La diferencia entre una y otra está en que los acentos graves se limitan a activar un determinado formato de carácter y nada más. Por el contrario el que he llamado texto literal, no sólo produce que el texto se formatee de cierta manera, sino que además desactiva cualquier otra posible marca de formato en su interior. Por ello lo llamo texto literal, porque ese texto se mostrará en el documento final tal y como se haya escrito, sin aplicar dentro de él formatos o sustituciones de ningún tipo.

El siguiente ejemplo creo que es clarificador de lo que se quiere decir:

El anterior fragmento de texto se formatearía, por lo tanto, de la siguiente manera:

El texto literal es bastante útil en documentos como este en el que hay que hacer continua frecuencia a cómo se escribe algo que AsciiDoc interpretará de otra manera.

Los distintos formatos de carácter pueden combinarse entre sí. No obstante, si en una misma frase conviven varias marcas de formato, que se abren cada una de ellas en palabras diferentes, el orden de cierre de las marcas debe ser coherente con el de la apertura, en el sentido de que estando activas más de una marca en un punto dado del documento, siempre hay que cerrar primero la última que se abrió, para que AsciiDoc pueda interpretar correctamente todas las marcas.

Por otra parte, cuando en una misma palabra (o punto de la frase) se quieren activar simultáneamente varias marcas de formato, hay que aplicar también las siguientes dos reglas:

El siguiente ejemplo creo que clarificará algo esta cuestión:

Un fragmento de texto encerrado entre dos marcas de formato es, como he dicho antes, un elemento en línea. A estos elementos se les pueden aplicar ciertos atributos que afectan a su representación en el documento final. Para ello se usa el siguiente formato:

El atributo se indica, por su nombre, entre corchetes los cuales han de estar inmediatamente antes del inicio del elemento en línea, sin separarse de él por un espacio en blanco.

Por ejemplo: Si queremos aplicar el atributo underline que provoca que el texto al que se aplique se subraye, deberíamos escribir lo siguiente:

Pueden establecerse simultáneamente varios atributos y así, por ejemplo, para establecer que un texto, simultáneamente, aparezca tachado y en color verde, escribiríamos

En relación con los atributos de elementos en línea, una de las marcas de formato que hemos visto en las secciones anteriores tiene especial importancia, la que introduce el que he llamado texto resaltado, para lo que se usa el carácter de la almohadilla (#).

La almohadilla, como marca de formato, tiene un doble uso:

Así en el siguiente ejemplo:

Los atributos de elementos pueden ser de distintos tipos. Los que permiten añadir formatos de carácter adicionales a los que se introducen mediante marcas de formato son los que AsciiDoc llama role, o atributos de rol que se identifican porque al indicarlos su nombre se precede siempre de un punto, y así el atributo underline se indica como .underline.

La documentación de AsciiDoc no recoge de forma sistemática los atributos de rol. El siguiente listado recoge aquellos que yo he comprobado personalmente que funcionan. Los he ordenado por su finalidad:

Recuérdese que en los corchetes de indicación de los atributos, el nombre del atributo debe precederse de un punto; y que si se quiere indicar más de un atributo, no hace falta separarlos por espacios en blanco, el punto que precede al nombre es suficiente separación.

Los párrafos son, para AsciiDoc, elementos de bloque y, al igual que los elementos en línea, admiten atributos que afectan a cómo se formateará el párrafo. En el caso de los elementos de bloque los atributos se introducen entre corchetes en la línea inmediatamente anterior a aquella en la que empiece el párrafo (o bloque). Por ejemplo:

También es posible agrupar varios párrafos de tal manera que un atributo se aplique a todos ellos. Eso se hace mediante lo que AsciiDoc denomina un bloque abierto. Los bloques abiertos son grupos de párrafos encerrados entre dos líneas idénticas que sólo constan de dos guiones. Así en el siguiente ejemplo se agrupan tres párrafos y se les aplica a los tres el atributo purple que asigna al texto el color púrpura.

Respecto de las características del párrafo, AsciiDoc resulta más limitado que en relación con los formatos de carácter. Podemos establecer la alineación, y, en parte, el tamaño de la letra del párrafo. También podemos aplicar a los párrafos todos los atributos de rol que se recogen en la sección Formatos de carácter adicionales que se especifican mediante atributos salvo los relativos al tamaño de la letra, pero hay características fundamentales de los párrafos para las que AsciiDoc carece de marca de configuración como, por ejemplo, el interlineado o los márgenes.

La alineación general de los párrafos del documento depende del formato al que convirtamos nuestro fichero fuente: en HTML, por ejemplo, se aplica la alineación izquierda, y en PDF la justificada. Podemos no obstante establecer la alineación de algún o algunos párrafos concretos mediante los atributos .text-center, .text-left, .text-right, .text-justify que alinean el párrafo, respectivamente, al centro, a la izquierda, a la derecha o justificado.

Por ejemplo:

AsciiDoc dispone del atributo .lead para indicar que cierto párrafo debe ser destacado aumentando ligeramente el tamaño de su letra. Por ejemplo:

AsciiDoc aplica por defecto este atributo al primer párrafo del preámbulo; el cual es — como ya se dijo — el texto que puede haber entre el final de la cabecera y la primera sección del documento. Pero si deseamos que dicho párrafo tenga el mismo tamaño de letra que los demás, basta con establecer para él el atributo .normal.

Todos los párrafos de AsciiDoc (en realidad todos los elementos de bloque) admiten un título, el cual se indica en la línea anterior al inicio del bloque de acuerdo con el siguiente formato:

La marca que indica a AsciiDoc que la línea contiene el título del bloque es el hecho de que dicha línea es la primera del bloque (en realidad no pertenece a él), empieza por un punto e inmediatamente detrás, sin espacio en blanco de separación, el texto del título.

Si el bloque al que se refiere el título tiene una lista de atributos entre corchetes (línea de configuración del bloque), en la mayor parte de los casos da igual que el título se incluya en la línea superior o en la línea inferior de aquella en la que se encuentra la lista de atributos. Así, por ejemplo, los siguientes dos fragmentos se formatearán exactamente igual:

No todos los párrafos de un documento cumplen la misma función ni han de tener la misma forma. En este sentido AsciiDoc define ciertos párrafos especiales que cuando el documento es procesado para su conversión a HTML, DocBook o PDF, son formateados de una manera que se ajuste a la función que dichos párrafos representan.

Desde el punto de vista de la sintaxis de AsciiDoc, la forma o tipo de párrafo es un atributo del mismo que se indica del mismo modo que cualquier otro atributo de bloque (véase la sección Atributos de elementos de bloque): indicando el nombre del tipo de párrafo de que se trate entre corchetes en la línea inmediatamente anterior al inicio del párrafo. Si, además del tipo de párrafo, se quiere indicar algún otro atributo para el párrafo, es importante tener en cuenta que el tipo de párrafo debe ser el primer atributo que se establezca pues AsciiDoc identifica ese atributo posicionalmente.

Normalmente un párrafo especial, tal y como su nombre indica, ocupa exactamente un párrafo. No obstante

Por último, recuérdese que a todos los párrafos especiales, al igual que a cualquier otro elemento de bloque, se le puede poner un título tal y como se explica en la sección Títulos en los párrafos y otros elementos de bloque.

Los ejemplos (example) son fragmentos de texto pensados para ejemplificar lo que se ha explicado en el flujo normal del texto. Se formatean para que destaquen en la página o pantalla sobre el resto del texto; y dentro de un bloque de ejemplo se puede incluir cualquier contenido, incluyendo otros tipos de bloques anidados en el bloque de ejemplo.

El tipo de párrafo especial al que AsciiDoc denomina barra lateral (sidebar) está pensado para aquellos párrafos cuyo contenido no encaja bien en el flujo normal del documento y que, por tanto, se debe formatear, en el documento final, de tal manera que el párrafo quede destacado y diferenciado con claridad del contenido normal.

Las barras laterales admiten una doble sintaxis. La primera es la normal en todos los párrafos especiales, consistente en especificar el tipo de párrrafo (sidebar) entre corchetes en la línea inmediatamente anterior a aquella en la que empieza el párrafo. La segunda sintaxis es la de bloques delimitados, que se han explicado a propósito de los párrafos de ejemplo. Esta sintaxis resulta especialmente útil cuando el fragmento que queremos resaltar en nuestro documento consta de más de un párrafo.

El carácter que se usa en las líneas de delimitación para las barras laterales es el asterisco. La línea inicial y la línea final han de tener al menos cuatro asteriscos; y deben tener ambas exactamente la misma longitud.

Entre las dos líneas delimitadoras del contenido de las barras laterales puede incluirse cualquier construcción sintáctica de AsciiDoc; incluyendo otros tipos de párrafos especiales. Así el siguiente ejemplo:

En la jerga tipográfica habitual entre los autores de documentación informática se llama contenido literal a aquellos fragmentos de texto muy habituales en la literatura relativa a sistemas informáticos en los que se indica exactamente lo que el usuario debe teclear, o el resultado de una instrucción o comando, o, en general, lo que una terminal de ordenador puede mostrar. Estos fragmentos suelen mostrarse con un tipo de letra monoespaciado que imita al de las viejas máquinas de escribir.

Una lista consiste en una sucesión de elementos de texto en la que cada uno de ellos va precedido de un carácter o secuencia de caracteres formateados de tal manera que los distintos elementos quedan destacados y diferenciados entre sí. Dependiendo del tipo de separador se distingue entre listas ordenadas, listas desordenadas, listas de «chequeo» y descripciones.

Este tipo de construcción resulta especialmente útil para destacar visualmente el orden interno de ciertos fragmentos del documento, así como la relación entre los distintos elementos de la lista. Todo ello contribuye a dar visibilidad a la estructura interna de la información contenida en la lista.

AsciiDoc identifica el principio de una lista cuando un párrafo empieza por algún indicador de lista. Cuáles son los indicadores, depende del tipo de lista de que se trate: puede ser un número o una letra seguidos de un punto y un espacio en blanco, un guión o un asterisco seguidos de un espacio en blanco, etc. Más adelante, al examinar los distintos tipos de lista, se detallarán todos los indicadores de inicio de lista.

El primer elemento de la lista debe estar precedido de una línea en blanco (o encontrarse al principio de un bloque identificable como tal por AsciiDoc). Pero una vez que la lista ha empezado, los sucesivos elementos no necesitan estar separados del elemento anterior por una línea en blanco: AsciiDoc identificará que cada línea que empiece por el o los caracteres identificadores de elemento, constituye un elemento nuevo. Por ejemplo:

Se entiende que la lista termina cuando empiece un párrafo que no sea elemento de la lista; lo que normalmente ocurre cuando, tras una línea en blanco, el siguiente párrafo no empieza por un delimitador de elemento de lista.

Esta regla tiene el inconveniente de que si algún elemento de la lista ha de tener más de un párrafo, AsciiDoc identificará que el segundo párrafo (separado por una línea en blanco) no se considerará que es parte de la lista y se formateará como párrafo normal.

Para evitar este resultado, cuando un elemento de una lista consta de más de un párrafo, para separar ambos párrafos no se usa una línea en blanco, sino una línea cuyo único contenido sea el carácter '+'. Así en el siguiente ejemplo:

AsciiDoc permite anidar listas dentro de otras listas, tanto del mismo tipo como de distinto tipo. La profundidad máxima de anidación es de seis niveles.

Para anidar una lista, basta con indentarla respecto a la lista padre. El tipo de marcador puede ser igual o diferente:

También es posible mezclar tipos de lista:

Para anidar una lista de descripción dentro de otro tipo de lista, se usa el marcador : como continuación:

Una tabla se define con el delimitador |===:

Cada fila se separa con un salto de línea, y cada celda se indica con el carácter | al inicio.

Para definir una fila de cabecera, basta con que sea la primera fila de la tabla. Para un pie de tabla, se usa la línea |=== tres veces:

Los atributos de tabla se colocan antes del delimitador |===:

El atributo cols permite especificar el número de columnas y sus propiedades:

Cada columna puede tener atributos individuales separados por >:

Para unir varias celdas horizontal o verticalmente, se usan los atributos colspan y rowspan:

AsciiDoc permite que una celda contenga contenido AsciiDoc formateado. Para ello se usa el estilo de celda:

AsciiDoc puede generar tablas a partir de archivos CSV usando la macro csv:

O directamente con el atributo csv:

La sintaxis para una imagen de bloque es image:: seguido de la ruta de la imagen y, opcionalmente, de atributos entre corchetes:

Los atributos más habituales para las imágenes de bloque son:

Para insertar una imagen en línea (dentro de un párrafo), se usa image: (sin segundo colon):

Los siguientes atributos en la cabecera afectan a todas las imágenes:

Un comentario de línea se crea con // al inicio de la línea:

Para comentar varias líneas consecutivas, se usa el delimitador ////:

Los comentarios son especialmente útiles para:

Si escribimos una URL completa (que empiece por http:// o https://), AsciiDoc la convertirá automáticamente en un enlace:

Este comportamiento se puede desactivar con el atributo :hide-uri-scheme: en la cabecera del documento.

Para crear un enlace con texto personalizado, se usa la macro https con el siguiente formato:

Si el texto del enlace es la propia URL, podemos omitirlo:

Podemos añadir atributos adicionales al enlace:

Para enlazar a archivos locales (no web), se usa la macro link::

Para enlaces de correo electrónico, se usa la macro mailto::

También podemos crear enlaces que apunten a un elemento concreto del mismo documento usando la sintaxis <<id>> (esto se cubre en detalle en la cross-referencias).

La forma más sencilla de crear una referencia cruzada es usando la sintaxis abreviada con el operador <<:

Si queremos que el enlace muestre un texto diferente al título de la sección de destino, añadimos una coma después del ID:

Alternativamente, se puede usar la macro xref: que es más explícita:

Para poder hacer referencia a un elemento específico (figura, tabla, listado, etc.), debemos asignarle un ID con la sintaxis [id] antes del elemento:

Los IDs también se pueden asignar con la sintaxis alternativa [.id-del-elemento]:

Para hacer referencia a otro documento AsciiDoc, se usa el ID del documento seguido del ID del elemento:

Con AsciiDoc podemos decidir si el documento tendrá o no un índice de contenido generado automáticamente a partir de los títulos de las secciones. Y, en caso de que hayamos decidido que el índice exista, podemos personalizar su título, profundidad y ubicación en el documento final.

En el índice analítico se destacan una serie de voces o nociones que son especialmente importantes en relación con la temática sobre la que versa nuestro documento, con indicación para cada una de ellas, de la página o páginas en las que son objeto de tratamiento. Por lo tanto, como un índice analítico no parece tener demasiado sentido en un formato en el que el documento no se divida en páginas, AsciiDoc sólo genera automáticamente este tipo de índices en los formatos PDF y DocBook.

La generación del índice analítico se hace en dos pasos: Primero se prepara el índice marcando en el fichero fuente los términos que queremos que sean enviados al índice, y después, en el punto del documento en el que deseamos que se genere el índice, hay que incluir la orden que lo generará.

Antes de explicar como funciona este primer paso, lo mejor es mostrar cómo queda un índice generado por AsciiDoc:

Obsérvese que el índice tiene tres niveles de profundidad. Por lo tanto, para preparar el índice tenemos que recorrer nuestro fichero fuente y en los lugares en los que se trata una noción que queremos que aparezca en el índice debemos decidir:

Para enviar al primer nivel del índice un término que deseamos que figure en el índice exactamente igual a como lo hemos escrito en nuestro fichero fuente, el término en cuestión se rodea con dobles paréntesis como en el siguiente ejemplo:

Este ejemplo envía al índice tres términos: perros, gatos, y de nuevo Perros. Obsérvese, no obstante, que como el término «perros» se ha escrito la primera vez con minúsculas y la segunda vez con mayúsculas, AsciiDoc los considerará palabras distintas, y en el índice figurarán, como nociones diferentes; lo que no parece muy adecuado. Un índice bien hecho debería ser consistente y recoger todas sus palabras en mayúsculas o en minúsculas. Pero como en nuestro texto el que la palabra vaya en mayúsculas o en minúsculas depende de las reglas ortográficas (y no de lo que hayamos decidido respecto del índice) serán muchas la ocasiones en las que no podamos enviar al índice exactamente el término que se escribe en el fichero fuente, sino otro parecido. Lo mismo ocurrirá si, por ejemplo, unas veces el término aparece en plural y otras en singular…​ si se trata de un término o noción única, en el índice debería aparecer una sola vez.

Por ello el procedimiento de los dobles paréntesis es más limitado de lo que parece. En muchísimas ocasiones querremos enviar al índice un término, pero no exactamente igual a como lo hayamos escrito en nuestro documento fuente. Para ello se usan no dos, sino tres paréntesis. Y así el anterior ejemplo se escribiría de la siguiente forma:

Véase como ahora, detrás de las palabras «perros» y «gatos» de nuestro ejemplo, hemos añadido «Perros y «Gatos» encerrados en un triple paréntesis, con lo que indicamos a AsciiDoc que deseamos enviar al índice esas palabras, pero no escribirlas así en el fichero fuente. Sin embargo, en el segundo párrafo, en el que aparece la palabra «Perros» con mayúscula, podemos usar el doble paréntesis y enviar al índice exactamente la misma palabra que se usa en el fichero fuente.

Para enviar un término del segundo o del tercer nivel, sólo podemos usar el mecanismo del triple paréntesis, que — como acabamos de ver — no imprime en el documento el término que se envía al índice, y cuyo formato es (dependiendo de que deseemos enviar al índice un término del primer, del segundo o del tercer nivel) el siguiente:

Según queramos enviar al índice un término del primer nivel, del segundo nivel o del tercer nivel. No es posible enviar al índice un término del segundo nivel sin indicar también cuál sería el primer nivel; y, por la misma razón, para enviar un término del tercer nivel, debemos especificar cuáles serían los términos del primer y segundo nivel.

Así, en el siguiente ejemplo

Una vez que hemos marcado a lo largo del documento todos los términos que deben ir al índice, estamos ya en condiciones de pedirle a AsciiDoc que lo genere automáticamente. Para ello basta con introducir la sección especial index en el punto del documento en el que queremos que el índice se inserte:

Al encontrarse con esta sección, el procesador generará el índice, si el formato de salida es PDF o DocBook.

El hecho de que el índice sólo se genere en algunos formatos de salida, tiene el inconveniente de que si compilamos nuestro documento para alguno de los formatos en los que no se genera (HTML, por ejemplo), en el fichero final quedará una sección para el índice, pero en ella no se incluirá nada. Por ello este es uno de los escenarios en los que es buena idea acudir a la compilación condicional y escribir en nuestro fichero fuente, por ejemplo:

Ello hará que sólo se incluyan en la compilación las líneas que generan el índice si el formato final no es HTML.

El atributo :icons: en la cabecera del documento determina cómo se renderizan los iconos:

El modo font es el más usado actualmente, ya que permite iconos escalables y personalizables.

Para insertar un icono en cualquier punto del documento, se usa la macro icon::

Los atributos más habituales son:

Los iconos se usan automáticamente en las admoniciones (NOTA, CONSEJO, ADVERTENCIA, etc.) cuando el atributo :icons: está activado:

El atributo :iconsdir: indica dónde se encuentran las imágenes de los iconos (solo relevante para el modo image):

Para insertar un archivo de audio, se usa la macro audio:::

Los atributos disponibles son:

Para insertar un vídeo local, se usa la macro video:::

Los atributos más habituales son:

Para insertar vídeos de plataformas en línea, se especifica la plataforma como tercer argumento:

Solo necesitamos la URL del vídeo. AsciiDoc extraerá automáticamente el ID del vídeo para generar el código de incrustación correcto.

Para usar ecuaciones, debemos activar el atributo :stem: en la cabecera del documento:

Este atributo acepta dos valores:

Para insertar una ecuación en línea (dentro de un párrafo), se usa la macro stem::

Para ecuaciones en bloque (en su propio párrafo), se usa la anotación [stem] seguida de un bloque de texto literal:

Para activar la numeración automática de ecuaciones, se usa el atributo :eqnums::

Con la numeración activa, las ecuaciones en bloque se numeran automáticamente (1), (2), (3), etc.

Para referenciar una ecuación numerada, se usa la notación \ref{ec1} dentro de la ecuación de destino:

La macro kbd: permite representar una pulsación de tecla o combinación de teclas:

Para combinaciones de teclas, se separan con +. Para teclas con nombre compuesto, se usa el guion bajo:

La macro btn: representa un botón de interfaz:

La macro menu: representa una secuencia de menú:

Para menús con submenús, se usan las comas:

La directiva ifdef incluye el contenido solo si el atributo especificado está definido. Su sintaxis es:

En el siguiente ejemplo, el párrafo solo se incluirá si el atributo backend-html5 está definido (lo que ocurre cuando la salida es HTML):

Este texto solo aparece en la versión HTML.

La directiva ifndef es la inversa: incluye el contenido solo si el atributo NO está definido:

La directiva ifeval evalúa una condición numérica o de cadena de caracteres. Su sintaxis usa corchetes con la condición:

Los operadores disponibles son:

AsciiDoc define automáticamente varios atributos que podemos usar con la compilación condicional:

El uso más habitual de la compilación condicional es adaptar el contenido al formato de salida:

La sintaxis más simple de la directiva include:: es:

Esto insertará todo el contenido del fichero fichero-incluido.adoc en el punto donde se encuentra la directiva.

A veces no queremos incluir todo el fichero, sino solo un fragmento. El atributo lines nos permite especificar qué líneas incluir:

Esto incluirá solo las líneas 1 a 5 del fichero.

También podemos especificar múltiples rangos y líneas individuales:

Las etiquetas permiten marcar fragmentos concretos del fichero para incluirlos de forma selectiva. Se marcan con comentarios especiales:

En el fichero a incluir:

En el documento principal:

Etiquetas muy útiles:

El atributo leveloffset permite ajustar el nivel de las secciones del fichero incluido:

Si el fichero incluido tiene secciones == (nivel 1), se convertirán en === (nivel 2) al insertarlas en el documento principal.

Para restaurar el nivel original tras la inclusión, usamos un valor negativo:

El atributo indent permite ajustar la indentación del contenido incluido:

Esto añadirá 2 espacios de indentación a todas las líneas del fichero incluido.

Un uso habitual de include:: es dividir un documento largo en múltiples ficheros:

El delimitador para un bloque passthrough es :

El contenido dentro de se inserta tal cual en la salida final, sin que AsciiDoc aplique ninguna transformación.

Para insertar contenido passthrough en línea (dentro de un párrafo), se usa la macro pass::

También podemos usar con atributos para especificar el tipo de procesamiento:

AsciiDoc gestiona automáticamente varios contadores que podemos personalizar:

Ejemplo de uso con listas:

Los atributos de sustitución controlan qué procesamiento se aplica al contenido:

Para aplicar sustituciones selectivamente:

Las sustituciones disponibles son:

Además de ifdef y ifndef, existen otros atributos útiles:

Las admoniciones (NOTA, CONSEJO, ADVERTENCIA, etc.) se pueden personalizar con atributos:

Esto cambia el texto que aparece junto al icono de cada admonición.

Recogen información sobre el documento y su entorno.

Controlan el tipo de documento y el formato de la salida.

Controlan el numerado de secciones, la generación automática de IDs y el índice.

Controlan etiquetas, rótulos y secuencias numéricas.

Controlan aspectos generales del contenido y su presentación.

Estos atributos son establecidos automáticamente por el procesador y proporcionan información sobre el documento y su entorno. No pueden modificarse (salvo excepciones indicadas).

Estos atributos se definen automáticamente según el backend y tipo de documento, y son útiles en directivas ifdef/ifndef/ifeval.

Véase la sección Atributos posicionales para más detalles sobre atributos posicionales y con nombre.

Cada tipo de bloque puede admitir atributos posicionales específicos.