This is an old revision of the document!
Table of Contents
asciidoc Mini HOWTO
For an interesting read about asciidoc see Living the Future of Technical Writing.
Helper Packages and Files
Asciidoctor
Consider installing Asciidoctor.
Dblatex
To convert asciidoc files to PDF, install dblatex from SlackBuilds.org. See documentation, PDF.
Source-highlight
To highlight source listings, install source-highlight from SlackBuilds.org. See online manual. This:
[source,bash] --------------------------------------------------------------------------- #!/bin/bash export LANG=en_US.UTF-8 ---------------------------------------------------------------------------
renders as (…)
#!/bin/bash export LANG=en_US.UTF-8
Vim Syntax Highlighter
If asciidoc.vim is not available locally, download. Otherwise:
$ -d $HOME/.vim/syntax || mkdir -p $HOME/.vim/syntax
$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/
and see 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 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 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 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"
To make a PDF file, first install dblatex. Then:
$ asciidoc -b docbook45 FILENAME
$ dblatex FILENAME.xml
Txt2tags
Use txt2tags to convert asciidoc files to dokuwiki format for the Slackware Documentation Project:
$ txt2tags -i FILENAME.txt -o FILENAME.dw -t doku
Sources