table of contents
other sections
A2X(1) | A2X(1) |
NAME¶
a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to other file formats)SYNOPSIS¶
a2x [OPTIONS] SOURCE_FILEDESCRIPTION¶
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=ATTRIBUTESet 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.
-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
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
-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=RESOURCE_SPEC
Specify a resource. This option may be
specified more than once. See the RESOURCES section for more
details.
-m, --resource-manifest=FILE
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 this
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.
// 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.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. 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.
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.
<resource_dir> <resource_file>[=<destination_file>] .<ext>=<mimetype>
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
.<ext>=<mimetype>
The chunked output directory.
epub
The archived OEBPS directory.
xhtml
The output DESTINATION_DIR.
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 ../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.txtGenerates 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:•
Asciidoc: http://www.methods.co.nz/asciidoc/
•
xsltproc: (all formats except text): http://xmlsoft.org/XSLT/
•
DocBook XSL Stylesheets (all formats except text):
http://docbook.sourceforge.net/projects/xsl/
•
dblatex (pdf, dvi, ps, tex formats):
http://dblatex.sourceforge.net/
•
FOP (pdf format — alternative PDF file generator):
http://xmlgraphics.apache.org/fop/
•
w3m (text format): http://w3m.sourceforge.net/index.en.html
•
Lynx (text format — alternative text file generator):
http://lynx.isc.org/
•
epubcheck (epub format — EPUB file validator):
http://code.google.com/p/epubcheck/
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.
# 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' # text generation. LYNX = 'lynx' # text generation (if no w3m). XMLLINT = 'xmllint' # Set to '' to disable. EPUBCHECK = 'epubcheck' # Set to '' to disable. # External executable default options. ASCIIDOC_OPTS = '' DBLATEX_OPTS = '' FOP_OPTS = '' XSLTPROC_OPTS = ''
BUGS¶
See the AsciiDoc distribution BUGS file.AUTHOR¶
a2x was originally written by Stuart Rackham. Many people have contributed to it.RESOURCES¶
SourceForge: http://sourceforge.net/projects/asciidoc/COPYING¶
Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is granted under the terms of the MIT license.17 March 2012 | 8.6.7 |