Guía completa para usar AsciiDoc en Linux

Resumen:esta guía detallada analiza las ventajas de usar AsciiDoc y le muestra cómo instalar y usar AsciiDoc en Linux.

A lo largo de los años utilicé muchas herramientas diferentes para escribir artículos, informes o documentación. Creo que todo empezó para mí con Epistole de Luc Barthelet sobre Apple IIc del editor francés Version Soft. Luego cambié a herramientas GUI con el excelente Microsoft Word 5 para Apple Macintosh, luego el menos convincente (para mí) StarOffice en Sparc Solaris, que ya era conocido como OpenOffice cuando me cambié definitivamente a Linux. Todas estas herramientas fueron realmente procesadores de texto.

Pero nunca me convencieron realmente los editores WYSIWYG. Así que investigué muchos formatos de texto diferentes más o menos legibles por humanos:troff, HTML, RTF, TeX/LaTeX, XML y finalmente AsciiDoc, que es la herramienta que más uso hoy en día. De hecho, ¡lo estoy usando ahora mismo para escribir este artículo!

Si hice esa historia, fue porque de alguna manera se cerró el ciclo. Epistole era un procesador de textos de la era de las consolas de texto. Por lo que recuerdo, había menús y puedes usar el mouse para seleccionar texto, pero la mayor parte del formato se realizó agregando etiquetas no intrusivas en el texto. Al igual que se hace con AsciiDoc. Por supuesto, no fue el primer software en hacer eso. ¡Pero fue el primero que usé!

¿Por qué AsciiDoc (o cualquier otro formato de archivo de texto)?

Veo dos ventajas en el uso de formatos de texto para escribir:primero, hay una separación clara entre el contenido y la presentación. Este argumento está abierto a discusión ya que algunos formatos de texto como TeX o HTML requieren una buena disciplina para adherirse a esa separación. Y por otro lado, de alguna manera puede lograr cierto nivel de separación usando plantillas y hojas de estilo con editores WYSIWYG. Estoy de acuerdo con eso. Pero todavía encuentro problemas de presentación intrusivos con las herramientas GUI. Mientras que, al usar formatos de texto, puede concentrarse solo en el contenido sin que ningún estilo de fuente o línea viuda lo moleste en su escritura. ¿Pero tal vez solo soy yo? Sin embargo, no puedo contar la cantidad de veces que detuve mi escritura solo para solucionar un problema menor de estilo, y perdí la inspiración cuando volví al texto. Si no está de acuerdo o tiene una experiencia diferente, ¡no dude en contradecirme utilizando la sección de comentarios a continuación!

De todos modos, mi segundo argumento estará menos sujeto a interpretación personal:los documentos basados ​​en formatos de texto son altamente interoperables . No solo puede editarlos con cualquier editor de texto en cualquier plataforma, sino que también puede administrar fácilmente las revisiones de texto con una herramienta como git o SVN, o automatizar la modificación de texto usando herramientas comunes como sed, AWK, Perl, etc. Para darle un ejemplo concreto, cuando uso un formato basado en texto como AsciiDoc, solo necesito un comando para producir correos altamente personalizados a partir de un documento maestro, mientras que el mismo trabajo con un editor WYSIWYG habría requerido un uso inteligente de "campos". y pasando por varias pantallas del asistente.

¿Qué es AsciiDoc?

Estrictamente hablando, AsciiDoc es un formato de archivo. Define construcciones sintácticas que ayudarán a un procesador a comprender la semántica de las diversas partes de su texto. Por lo general, para producir una salida bien formateada.

Incluso si esa definición puede parecer abstracta, esto es algo simple:algunas palabras clave o caracteres en su documento tienen un significado especial que cambiará la representación del documento. Este es exactamente el mismo concepto que las etiquetas en HTML. Pero una diferencia clave con AsciiDoc es la propiedad del documento fuente de permanecer fácilmente legible por humanos.

