Welcome to the Slackware Documentation Project

Diferencias

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

Enlace a la vista de comparación

es:howtos:software:asciidoc [2019/02/28 01:42 (UTC)] (actual)
slackwarespanol creado
Línea 1: Línea 1:
 +====== Asciidoc ======
  
 +===== Introduction =====
 +
 +Keeping notes is an integral part of using any Linux distribution. Keeping them in plain text allows one to use them from a console during initial setup; using a consistent markup for plain text adds to the readability of the notes. ​
 +
 +//​asciidoc//​ is one of the tools that provide such a consistent markup. Source highlighting,​ for those who prefer it, can add to the readability of the text file.
 +
 +//​asciidoc//​ can produce HTML files, an added bonus as it allows to interlink notes and makes browsing them with //lynx// more effective. It can also work in tandem with [[howtos:​software:​man2html_mini_howto|man2html]] to provide HTML access to all installed //man// pages on the fly.
 +
 +For an interesting read about //​asciidoc//​ see [[https://​medium.com/​@chacon/​living-the-future-of-technical-writing-2f368bd0a272|Living the Future of Technical Writing]].
 +
 +===== 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}}

En otros idiomas
QR Code
QR Code es:howtos:software:asciidoc (generated for current page)