SYNOPSIS
DESCRIPTION
A DocBook toolchain manager that translates an AsciiDoc text file
FILE to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or chunked),
man page, HTML Help or plain text formats using asciidoc(1) and
other applications (see REQUISITES section). FILE can also be
a DocBook file with an .xml extension.
OPTIONS
-
-a, --attribute=ATTRIBUTE
-
Set asciidoc(1) attribute value (shortcut for --asciidoc-opts="-a
ATTRIBUTE" option). This option may be specified more than once.
-
--asciidoc-opts=ASCIIDOC_OPTS
-
Additional asciidoc(1) options.
-
--conf-file=CONF_FILE
-
Load configuration file. See CONF FILES section.
-
-D, --destination-dir=PATH
-
Output directory. Defaults to source FILE directory.
-
-d, --doctype=DOCTYPE
-
DocBook document type: article, manpage or book. Default
document type is article unless the format is manpage (in which
case it defaults to manpage).
-
-f, --format=FORMAT
-
Output formats: chunked, docbook, dvi, epub, htmlhelp,
manpage, pdf (default), ps, tex, text, xhtml.
-
-h, --help
-
Print command-line syntax and program options to stdout.
-
--icons
-
Use admonition or navigation icon images in output documents. The
default behavior is to use text in place of icons.
-
--icons-dir=PATH
-
A path (relative to output files) containing admonition
and navigation icons. Defaults to images/icons.
The --icons option is implicit if this option is used.
-
--lynx
-
Use lynx(1) to generate text formatted output. The default
behavior is to use w3m(1).
-
-L, --no-xmllint
-
Do not check asciidoc output with xmllint(1).
-
---epubcheck
-
Check EPUB output with epubcheck(1).
-
-n, --dry-run
-
Do not do anything just print what would have been done.
-
-r, --resource-dir=PATH
-
If a relative image or CSS resource is not found relative to the
source FILE then search the PATH recursively. This option may be
specified more than once.
-
--stylesheet=PATH
-
A path (relative to destination HTML files) specifying the
docbook-xsl CSS stylesheet file. Defaults to docbook-xsl.css.
Applies to HTML formats: xhtml, epub, chunked, htmlhelp
formats.
-
-v, --verbose
-
Print operational details to stderr.
A second -v option applies the verbose option to toolchain commands.
-
--version
-
Print program version to stdout.
-
--xsltproc-opts=XSLTPROC_OPTS
-
Additional xsltproc(1) options.
-
--fop
-
Use FOP to generate PDFs. The default behavior is to use
dblatex(1). The --fop option is implicit if this option is
used.
-
--fop-opts=FOP_OPTS
-
Additional fop(1) options. If this option is specified FOP is used
to generate PDFs.
-
--dblatex-opts=DBLATEX_OPTS
-
Additional dblatex(1) options.
OUTPUT FILES
Output files are written to the directory specified by the
--destination-dir option. If no --destination-dir option is set
output files are written to the source FILE directory.
Output files have the same name as the source FILE but with an
appropriate file name extension: .html for xhtml; .epub for
epub; .hhp for htmlhelp; .pdf for pdf; .text for text,
.xml for docbook. By convention manpages have no .man extension
(man page section number only). Chunked HTML directory names have a
.chunked extension; chunked HTML Help directory names have a
.htmlhelp extension.
Same named existing files are overwritten.
In addition to generating HTML files the xhtml, epub, chunked
and htmlhelp formats copy images and CSS stylesheet files referenced
in the generated HTML outputs from locations relative to the asciidoc
input FILE to the correct relative destination directory locations
generating required sub-directories if necessary. See also the
--resource-dir option.
EXAMPLES
-
a2x -f pdf doc/source-highlight-filter.txt
-
Generates doc/source-highlight-filter.pdf file.
-
a2x -f xhtml -D ../doc --icons -r ../images team.txt
-
Creates HTML file ../doc/team.html, uses admonition icons
and searches ../images for any missing resources.
-
a2x -f manpage doc/asciidoc.1.txt
-
Generate doc/asciidoc.1 manpage.
REQUISITES
a2x uses the following programs:
See also the latest README file.
CONF FILES
A configuration file contains executable Python code that overrides
the global configuration parameters in a2x.py. Optional configuration
files are loaded in the following order:
-
a2x.conf from the AsciiDoc global configuration directory.
-
a2x.conf from the AsciiDoc $HOME/.asciidoc configuration
directory.
-
a2x.conf from the directory containing a2x.py.
-
The CONF_FILE specified in the --conf-file option.
BUGS
See the AsciiDoc distribution BUGS file.
AUTHOR
RESOURCES
COPYING
Copyright (C) 2002-2009 Stuart Rackham. Free use of this software is
granted under the terms of the MIT license.
|