NAME¶
a2x - A toolchain manager for AsciiDoc (converts Asciidoc text
files to other file formats)
SYNOPSIS¶
a2x [OPTIONS] SOURCE_FILE
DESCRIPTION¶
A DocBook toolchain manager that translates an AsciiDoc text file
SOURCE_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). SOURCE_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. This option may be
specified more than once.
--conf-file=CONF_FILE
Load configuration file. See CONF FILES section.
-D, --destination-dir=DESTINATION_DIR
Output directory. Defaults to SOURCE_FILE
directory. This option is only applicable to HTML and manpage based output
formats (chunked, epub, htmlhelp, xhtml,
manpage).
-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).
-b, --backend=BACKEND
BACKEND is the name of an installed backend
plugin. When this option is specified a2x attempts to load a file name
a2x-backend.py from the BACKEND plugin directory. It then
converts the SOURCE_FILE to a BACKEND formatted output file
using a global function defined in a2x-backend.py called
to_BACKEND.
-f, --format=FORMAT
Output formats: chunked, docbook,
dvi, epub, htmlhelp, manpage, pdf
(default), ps, tex, text, xhtml. The AsciiDoc
a2x-format attribute value is set to FORMAT.
-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.
-k, --keep-artifacts
Do not delete temporary build files.
--lynx
Use
lynx(1) (actually: the text-based browser
defined by the LYNX config variable) when generating text formatted output.
The default behavior is to use
w3m(1) (actually: the text-based browser
defined by the W3M config variable).
-L, --no-xmllint
---epubcheck
Check EPUB output with epubcheck(1).
-n, --dry-run
Do not do anything just print what would have been
done.
-r, --resource=RESOURCE_SPEC
Specify a resource. This option may be specified more
than once. See the RESOURCES section for more details.
-m, --resource-manifest=FILE
FILE contains a list resources (one per line).
Manifest FILE entries are formatted just like --resource option
arguments. Environment variables and tilde home directories are allowed.
--stylesheet=STYLESHEET
A space delimited list of one or more CSS stylesheet file
names that are used to style HTML output generated by DocBook XSL Stylesheets.
Defaults to docbook-xsl.css. The stylesheets are processed in list
order. The stylesheets must reside in a valid resource file location. 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. This option may be
specified more than once.
--xsl-file=XSL_FILE
Override the built-in XSL stylesheet with the custom XSL
stylesheet XSL_FILE.
--fop
Use FOP to generate PDFs. The default behavior is to use
dblatex(1). The
--fop option is implicit if the
--fop-opts option is used.
--fop-opts=FOP_OPTS
Additional fop(1) options. If this option is
specified FOP is used to generate PDFs. This option may be specified more than
once.
--dblatex-opts=DBLATEX_OPTS
Additional
dblatex(1) options. This option may be
specified more than once.
--backend-opts=BACKEND_OPTS
Options for the backend plugin specified by the
--backend option. This option may be specified more than once.
Options can also be set in the AsciiDoc source file. If
SOURCE_FILE contains a comment line beginning with // a2x:
then the remainder of the line will be treated as a2x command-line
options. For example:
// a2x default options.
// a2x: -dbook --epubcheck
// Suppress revision history in dblatex outputs.
// a2x: --dblatex-opts "-P latex.output.revhistory=0"
•Options spanning multiple such comment lines will
be concatenated.
•Zero or more white space characters can appear
between the leading // and a2x:.
•Command-line options take precedence over options
set in the source file.
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 ensure resource
files are copied to their correct destination directory locations.
RESOURCES¶
Resources are files (typically CSS and images) that are required
by HTML based outputs (xhtml, epub, chunked,
htmlhelp formats). a2x scans the generated HTML files and
builds a list of required CSS and image files. Additional resource files can
be specified explicitly using the --resource option.
a2x searches for resource files in the following locations
in the following order:
1.The SOURCE_FILE directory.
2.Resource directories specified by the
--resource option (searched recursively).
3.Resource directories specified by the
--resource-manifest option (searched recursively in the order they
appear in the manifest file).
4.The stock images and stylesheets directories in the
asciidoc(1) configuration files directories (searched
recursively).
5.The destination directory.
When a resource file is found it is copied to the correct relative
destination directory. Missing destination sub-directories are created
automatically.
There are two distinct mechanisms for specifying additional
resources:
1.A resource directory which will be searched
recursively for missing resource files.
2.A resource file which will be copied to the output
destination directory.
Resources are specified with --resource option values which
can be one of the following formats:
<resource_dir>
<resource_file>[=<destination_file>]
.<ext>=<mimetype>
Where:
<resource_dir>
Specifies a directory (absolute or relative to the
SOURCE_FILE) which is searched recursively for missing resource files.
To eliminate ambiguity the <resource_dir> name should end with a
directory separator character.
<resource_file>
Specifies a resource file (absolute or relative to the
SOURCE_FILE) which will be copied to <destination_file>. If
<destination_file> is not specified then it is the same as the
<resource_file>.
<destination_file>
Specifies the destination of the copied source file. The
<destination_file> path is relative to the destination directory
(absolute paths are not allowed). The location of the destination directory
depends on the output
FORMAT (see the
OUTPUT FILES section for
details):
chunked, htmlhelp
The chunked output directory.
epub
The archived OEBPS directory.
xhtml
The output DESTINATION_DIR.
.<ext>=<mimetype>
When adding resources to EPUB files the mimetype is
inferred from the <destination file> extension, if the mimetype cannot
be guessed an error occurs. The .<ext>=<mimetype> resource syntax
can be used to explicitly set mimetypes. <ext> is the file name
extension, <mimetype> is the corresponding MIME type.
Resource option examples:
--resource ../images/
--resource doc/README.txt=README.txt
--resource ~/images/tiger.png=images/tiger.png
--resource .ttf=application/x-font-ttf
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 recursively searches the ../images/ directory 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:
1.a2x.conf from the directory containing the
a2x.py executable.
2.a2x.conf from the AsciiDoc global configuration
directory. Skip this step if we are executing a locally installed (non system
wide) copy.
3.a2x.conf from the AsciiDoc $HOME/.asciidoc
configuration directory.
4.The CONF_FILE specified in the
--conf-file option.
Here are the default configuration file option values:
# Optional environment variable dictionary passed to
# executing programs. If set to None the existing
# environment is used.
ENV = None
# External executables.
ASCIIDOC = 'asciidoc'
XSLTPROC = 'xsltproc'
DBLATEX = 'dblatex' # pdf generation.
FOP = 'fop' # pdf generation (--fop option).
W3M = 'w3m' # primary text file generator.
LYNX = 'lynx' # alternate text file generator.
XMLLINT = 'xmllint' # Set to '' to disable.
EPUBCHECK = 'epubcheck' # Set to '' to disable.
# External executable default options.
ASCIIDOC_OPTS = ''
BACKEND_OPTS = ''
DBLATEX_OPTS = ''
FOP_OPTS = ''
LYNX_OPTS = '-dump'
W3M_OPTS = '-dump -cols 70 -T text/html -no-graph'
XSLTPROC_OPTS = ''
Note, that it is possible to redefine W3M and LYNX to use
different text-based browsers, e.g. links:
http://links.twibright.com/ or elinks: http://elinks.or.cz/.
LYNX_OPTS and W3M_OPTS can be used to pass options to the selected browser.
If these are defined they override the respective defaults listed above (so
don’t forget to include the -dump option in your definition:
this is mandatory at least with w3m, lynx, links, and
elinks in order to send the formatted text to stdout).
BUGS¶
See the AsciiDoc distribution BUGS file.
AUTHOR¶
a2x was originally written by Stuart Rackham. Many people have
contributed to it.
COPYING¶
Copyright (C) 2002-2011 Stuart Rackham. Free use of this software
is granted under the terms of the MIT license.