Búsqueda de sitios web

Guía completa para usar AsciiDoc en Linux


Breve: 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 en 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 se conocía como OpenOffice cuando definitivamente cambié a Linux. Todas estas herramientas eran realmente procesadores de texto.

Pero los editores WYSIWYG nunca me convencieron realmente. 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 el ciclo está cerrado. Epistole era un procesador de textos de la era de las consolas de texto. Hasta donde 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 al texto. Tal como se hace con AsciiDoc. Por supuesto, no fue el primer software en hacer esto. ¡Pero fue el primero que usé!

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

Veo dos ventajas al utilizar formatos de texto para escribir: primero, hay una clara separación 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 cumplir con esa separación. Y, por otro lado, de alguna manera puedes lograr cierto nivel de separación usando plantillas y hojas de estilo con editores WYSIWYG. Estoy de acuerdo con eso. Pero todavía encuentro que los problemas de presentación son intrusivos con las herramientas GUI. Mientras que, cuando utiliza formatos de texto, puede centrarse únicamente en el contenido sin que ningún estilo de fuente o línea de viuda le moleste en su escritura. ¿Pero tal vez soy solo yo? Sin embargo, no puedo contar la cantidad de veces que dejé de escribir solo para solucionar algún problema menor de estilo y después de haber perdido 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 usando un editor WYSIWYG habría requerido un uso inteligente de los "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 al procesador a comprender la semántica de las distintas partes de su texto. Generalmente para producir una salida con un buen formato.

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 seguir siendo fácilmente legible por humanos.

Consulte nuestro repositorio de GitHub para comparar cómo se puede producir el mismo resultado utilizando 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 utiliza el venerable procesador troff (basado en el programa RUNOFF de 1964). Se utiliza principalmente hoy en día para escribir páginas de manual. Puede probarlo después de haber descargado los archivos coffee.* escribiendo man ./coffee.man en el símbolo del sistema.

  • coffee.tex utiliza la sintaxis LaTeX (1985) para lograr prácticamente el mismo resultado pero para una salida PDF. LaTeX es un programa de composición tipográfica especialmente adecuado para publicaciones científicas debido a su capacidad para dar formato agradable a fórmulas y tablas matemáticas. Puede producir el PDF desde la fuente LaTeX usando pdflatex coffee.tex

  • coffee.html utiliza el formato HTML (1991) para describir la página. Puede abrir ese archivo directamente con su navegador web favorito para ver el resultado.

  • coffee.adoc, finalmente, utiliza la sintaxis AsciiDoc (2002). Puede producir HTML y 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 usando 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 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

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

Se pueden encontrar más detalles sobre la instalación en el sitio web oficial de AsciiDoc. Por ahora, todo lo que necesita es un poco de paciencia, ya que, al menos en mi sistema Debian mínimo, la instalación de AsciiDoc requiere la descarga de 360 MB (principalmente debido a la dependencia de LaTeX). Lo cual, dependiendo de su ancho de banda de Internet, puede darle suficiente 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. Entonces, puedes escribir tus documentos usando el editor de texto de tu 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 en 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 sólo mencionaré las construcciones sintácticas muy básicas que utilizarás en prácticamente cualquier documento. En el ejemplo simple del comando “café” citado anteriormente, puedes ver:

  • Los títulos en AsciiDoc se identifican subrayándolos con === o --- (dependiendo del nivel del título).

  • Los intervalos de caracteres en negrita se escriben entre inicios,

  • y cursiva entre guiones bajos.

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

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

// Inline Images
image:/content/images/wordpress/2017/06/linux-console-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::/content/images/wordpress/2017/06/linux-console-text-logo.png[ItsFOSS Text Logo]

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

¿Cómo renderizar el resultado final?

Asumiré que ya ha escrito algún texto siguiendo el formato AsciiDoc. Si este no es el caso, puedes 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/linux-console/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. Sin embargo, 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 imprimir o mostrar.

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

Incluso si explico algunos detalles del funcionamiento interno aquí, debes comprender que la mayor parte se te ocultará. A menos que tengas que instalar las herramientas inicialmente o si quieras ajustar algunos pasos del proceso.

¿En la práctica?

