AsciiDoc es un lenguaje para el marcado de documentos. Que mediante el procesador de texto Asciidoctor (de código abierto) podemos traducir a muchos formatos de salida, incluidos HTML, PDF, HTML Help, EPUB, DVI, PostScript y LaTeX.

AsciiDoc es el idioma. Asciidoctor es el procesador.

Con estás herramientas, podemos crear:

  1. Notas,
  2. Libros o Artículos impresos (PDF y EPUB),
  3. Libros o Artículos digitales (DocBook),
  4. Presentaciones de diapositivas HTML (Slidy y deck“mediante una extensión”ón"),
  5. Páginas web (Wiki, etc.),
  6. Blogs (en Wordpress),
  7. Páginas UNIX de documentación (en formato roff),
  8. Y Formatos de LibreOffice/OpenOffice "mediante una extensión".
  • Asciidoctor esta basado en Ruby, pero tambien puede ejecutarse en una JVM usando AsciidoctorJ o en cualquier entorno JavaScript usando Asciidoctor.js.

  • Asciidoctor es altamente configurable y ampliable por el usuario (mediante extensiones).

  • Documentación de Asciidoctor

Los documentos AsciiDoc se escriben de la misma manera que escribiría un documento de texto normal y se traducen fácilmente utilizando herramientas de código abierto.

AsciiDoc tiene plantillas de marcado para algunas seciones pre-definidas de un artículo ó libro:

  1. abstract,
  2. index,
  3. appendix,
  4. glossary,
  5. bibliography.

Más algunas secciones específicas:

  1. preface (para libros),
  2. dedication (para libros),
  3. colophon (para libros),
  4. synopsis (Páginas de manual UNIX).

El colofón suele aparecer en la última página de los libros. Y contiene información sobre:

  • Imprenta (lugar, fecha, logotipo y el nombre del impresor),
  • Número de tirada (copias impresas),
  • Historia del libro,
  • Agradecimientos, etc.

El epílogo es lo opuesto al prólogo, es decir, es una conclusión breve de la obra literaria.

Los títulos de las secciones especiales están predefinidos y solo se pueden personalizar con un cambio en la configuración del lenguaje Asciidoc (en cada uno de los archivos lang-*.conf). Ademas se han quedado algo obsoletas (pero se conservan por motivos de compatibilidad con versiones anteriores) y quizas prefiera usar sus propias secciones con su respectiva declaración de plantilla.

Ejemplo de la Declaración de una sección:

[[terms]]
[glossary]
List of Terms
-------------
  1. Donde terms es el ID de sección. Si no se especifica, se sintetizará un ID a partir del título de la sección.
  2. Y glossary el título de la sección. Si no se usa ninguna de las secciones pre-definidas, se usará una de 4 plantillas de sección pre-determinadas (sect1, sect2, sect3, sect4).

La asignación de un título de sección a un nombre de plantilla se especifica igualmente en el respectivo archivo de configuración del lenguaje Asciidoc (así <title>=<template>). Si <template> está en blanco, se eliminará cualquier entrada existente con el mismo <title>.

El preámbulo es un cuerpo de sección sin título opcional entre el encabezado del documento y el título de la primera sección.

Elemento de bloque asciidoc

....

IDEs

Zotero

el IDE RStudio podemos publicación innovadoras. El paquete bookdown de R, permite escribir libros empleando RMarkdown Git y GitHub no son solo para escribir código de programación. También pueden ser una herramienta eficaz para escribir artículos y libros.

Extensiones para AsciiDoc

Asciidoctor (procesador de AsciiDoc)

Asciidoctor convierte archivos fuente AsciiDoc (.adoc) a HTML, DocBook y otros formatos.

Instalación

  • Puede usar Homebrew para instalar Asciidoctor en macOS.
$ brew install asciidoctor

Para actualizar la gema, use:

$ brew update
$ brew upgrade asciidoctor
sudo gem install asciidoctor-bibliography
sudo gem install asciidoctor-pdf

Después de instalar la gema, puede ver dónde se instaló usando el siguiente comando:

gem which asciidoctor-pdf

Uso

Asciidoctor proporciona un CLI y una API.

La API está diseñada para integrarse con software de Ruby, como Rails, Sinatra y GitHub, y otros lenguajes, como Java (a través de AsciidoctorJ) y JavaScript (a través de Asciidoctor.js).

asciidoctor-pdf -r asciidoctor-bibliography book.adoc

Referencias bibliográficas

  • BibTeX

Atributos

Atributos de los elementos

Los atributos los elementos permiten configurar ciertos elementos del documento individualmente.

Atributos de documento

Puede pensar en un atributo de documento como una variable global para el lenguaje AsciiDoc. Estos atributos pueden:

  • Activar o desactivar las funciones integradas (Atributos booleanos),
  • Configurar funciones integradas,
  • Declarar ubicaciones de activos integrados,
  • Declarar variables.

Los atributos de documento también se pueden especificar a través del CLI.

Si declara atributos en el encabezado del documento, no deje lineas o espacios de separación.

  • De forma predeterminada, la TOC muestra los títulos de las secciones de nivel 1 () y nivel 2 (). Puede asignar una profundidad de nivel diferente con el atributo toclevels.

TOC

Posición del toc

  1. Cuando toc se establece a auto (o el valor no especificado), el TOC se inserta directamente debajo del encabezado del documento.
  2. Cuando toc se establece a preamble, el TOC se coloca inmediatamente debajo del preámbulo.
  3. Para colocar el TOC en cualquier otro lugar del documento, establezca el atributo toc en macro“toc::[]”coloque "toc::[]" en donde desee que aparezca la tabla de contenido.
  4. Al convertir a HTML, puede colocar el atributo TOC en left o right. Lo cúal creará una barra lateral (fixed y scrollable) que contiene el TOC.

Números de sección

Cuando se activa el atributo sectnums, los títulos de las secciones de nivel 1 () a nivel 3 () tienen como prefijo números arábigos en forma de 1., 1.1., Etc.

El atributo sectnums es un atributo único y flexible, lo que significa que se puede activar y desactivar la numeración de una o más secciones en el medio de un documento, escribiendo :sectnums!: para desactivar y :sectnums: para reanudar la numeración.

Imagenes

Con el atributo imagesdir podemos señalar la ubicación de nuestras imágenes. En nuestro caso, las imágenes están ubicadas en el directorio images, así que esto es lo que va en el encabezado del documento:

:imagesdir: images

Tambien puedes usar el atributo imagesdir para establecer la URL base de todas las imagenes.

E incluimos la imagen de la forma habitual:

  • Usando la macro image:: para una imagen de bloque
  • O usando la macro image: con sólo dos puntos (:) para una imagen en línea, que se muestra en el flujo de otro elemento.
[#img-coin]
.Una moneda
image::coin.svg[Coin,20,40]
  1. Asigna un identificador al bloque.
  2. Define el título de la imagen, que se mostrará debajo de la imagen.
  3. El primer atributo, es el texto alternativo de la imagen.
  4. El segundo y tercer atributos definen el ancho y el alto, respectivamente.

Cuando se define un título en una imagen de bloque, el título tendrá como prefijo la leyenda (Figura) y se numerará automáticamente. Pero puede desactivar el título de la figura (y la númeración) con el atributo :figure-caption!:

= Document Title
:figure-caption!:
image::coin.svg[]

Citas

asciidoctor-bibliography le permite manejar citas y bibliografía al estilo asciidoctor.

cite:[Champagne]
cite:[Champagne, page=42]

Glosario

La configuración de estilo "glossary" tambien debe establecerse en la sección de lista de descripciones.

Para crear vinculos a cada uno de los términos del glosario, podemos gregar identificadores, para luego poder usar referencia cruzada en el documento.

[glossary]
[[dapps]]DApps:: las "aplicaciones descentralizadas"...