====== 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}}