[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

no way to compare when less than two revisions

Diferencias

Muestra las diferencias entre dos versiones de la página.


Revisión previa
Próxima revisión
—es:howtos:software:asciidoc [2019/08/26 14:24 (UTC)] – [Introduction] slackwarespanol
Línea 1: Línea 1:
 +====== 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 [[es: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 ====
 +Consider installing [[http://asciidoctor.org/|Asciidoctor]].
 +
 +==== Dblatex ====
 +To convert //asciidoc// files to PDF, install
 +[[http://slackbuilds.org/graphics/dblatex/|dblatex]] from SlackBuilds.org. See
 +[[http://dblatex.sourceforge.net/|documentation]], [[#PDF]].
 +
 +==== Source-highlight ====
 +To highlight source listings, install
 +[[http://slackbuilds.org/system/source-highlight/|source-highlight]] from SlackBuilds.org. See [[https://www.gnu.org/software/src-highlite/source-highlight.html|online manual]].
 +This:
 +<code>
 +[source,bash]
 +---------------------------------------------------------------------------
 +#!/bin/bash
 +export LANG=en_US.UTF-8
 +---------------------------------------------------------------------------
 +</code>
 +
 +renders as (this is DokuWiki's GeSHi highlighting, but gives the general idea):
 +<code bash>
 +#!/bin/bash
 +export LANG=en_US.UTF-8
 +</code> 
 +
 +
 +==== Vim Syntax Highlighter ====
 +If //asciidoc.vim// is not available locally, [[https://asciidoc.googlecode.com/hg/vim/syntax/asciidoc.vim|download]]. Otherwise:
 +
 +**''$ mkdir -p $HOME/.vim/syntax''**
 +
 +**''$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/''**
 +
 +and see [[http://www.methods.co.nz/asciidoc/chunked/ape.html|Appendix E. Vim Syntax Highlighter]].
 +
 +Highlighting can also work by inserting at the bottom of the file:
 +
 +<code>// vim: set syntax=asciidoc:</code>
 +
 +
 +
 +===== User Guide =====
 +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 [[http://asciidoc.org/|asciidoc.org]].
 +
 +===== Source Files =====
 +==== TXT ====
 +It is a //convention// for //asciidoc// files to have a //.txt// extension.
 +
 +==== Common Variables ====
 +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:
 +
 +<file>
 +:pathname: {pathname=/path/to/somewhere}
 +</file>
 +
 +Then, at the header of each file put:
 +
 +<file>
 +include::/path/to/include/paths.txt[]
 +</file>
 +
 +and in text use as:
 +
 +<file>
 +{pathname}/remaining/path
 +</file>
 +
 +==== System Attributes ====
 +Any variable that can be defined in //bash// with 
 +**''NAME="$(commands)"''**
 +can also be defined in //asciidoc// as a [[http://asciidoc.org/userguide.html#X24|system attribute]]. First define the attribute in the header section:
 +<file>
 +:NAME: {sys:commands}
 +</file>
 +then use in text as:
 +<file>
 +{NAME}
 +</file>
 +
 +==== Man ====
 +Linking to //man// pages in HTML is very useful. See [[howtos:software:man2html_mini_howto|man2html Mini HOWTO]] on how to set the infrastructure. To see grep(1) use
 +<file>
 +http://localhost/cgi-bin/man/man2html?1+grep[grep(1)]
 +</file>
 +
 +===== 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//:
 +<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 ====
 +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 [[http://search.cpan.org/~diberri/HTML-WikiConverter-DokuWiki-0.53/lib/HTML/WikiConverter/DokuWiki.pm|HTML::WikiConverter::DokuWiki]], see also [[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''**
 +
 +
 +====== Sources ======
 +
 +  * Original source: [[http://www.linuxquestions.org/questions/slackware-14/asciidoc-mini-howto-4175528145/|asciidoc mini howto]]
 +  * Originally written by [[wiki:user:pdi | pdi]]
 +  * Contributions by [[wiki:user:markand | markand]]
 +
 +{{tag>howtos asciidoc}}

Traza:

es:howtos:software:asciidoc ()