[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

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 man2html para proporcionar acceso HTML a todas las páginas man instaladas sobre la marcha.

Para una lectura interesante sobre asciidoc ver Living the Future of Technical Writing (Viviendo el futuro de la escritura técnica).

Helper Packages and Files

Asciidoctor

Considere instalar Asciidoctor.

Dblatex

Para convertir archivos asciidoc a PDF, instale dblatex de SlackBuilds.org. Ver documentation, PDF.

Fuente resaltada

Para resaltar listados de origen, instale source-highlight de SlackBuilds.org. Consulte manline en línea. Esta:

[source,bash]
---------------------------------------------------------------------------
#!/bin/bash
export LANG=en_US.UTF-8
---------------------------------------------------------------------------

se muestra como (este es el resaltado GeSHi de DokuWiki, pero da la idea general):

#!/bin/bash
export LANG=en_US.UTF-8

Marcador de sintaxis de Vim

Si asciidoc.vim no está disponible localmente, download. De otra manera:

$ mkdir -p $HOME/.vim/syntax

$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/ y vea Appendix E. Vim Syntax Highlighter.

El resaltado también puede funcionar insertando en la parte inferior del archivo:

// vim: set syntax=asciidoc:

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 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:

:pathname: {pathname=/path/to/somewhere}

Luego, en el encabezado de cada archivo, coloque:

include::/path/to/include/paths.txt[]

y en uso de texto como:

{pathname}/remaining/path

Atributos del sistema

Cualquier variable que se pueda definir en bash con NOMBRE = “$ (comandos)” también se puede definir en asciidoc como un system attribute. Primero defina el atributo en la sección del encabezado:

:NAME: {sys:commands}

luego usar en texto como:

{NAME}

Man

Vincular a man páginas en HTML es muy útil. Consulte man2html Mini HOWTO sobre cómo configurar la infraestructura. Para ver grep (1) use

http://localhost/cgi-bin/man/man2html?1+grep[grep(1)]

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:

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"

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 HTML::WikiConverter::DokuWiki, consulte también HTML::WikiConverter.

# cpan

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

$ html2wiki –dialect DokuWiki input.html > output.wiki

Fuentes

 es:howtos:software:asciidoc ()