A2X(1) ====== :doctype: manpage 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 <>). '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 <>. *-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*:: 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 <> 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 <> 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. [[X4]] 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 <> are copied to their correct destination directory locations. [[X3]] 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: . The 'SOURCE_FILE' directory. . Resource directories specified by the *--resource* option (searched recursively). . Resource directories specified by the *--resource-manifest* option (searched recursively in the order they appear in the manifest file). . The stock `images` and `stylesheets` directories in the 'asciidoc(1)' configuration files directories (searched recursively). . 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: . A resource directory which will be searched recursively for missing resource files. . 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: [=] .= Where: ``:: Specifies a directory (absolute or relative to the 'SOURCE_FILE') which is searched recursively for missing resource files. To eliminate ambiguity the `` name should end with a directory separator character. ``:: Specifies a resource file (absolute or relative to the 'SOURCE_FILE') which will be copied to ``. If `` is not specified then it is the same as the ``. ``:: Specifies the destination of the copied source file. The `` 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 <> section for details): chunked, htmlhelp;; 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 `` extension, if the mimetype cannot be guessed an error occurs. The `.=` resource syntax can be used to explicitly set mimetypes. `` is the file name extension, `` 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. [[X1]] REQUISITES ---------- 'a2x' uses the following programs: - *Asciidoc*: https://asciidoc.org/ - *xsltproc*: (all formats except text): http://xmlsoft.org/XSLT/ - *DocBook XSL Stylesheets* (all formats except text): https://github.com/docbook/xslt10-stylesheets - *dblatex* (pdf, dvi, ps, tex formats): http://dblatex.sourceforge.net/ - *FOP* (pdf format -- alternative PDF file generator): https://xmlgraphics.apache.org/fop/ - *w3m* (text format): http://w3m.sourceforge.net/index.en.html - *Lynx* (text format -- alternative text file generator): https://invisible-island.net/lynx/ - *epubcheck* (epub format -- EPUB file validator): https://github.com/w3c/epubcheck See also the latest README file. [[X2]] 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 directory containing the 'a2x.py' executable. . `a2x.conf` from the AsciiDoc global configuration directory. Skip this step if we are executing a locally installed (non system wide) copy. . `a2x.conf` from the AsciiDoc `$HOME/.asciidoc` configuration directory. . 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. RESOURCES --------- GitHub: https://github.com/asciidoc/asciidoc-py3/ Main web site: https://asciidoc.org/ SEE ALSO -------- asciidoc(1) COPYING ------- Copyright \(C) 2002-2013 Stuart Rackham. Copyright \(C) 2013-2022 AsciiDoc Contributors. Free use of this software is granted under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.