--- name: "a2x" section: "1" platform: "linux" package: "asciidoc" version: "10.2.1-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/a2x" --- # a2x(1) A toolchain manager for AsciiDoc (converts Asciidoc text files to other file formats) ## 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)](/asciidoc/1.md)* 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)](/asciidoc/1.md) attribute value (shortcut for **--asciidoc-opts**=*"-a ATTRIBUTE"* option). This option may be specified more than once. - **--asciidoc-opts**=*ASCIIDOC\_OPTS* Additional *[asciidoc(1)](/asciidoc/1.md)* 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)](/lynx/1.md)* (actually: the text-based browser defined by the LYNX config variable) when generating text formatted output. The default behavior is to use *[w3m(1)](/w3m/1.md)* (actually: the text-based browser defined by the W3M config variable). - **-L, --no-xmllint** Do not check asciidoc output with *[xmllint(1)](/xmllint/1.md)*. **---epubcheck** Check EPUB output with *[epubcheck(1)](/epubcheck/1.md)*. - **-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)](/xsltproc/1.md)* 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)](/dblatex/1.md)*. The *--fop* option is implicit if the *--fop-opts* option is used. - **--fop-opts**=*FOP\_OPTS* Additional *[fop(1)](/fop/1.md)* 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)](/dblatex/1.md)* 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)](/asciidoc/1.md)* 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: ``` [=] .= ``` 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 **OUTPUT FILES** 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. ## 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. ## 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. ## RESOURCES GitHub: https://github.com/asciidoc/asciidoc-py3/ Main web site: https://asciidoc.org/ ## SEE ALSO [asciidoc(1)](/asciidoc/1.md) ## 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.