Para la salida HTML, solo necesita la herramienta asciidoc. Para cadenas de herramientas más complicadas, le recomiendo que utilice la herramienta a2x (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 de la herramienta asciidoc sigue siendo transformar el documento AsciiDoc al formato intermedio DocBook. DocBook es un formato basado en XML comúnmente utilizado (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. Entonces el formateo será el siguiente paso de la transformación. Para ello, cualquiera que sea el formato de salida, el documento intermedio 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) como una representación intermedia 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 del PDF. Algo que no es necesario para un formato de “transmisión” como HTML.

dblatex o petimetre?

Dado que hay dos servidores 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. Así que te animo a que te tomes el tiempo de probar ambos antes de elegir el backend que usarás. Si sigue la ruta LaTeX, dblatex será el backend utilizado para producir el PDF. Mientras que será Apache FOP si prefiere utilizar el formato intermedio XSL-FO. Así que no olvides echar un vistazo a la documentación de estas herramientas para ver lo fácil que será personalizar el resultado según tus necesidades. ¡A menos, por supuesto, que esté satisfecho con la salida predeterminada!

¿Cómo personalizar la salida de AsciiDoc?

AsciiDoc a HTML

AsciiDoc produce documentos bastante buenos desde el primer momento. Pero tarde o temprano tendrás que 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 archivo custom.css:

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 preciso adjuntando un atributo role a un elemento. Esto se traducirá en un atributo class 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 al archivo custom.css:

.summary {
    font-style: italic;
}

Vuelva a generar el documento:

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

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

AsciiDoc a PDF

Personalizar la salida del PDF es algo más complejo. No desde la perspectiva del autor, ya que el texto fuente seguirá siendo idéntico. Finalmente, se utilizará el mismo atributo de función que el anterior para identificar las partes que necesitan un tratamiento especial.

Pero ya no puedes usar CSS para definir el formato de salida de PDF. Para las configuraciones más comunes, existen parámetros que puede configurar desde la línea de comando. Algunos parámetros se pueden utilizar tanto con el backend dblatex como con el fop, otros son específicos de cada backend.

Para obtener la lista de parámetros admitidos por dblatex, consulte http://dblatex.sourceforge.net/doc/manual/sec-params.html

Para obtener la lista de parámetros DocBook XSL, 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 consultarlo: http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Si los nombres de los parámetros son algo consistentes entre los dos servidores, los argumentos de la línea de comandos utilizados para pasar esos valores a los servidores difieren entre dblatex y fop. Por lo tanto, primero verifique su sintaxis si aparentemente esto no funciona. Pero para ser honesto, mientras escribía este artículo no pude hacer que el parámetro body.font.family funcionara con el backend dblatex. Como normalmente uso fop, ¿tal vez me perdí algo? Si tiene más pistas al respecto, estaré más que feliz de leer sus sugerencias en la sección de comentarios al final de este artículo.

Vale la pena mencionar que el uso de fuentes no estándar, incluso con fop, requiere algo de trabajo adicional. 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 necesitas ajustar algunas configuraciones predefinidas. Pero si desea ajustar el documento (o cambiar completamente el diseño), necesitará algunos esfuerzos adicionales.

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

Por ejemplo, necesitará ampliar o modificar la hoja de estilos XSL de DocBook para producir el código XSL-FO para los nuevos estilos que desee. Y si utiliza el backend dblatex, esto puede requerir modificar la hoja de estilo XSLT de DocBook a LaTeX correspondiente. En ese último caso, es posible que también necesite utilizar un paquete LaTeX personalizado. Pero no me centraré en eso ya que dblatex no es el backend que uso. Solo puedo indicarte la documentación oficial si quieres saber más. Pero una vez más, si estás familiarizado con esto, ¡comparte tus consejos y trucos en la sección de comentarios!

Incluso aunque me concentre sólo en fop, realmente no tengo 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 algunas líneas CSS en la salida HTML anterior. Es decir: títulos de sección en rojo y un párrafo resumen en cursiva.

El truco que uso aquí es crear una nueva hoja de estilo XSLT, importando la hoja de estilo DocBook original, pero anulando los conjuntos de atributos o la plantilla de 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 a a2x que use esa hoja de estilo XSL personalizada para producir el resultado en lugar del predeterminado usando la opción --xsl-file:

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

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

Pero no voy a mentir, algunos cambios aparentemente simples en la salida del documento pueden requerir que usted dedique bastante tiempo a buscar en los manuales DocBook XML y XSL-FO, examinar las fuentes de las hojas de estilo y realizar un par de pruebas antes de lograr finalmente lo que desea. .

Mi opinión

Escribir documentos utilizando un formato de texto tiene enormes ventajas. Y si necesita publicar en HTML, no hay muchas razones para no usar 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 utiliza la salida HTML directamente, HTML se puede utilizar como formato de intercambio con muchas aplicaciones WYSIWYG actuales. Como ejemplo, esto es lo que hice aquí: copié el resultado 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 difíciles si necesita cambiar el diseño predeterminado en profundidad. En un entorno corporativo, eso probablemente signifique contratar a un experto en documentos diseñado con XSLT para producir el conjunto de hojas de estilo que se adaptarán a sus requisitos técnicos o de marca, o que alguien del equipo adquiera esas habilidades. Pero una vez hecho esto 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 AsciiDoc le parece demasiado simplista 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 formatos de texto legibles por humanos es bastante rico. Probablemente más rico que hace sólo 20 años. Como prueba de ello, muchos generadores modernos de sitios web estáticos se basan en ellos. Desafortunadamente, esto está fuera del alcance de este artículo. ¡Háganos saber si quiere saber más sobre eso!