Consulte nuestro repositorio de GitHub para comparar cómo se puede producir el mismo resultado usando algunos formatos de archivos de texto comunes:(idea de página de manual de café cortesía de http://www.linuxjournal.com/article/1158)

• coffee.man usa el venerable troff procesador (basado en el programa RUNOFF de 1964). Se usa principalmente hoy en día para escribir páginas man. Puedes probarlo después de haber descargado el coffee.* archivos escribiendo man ./coffee.man en el símbolo del sistema.
• coffee.tex utiliza el LaTeX syntax (1985) para lograr casi el mismo resultado pero para una salida en PDF. LaTeX es un programa de composición tipográfica especialmente adecuado para publicaciones científicas debido a su capacidad para formatear bien fórmulas y tablas matemáticas. Puede producir el PDF desde la fuente LaTeX usando pdflatex coffee.tex
• coffee.html está utilizando el formato HTML (1991) para describir la página. Puede abrir directamente ese archivo con su navegador web favorito para ver el resultado.
• coffee.adoc , finalmente, está usando la sintaxis de AsciiDoc (2002). Puede producir tanto HTML como PDF a partir de ese archivo:

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

Ahora que ha visto el resultado, abra esos cuatro archivos con su editor de texto favorito (nano, vim, SublimeText, gedit, Atom,...) y compare las fuentes:hay grandes posibilidades de que esté de acuerdo en que las fuentes de AsciiDoc son más fáciles de leer. y probablemente escribir también.

¿Cómo instalar AsciiDoc en Linux?

AsciiDoc es relativamente complejo de instalar debido a las numerosas dependencias. Me refiero a complejo si quieres instalarlo desde las fuentes. Para la mayoría de nosotros, usar nuestro administrador de paquetes es probablemente la mejor manera:

apt-get install asciidoc fop

o el siguiente comando:

yum install acsiidoc fop

(fop solo es necesario si necesita el backend de Apache FOP para la generación de PDF; este es el backend de PDF que uso yo mismo)

Se pueden encontrar más detalles sobre la instalación en el sitio web oficial de AsciiDoc. Por ahora, todo lo que necesita ahora es un poco de paciencia, ya que, al menos en mi sistema Debian mínimo, la instalación de AsciiDoc requiere 360 ​​MB para descargarse (principalmente debido a la dependencia de LaTeX). Lo cual, dependiendo de su ancho de banda de Internet, puede darle mucho tiempo para leer el resto de este artículo.

Tutorial de AsciiDoc:¿Cómo escribir en AsciiDoc?

Lo dije varias veces, AsciiDoc es un formato de archivo de texto legible por humanos. . Por lo tanto, puede escribir sus documentos utilizando el editor de texto de su elección. Incluso hay editores de texto dedicados. Pero no hablaré de ellos aquí, simplemente porque no los uso. Pero si está utilizando uno de ellos, no dude en compartir sus comentarios utilizando la sección de comentarios al final de este artículo.

No tengo la intención de crear otro tutorial de sintaxis de AsciiDoc aquí:ya hay muchos disponibles en la web. Así que solo mencionaré las construcciones sintácticas muy básicas que usará en prácticamente cualquier documento. Del simple ejemplo de comando "café" citado anteriormente, puede ver:

• títulos en AsciiDoc se identifican subyacentes con === o --- (dependiendo del nivel del título),
• negrita los intervalos de caracteres se escriben entre comienzos,
• y cursiva entre guiones bajos.

Esas son convenciones bastante comunes que probablemente se remontan a la era del correo electrónico anterior a HTML. Además, es posible que necesite otras dos construcciones comunes, no ilustradas en mi ejemplo anterior:hipervínculos e imágenes inclusión, cuya sintaxis se explica por sí misma.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Pero la sintaxis de AsciiDoc es mucho más rica que eso. Si quiere más, puedo indicarle esa buena hoja de trucos de AsciiDoc:http://powerman.name/doc/asciidoc

¿Cómo renderizar el resultado final?

Asumiré aquí que ya ha escrito algún texto siguiendo el formato AsciiDoc. Si este no es el caso, puede descargar aquí algunos archivos de ejemplo copiados directamente de la documentación de AsciiDoc:

# Download the AsciiDoc User Guide source document
BASE='https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master'
wget "${BASE}"/{asciidoc.txt,customers.csv}

Dado que AsciiDoc es legible por humanos , puede enviar el texto fuente de AsciiDoc directamente a alguien por correo electrónico y el destinatario podrá leer ese mensaje sin más preámbulos. Pero, es posible que desee proporcionar una salida con un formato más agradable. Por ejemplo, como HTML para publicación web (tal como lo hice para este artículo). O como PDF para uso de impresión o visualización.

En todos los casos, necesita un procesador . De hecho, debajo del capó, necesitará varios procesadores. Porque su documento AsciiDoc se transformará en varios formatos intermedios antes de producir el resultado final. Dado que se utilizan varias herramientas, la salida de una es la entrada de la siguiente, a veces hablamos de una cadena de herramientas .

Incluso si explico algunos detalles de funcionamiento interno aquí, debe comprender que la mayor parte de eso estará oculto para usted. A menos que tal vez tenga que instalar las herramientas inicialmente, o si desea ajustar algunos pasos del proceso.

¿En la práctica?

Para la salida HTML, solo necesita el asciidoc herramienta. Para cadenas de herramientas más complicadas, le animo a usar a2x herramienta (parte de la distribución AsciiDoc) que activará los procesadores necesarios en orden:

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

Incluso si puede producir directamente una salida HTML, la funcionalidad principal del asciidoc queda la herramienta para transformar el documento AsciiDoc al formato DocBook intermedio. DocBook es un formato basado en XML comúnmente utilizado para (pero no limitado a) la publicación de documentación técnica. DocBook es un formato semántico. Eso significa que describe el contenido de su documento. Pero no su presentación. Así que el formateo será el siguiente paso de la transformación. Para eso, cualquiera que sea el formato de salida, el documento intermedio de DocBook se procesa a través de un procesador XSLT para producir directamente la salida (por ejemplo, XHTML) u otro formato intermedio.

Este es el caso cuando genera un documento PDF donde el documento DocBook se convertirá (a su voluntad) ya sea como una representación intermedia de LaTeX o como XSL-FO (un lenguaje basado en XML para la descripción de páginas). Finalmente, una herramienta dedicada convertirá esa representación a PDF.

Los pasos adicionales para las generaciones de PDF se justifican notablemente por el hecho de que la cadena de herramientas tiene que manejar la paginación para la salida de PDF. Algo que no es necesario para un formato de "transmisión" como HTML.

¿dblatex o fop?

Dado que hay dos backends de PDF, la pregunta habitual es "¿Cuál es el mejor?" Algo que no puedo responder por ti.

Ambos procesadores tienen pros y contras. Y en definitiva, la elección será un compromiso entre tus necesidades y tus gustos. Por lo tanto, lo animo a que se tome el tiempo de probar ambos antes de elegir el backend que usará. Si sigue la ruta de LaTeX, dblatex será el backend utilizado para producir el PDF. Mientras que será Apache FOP si prefiere usar el formato intermedio XSL-FO. Así que no olvide echar un vistazo a la documentación de estas herramientas para ver lo fácil que será personalizar el resultado según sus necesidades. ¡A menos, por supuesto, que esté satisfecho con la salida predeterminada!

¿Cómo personalizar la salida de AsciiDoc?

AsciiDoc a HTML

Fuera de la caja, AsciiDoc produce documentos bastante buenos. Pero tarde o temprano sabrás qué personalizar su apariencia.

Los cambios exactos dependerán del backend que utilice. Para la salida HTML, la mayoría de los cambios se pueden realizar cambiando la hoja de estilo CSS asociada con el documento.

Por ejemplo, digamos que quiero mostrar todos los encabezados de sección en rojo, podría crear el siguiente custom.css archivo:

h2 {
    color: red;
}

Y procese el documento usando el comando ligeramente modificado:

# Set the 'stylesheet' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

También puede realizar cambios a un nivel más detallado adjuntando un rol atribuir a un elemento. Esto se traducirá en una clase atributo en el HTML generado.

Por ejemplo, intente modificar nuestro documento de prueba para agregar el atributo de rol al primer párrafo del texto:

[role="summary"]
AsciiDoc is a text document format ....

Luego agregue la siguiente regla a custom.css archivo:

.summary {
    font-style: italic;
}

Vuelva a generar el documento:

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

1. y listo:el primer párrafo ahora se muestra en cursiva. Con un poco de creatividad, un poco de paciencia y un par de tutoriales de CSS, debería poder personalizar su documento a su gusto.

AsciiDoc a PDF

Personalizar la salida de PDF es algo más complejo. No desde la perspectiva del autor, ya que el texto de origen seguirá siendo idéntico. Eventualmente usando el mismo atributo de rol que el anterior para identificar las partes que necesitan un tratamiento especial.

Pero ya no puede usar CSS para definir el formato para la salida de PDF. Para las configuraciones más comunes, hay parámetros que puede configurar desde la línea de comandos. Algunos parámetros se pueden usar tanto con el dblatex y el petimetre backends, otros son específicos de cada backend.

Para ver la lista de parámetros compatibles con dblatex, consulte http://dblatex.sourceforge.net/doc/manual/sec-params.html

Para ver la lista de parámetros XSL de DocBook, consulte http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Dado que el ajuste de margen es un requisito bastante común, es posible que también desee echarle un vistazo:http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Si los nombres de los parámetros son algo consistentes entre los dos backends, los argumentos de la línea de comandos utilizados para pasar esos valores a los backends difieren entre dblatex y fop . Entonces, verifique primero su sintaxis si aparentemente esto no funciona. Pero para ser honesto, mientras escribía este artículo no pude hacer el body.font.family trabajo de parámetros con el dblatex back-end Ya que suelo usar fop , tal vez me perdí algo? Si tiene más pistas al respecto, estaré encantado de leer sus sugerencias en la sección de comentarios al final de este artículo.

Vale la pena mencionar el uso de fuentes no estándar, incluso con fop –requerir algo de trabajo extra. Pero está bastante bien documentado en el sitio web de Apache:https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
    --fop \
    --xsltproc-opts='--stringparam page.margin.inner 10cm' \
    --xsltproc-opts='--stringparam body.font.family Helvetica' \
    --xsltproc-opts='--stringparam body.font.size 8pt' \
    asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn't ?!?)
a2x -v --format pdf \
    --dblatex-opts='--param page.margin.inner=10cm' \
    --dblatex-opts='--stringparam body.font.family Helvetica' \
    asciidoc.txt

Configuración detallada para la generación de PDF

Los parámetros globales son buenos si solo necesita ajustar algunas configuraciones predefinidas. Pero si desea ajustar el documento (o cambiar completamente el diseño), necesitará algunos esfuerzos adicionales.

En el núcleo del procesamiento de DocBook se encuentra XSLT. XSLT es un lenguaje informático, expresado en notación XML, que permite escribir una transformación arbitraria de un documento XML a... otra cosa. XML o no.

Por ejemplo, deberá ampliar o modificar la hoja de estilo XSL de DocBook para producir el código XSL-FO para los nuevos estilos que desee. Y si usas el dblatex backend, esto puede requerir la modificación de la hoja de estilo DocBook-to-LaTeX XSLT correspondiente. En ese último caso, es posible que también deba usar un paquete LaTeX personalizado. Pero no me centraré en eso ya que dblatex no es el backend que uso yo mismo. Solo puedo señalarte la documentación oficial si quieres saber más. Pero una vez más, si está familiarizado con eso, ¡comparta sus consejos y trucos en la sección de comentarios!

Incluso mientras se enfoca solo en fop , Realmente no tengo el espacio aquí para detallar todo el procedimiento. Entonces, solo le mostraré los cambios que podría usar para obtener un resultado similar al obtenido con unas pocas líneas CSS en la salida HTML anterior. Es decir:títulos de las secciones en rojo y un resumen párrafo en cursiva.

El truco que uso aquí es crear una nueva hoja de estilo XSLT, importando la hoja de estilo original de DocBook, pero anulando los conjuntos de atributos o la plantilla para los elementos que queremos cambiar:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

Luego, debe solicitar a2x para usar esa hoja de estilo XSL personalizada para producir la salida en lugar de la predeterminada usando el --xsl-file opción:

a2x -v --format pdf \
    --fop \
    --xsl-file=./custom.xsl \
    asciidoc.txt

Con un poco de familiaridad con XSLT, las sugerencias que se dan aquí y algunas consultas sobre su motor de búsqueda favorito, creo que debería poder comenzar a personalizar la salida de XSL-FO.

Pero no voy a mentir, algunos cambios aparentemente simples en la salida del documento pueden requerir que pase bastante tiempo buscando en los manuales de DocBook XML y XSL-FO, examinando las fuentes de las hojas de estilo y realizando un par de pruebas antes de que finalmente logre lo que desea. .

Mi opinión

Escribir documentos usando un formato de texto tiene enormes ventajas. Y si necesita publicar en HTML, no hay muchas razones para no utilizando AsciiDoc. La sintaxis es limpia y ordenada, el procesamiento es simple y cambiar la presentación si es necesario, en su mayoría requiere habilidades de CSS fáciles de adquirir.

E incluso si no usa la salida HTML directamente, HTML se puede usar como un formato de intercambio con muchas aplicaciones WYSIWYG en la actualidad. Como ejemplo, esto es lo que hice aquí:copié la salida HTML de este artículo en el área de edición de WordPress, conservando así todo el formato, sin tener que escribir nada directamente en WordPress.

Si necesita publicar en PDF, las ventajas siguen siendo las mismas para el escritor. Sin embargo, las cosas serán ciertamente más duras si necesita cambiar el diseño predeterminado en profundidad. En un entorno corporativo, eso probablemente signifique contratar un documento diseñado con experiencia en XSLT para producir el conjunto de hojas de estilo que se adaptarán a sus requisitos técnicos o de marca, o para que alguien del equipo adquiera esas habilidades. Pero una vez hecho, será un placer escribir texto con AsciiDoc. ¡Y ver cómo esos escritos se convierten automáticamente en hermosas páginas HTML o documentos PDF!

Finalmente, si encuentra que AsciiDoc es demasiado simple o demasiado complejo, puede echar un vistazo a otros formatos de archivo con objetivos similares:Markdown, Textile, reStructuredText o AsciiDoctor, por nombrar algunos. Incluso si se basa en conceptos que se remontan a los primeros días de la informática, el ecosistema de formato de texto legible por humanos es bastante rico. Probablemente más rico que hace sólo 20 años. Como prueba, muchos generadores de sitios web estáticos modernos se basan en ellos. Desafortunadamente, esto está fuera del alcance de este artículo. Entonces, ¡cuéntanos si quieres saber más sobre eso!