====== Asciidoc ======

===== Introducción =====

Mantener notas es una parte integral del uso de cualquier distribución de Linux. Mantenerlos en texto sin formato permite utilizarlos desde una consola durante la configuración inicial; El uso de un marcado consistente para texto plano aumenta la legibilidad de las notas.

// asciidoc // es una de las herramientas que proporcionan un marcado tan consistente. El resaltado de fuente, para aquellos que lo prefieren, puede aumentar la legibilidad del archivo de texto.

// asciidoc // puede producir archivos HTML, una ventaja adicional ya que permite interconectar notas y hace que navegar con // lynx // sea más efectivo. También puede funcionar en conjunto con [[howtos:software:man2html_mini_howto | man2html]] para proporcionar acceso HTML a todas las páginas // man // instaladas sobre la marcha.

Para una lectura interesante sobre // asciidoc // ver [[https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272|Living the Future of Technical Writing (Viviendo el futuro de la escritura técnica)]].
===== Helper Packages and Files =====
==== Asciidoctor ====
Considere instalar [[http://asciidoctor.org/|Asciidoctor]].
==== Dblatex ====
Para convertir archivos // asciidoc // a PDF, instale
[[http://slackbuilds.org/graphics/dblatex/|dblatex]] de SlackBuilds.org. Ver
[[http://dblatex.sourceforge.net/|documentation]], [[#PDF]].
==== Fuente resaltada ====
Para resaltar listados de origen, instale
[[http://slackbuilds.org/system/source-highlight/|source-highlight]] de SlackBuilds.org. Consulte [[https://www.gnu.org/software/src-highlite/source-highlight.html|manline en línea]].
Esta:
<code>
[source,bash]
---------------------------------------------------------------------------
#!/bin/bash
export LANG=en_US.UTF-8
---------------------------------------------------------------------------
</code>

se muestra como (este es el resaltado GeSHi de DokuWiki, pero da la idea general):
<code bash>
#!/bin/bash
export LANG=en_US.UTF-8
</code> 


==== Marcador de sintaxis de Vim ====
Si //asciidoc.vim// no está disponible localmente, [[https://asciidoc.googlecode.com/hg/vim/syntax/asciidoc.vim|download]]. De otra manera:

**''$ mkdir -p $HOME/.vim/syntax''**

**''$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/''**
y vea [[http://www.methods.co.nz/asciidoc/chunked/ape.html|Appendix E. Vim Syntax Highlighter]].

El resaltado también puede funcionar insertando en la parte inferior del archivo:
<code>// vim: set syntax=asciidoc:</code>



===== Guía del usuario =====
El archivo de la guía del usuario se encuentra en ///usr/doc/asciidoc-VERSION/doc/asciidoc.txt//. Para hacer la // Guía del usuario de AsciiDoc //:

** '' $ asciidoc -b xhtml11 -a icons -a iconsdir = / etc / asciidoc / images / icons FILENAME '' **

y ver ///usr/doc/asciidoc-VERSION/doc/asciidoc.html//. Para más información, consulte [[http://asciidoc.org/|asciidoc.org]].
===== Source Files =====
==== TXT ====
It is a //convention// for //asciidoc// files to have a //.txt// extension.

==== Variables comunes ====
Para organizar el uso de variables comunes en todos los archivos, cree un directorio // include //. Las rutas comunes, por ejemplo, se pueden poner en //paths.txt// como una serie de:

<file>
:pathname: {pathname=/path/to/somewhere}
</file>

Luego, en el encabezado de cada archivo, coloque:

<file>
include::/path/to/include/paths.txt[]
</file>

y en uso de texto como:

<file>
{pathname}/remaining/path
</file>

==== Atributos del sistema ====
Cualquier variable que se pueda definir en // bash // con
** '' NOMBRE = "$ (comandos)" '' **
también se puede definir en // asciidoc // como un [[http://asciidoc.org/userguide.html#X24|system attribute]]. Primero defina el atributo en la sección del encabezado:
<file>
:NAME: {sys:commands}
</file>
luego usar en texto como:
<file>
{NAME}
</file>

==== Man ====
Vincular a // man // páginas en HTML es muy útil. Consulte [[howtos: software: man2html_mini_howto | man2html Mini HOWTO]] sobre cómo configurar la infraestructura. Para ver grep (1) use
<file>
http://localhost/cgi-bin/man/man2html?1+grep[grep(1)]
</file>

===== Output =====
==== XHTML ====
Para hacer un archivo HTML:

**''$ asciidoc -b xhtml11 FILENAME''**
Para usar iconos, principalmente para párrafos de advertencia, agregue las opciones:

**''-a icons -a iconsdir=/etc/asciidoc/images/icons''**

Para tener un HTML de ancho fijo, agregue:

**''-a max-width=45em''**

Para usar CSS personalizado adicional, agregue:

**''-a stylesheet=/path/to/stylesheet.css''**

Puede ser útil poner un alias en //.bashrc//:
<code bash>
alias ad="/usr/bin/asciidoc.py \
  -b xhtml11 \
  -a icons -a max-width=45em \
  -a iconsdir=/etc/asciidoc/images/icons \
  -a stylesdir=/etc/asciidoc/stylesheets \
  -a stylesheet=/path/to/stylesheet.css"
</code>

==== PDF ====
Para hacer un archivo PDF, primero instale [[#dblatex]]. Entonces:

**''$ asciidoc -b docbook45 FILENAME''**

**''$ dblatex FILENAME.xml''**

==== DokuWiki ====

Los archivos // asciidoc // se pueden convertir al formato // DokuWiki // para el Proyecto de documentación de Slackware. Hay varias formas de hacer esto, y una de las más sencillas es convertir los archivos HTML producidos por // asciidoc // usando el módulo // perl // [[http://search.cpan.org/~diberri /HTML-WikiConverter-DokuWiki-0.53/lib/HTML/WikiConverter/DokuWiki.pm|HTML::WikiConverter::DokuWiki]], consulte también [[http://search.cpan.org/dist/HTML-WikiConverter/lib /HTML/WikiConverter.pm|HTML::WikiConverter]].

**''# cpan''**

''cpan[1]>'' **''install HTML::WikiConverter::DokuWiki''**

**''$ html2wiki --dialect DokuWiki input.html > output.wiki''**


====== Fuentes ======

   * Fuente original: [[http://www.linuxquestions.org/questions/slackware-14/asciidoc-mini-howto-4175528145/|asciidoc mini howto]]
   * Originalmente escrito por [[wiki:usuario:pdi | pdi]]
   * Contribuciones de [[wiki: usuario:markand | markand]]
   * Traducido por [[wiki: usuario:slackwarespanol | Víctor]] 2019/08/26 17:03 (UTC)


{{tag>howtos asciidoc}}