====== 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:
[source,bash]
---------------------------------------------------------------------------
#!/bin/bash
export LANG=en_US.UTF-8
---------------------------------------------------------------------------
renders as (this is DokuWiki's GeSHi highlighting, but gives the general idea):
#!/bin/bash
export LANG=en_US.UTF-8
==== 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:
// vim: set syntax=asciidoc:
===== 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:
:pathname: {pathname=/path/to/somewhere}
Then, at the header of each file put:
include::/path/to/include/paths.txt[]
and in text use as:
{pathname}/remaining/path
==== 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:
:NAME: {sys:commands}
then use in text as:
{NAME}
==== 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
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"
==== 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}}