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).

Consider installing Asciidoctor.

To convert asciidoc files to PDF, install dblatex from SlackBuilds.org. See documentation, PDF.

To highlight source listings, install source-highlight from SlackBuilds.org. See online manual. This:

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

renders as (this is DokuWiki's GeSHi highlighting, but gives the general idea):

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

If asciidoc.vim is not available locally, download. Otherwise:

$ mkdir -p $HOME/.vim/syntax

$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/

and see Appendix E. Vim Syntax Highlighter.

Highlighting can also work by inserting at the bottom of the file:

// vim: set syntax=asciidoc:

The user guide file is found in /usr/doc/asciidoc-VERSION/doc/asciidoc.txt. To make the AsciiDoc User Guide:

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

and see /usr/doc/asciidoc-VERSION/doc/asciidoc.html. For more see asciidoc.org.

It is a convention for asciidoc files to have a .txt extension.

To organize the use of common variables in all files, make a directory include. Common paths, for example, can be put in a paths.txt as a series of:

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

Then, at the header of each file put:

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

and in text use as:

{pathname}/remaining/path

Any variable that can be defined in bash with NAME=“$(commands)” can also be defined in asciidoc as a system attribute. First define the attribute in the header section:

:NAME: {sys:commands}

then use in text as:

{NAME}

Linking to man pages in HTML is very useful. See man2html Mini HOWTO on how to set the infrastructure. To see grep(1) use

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

To make an HTML file:

$ asciidoc -b xhtml11 FILENAME

To use icons, mainly for admonition paragraphs, add the options:

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

To have a fixed-width HTML, add:

-a max-width=45em

To use additional custom CSS, add:

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

It may be helpful to put an alias in .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"

To make a PDF file, first install dblatex. Then:

$ asciidoc -b docbook45 FILENAME

$ dblatex FILENAME.xml

The asciidoc files can be converted to DokuWiki format for the Slackware Documentation Project. There are various ways to do this, and one of the more straightforward ones is to convert the HTML files produced by asciidoc using the perl module HTML::WikiConverter::DokuWiki, see also HTML::WikiConverter.

# cpan

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

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

• Original source: asciidoc mini howto
• Originally written by pdi
• Contributions by markand