====== 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:
[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, [[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:
// 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 [[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:
: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 [[http://asciidoc.org/userguide.html#X24|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 [[howtos: software: man2html_mini_howto | 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 // [[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}}