¡Esta es una revisión vieja del documento!
Tabla de Contenidos
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
System Attributes
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}
Man
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)]
Output
XHTML
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
DokuWiki
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
Sources
- Original source: asciidoc mini howto
- Originally written by pdi
- Contributions by markand