 |  |
| | |
AsciiDoc generates article, book and refentry DocBook documents (corresponding to the AsciiDoc article, book and manpage document types).
Most Linux distributions come with conversion tools (collectively called a toolchain) for converting DocBook files to presentation formats such as Postscript, HTML, PDF, EPUB, DVI, PostScript, LaTeX, roff (the native man page format), HTMLHelp, JavaHelp and text. There are also programs that allow you to view DocBook files directly, for example Yelp (the GNOME help viewer).
DocBook files are validated, parsed and translated various presentation file formats using a combination of applications collectively called a DocBook tool chain. The function of a tool chain is to read the DocBook markup (produced by AsciiDoc) and transform it to a presentation format (for example HTML, PDF, HTML Help, EPUB, DVI, PostScript, LaTeX).
A wide range of user output format requirements coupled with a choice of available tools and stylesheets results in many valid tool chain combinations.
One of the biggest hurdles for new users is installing, configuring
and using a DocBook XML toolchain. a2x(1) can help — it’s a
toolchain wrapper command that will generate XHTML (chunked and
unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
file outputs from an AsciiDoc text file. a2x(1) does all the grunt
work associated with generating and sequencing the toolchain commands
and managing intermediate and output files. a2x(1) also optionally
deploys admonition and navigation icons and a CSS stylesheet. See the
a2x(1) man page for more details. In addition to asciidoc(1) you
also need xsltproc(1), DocBook XSL Stylesheets and
optionally: dblatex or FOP (to generate PDF);
w3m(1) or lynx(1) (to generate text).
The following examples generate doc/source-highlight-filter.pdf from
the AsciiDoc doc/source-highlight-filter.txt source file. The first
example uses dblatex(1) (the default PDF generator) the second
example forces FOP to be used:
$ a2x -f pdf doc/source-highlight-filter.txt $ a2x -f pdf --fop doc/source-highlight-filter.txt
See the a2x(1) man page for details.
![[Tip]](images/icons/tip.png){kind=icon} | |
Use the |
AsciiDoc produces nicely styled HTML directly without requiring a DocBook toolchain but there are also advantages in going the DocBook route:
On the other hand, HTML output directly from AsciiDoc is much faster, is easily customized and can be used in situations where there is no suitable DocBook toolchain (for example, see the AsciiDoc website).
There are two commonly used tools to generate PDFs from DocBook, dblatex and FOP.
dblatex or FOP?
.hhp and .html) files to HTML Help
(.chm) files using the Microsoft HTML Help Compiler.
.txt) files to DocBook XML (.xml) files.
latex(1).
.fo)
files to PDF files. The XSL-FO files are generated from DocBook
source files using DocBook XSL Stylesheets and
xsltproc(1).
hhc.exe) is a command-line tool
that converts HTML Help source files to a single HTML Help (.chm)
file. It runs on MS Windows platforms and can be downloaded from
https://www.microsoft.com/.
The AsciiDoc distribution ./dblatex directory contains
asciidoc-dblatex.xsl (customized XSL parameter settings) and
asciidoc-dblatex.sty (customized LaTeX settings). These are examples
of optional dblatex output customization and are used by
a2x(1).
You will have noticed that the distributed HTML and HTML Help
documentation files (for example ./doc/asciidoc.html) are not the
plain outputs produced using the default DocBook XSL Stylesheets
configuration. This is because they have been processed using
customized DocBook XSL Stylesheets along with (in the case of HTML
outputs) the custom ./stylesheets/docbook-xsl.css CSS stylesheet.
You’ll find the customized DocBook XSL drivers along with additional
documentation in the distribution ./docbook-xsl directory. The
examples that follow are executed from the distribution documentation
(./doc) directory. These drivers are also used by a2x(1).
common.xsl
chunked.xsl
Generate chunked XHTML (separate HTML pages for each document
section) in the ./doc/chunked directory. For example:
$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
epub.xsl
a2x(1) to generate EPUB formatted documents.
fo.xsl
Generate XSL Formatting Object (.fo) files for subsequent PDF
file generation using FOP. For example:
$ python ../asciidoc.py -b docbook article.txt $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo $ fop article.fo article.pdf
htmlhelp.xsl
Generate Microsoft HTML Help source files for the MS HTML Help
Compiler in the ./doc/htmlhelp directory. This example is run on
MS Windows from a Cygwin shell prompt:
$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
manpage.xsl
Generate a roff(1) format UNIX man page from a DocBook XML
refentry document. This example generates an asciidoc.1 man
page file:
$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
xhtml.xsl
Convert a DocBook XML file to a single XHTML file. For example:
$ python ../asciidoc.py -b docbook asciidoc.txt $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
If you want to see how the complete documentation set is processed
take a look at the A-A-P script ./doc/main.aap.
| | | |
 |