A2X(1)

📦
version 10.2.1 · 12 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, opensuse-leap 16.0

🌸 NAME 🌸

a2x — A toolchain manager for AsciiDoc (converts Asciidoc text files to other file formats). And yes bestie, this is the a2x(1) manual, so buckle up. 💅

✨ SYNOPSIS ✨

a2x [OPTIONS] SOURCE_FILE

💖 DESCRIPTION 💖

okay so a2x is 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 the REQUISITES section). Also SOURCE_FILE can be a DocBook file with an .xml extension. No cap, it's giving build-system main character energy. 🔥

🎀 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 the 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 — 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 — 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 in your source file 🫶

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 🌈

okay so 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. periodt. 💅

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. they get overwritten, bestie — that's the whole sentence. 😭

In addition to generating HTML files the xhtml, epub, chunked and htmlhelp formats ensure resource files are copied to their correct destination directory locations. That's the little behind-the-scenes slay. ✨

🦋 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. iykyk. 💜

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. no cap, it makes the folders for you. 🫶

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. pdf bestie, classic. ✨
  • 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. the way this one multitasks. 💅
  • a2x -f manpage doc/asciidoc.1.txt — Generate doc/asciidoc.1 manpage. manpage era. 🎀

🌟 REQUISITES 🌟

a2x uses the following programs:

See also the latest README file. 🫶

💅 CONF FILES 💅

okay so bestie, a configuration file is literally executable Python code that overrides the global configuration parameters in a2x.py. Optional configuration files get loaded in this exact order, no cap:

  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, and yes bestie you can copy-paste these bad boys exactly:

# 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/. <code>LYNX_OPTS</code> and <code>W3M_OPTS</code> 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 <code>-dump</code> option in your definition: this is mandatory at least with <code>w3m</code>, <code>lynx</code>, <code>links</code>, and <code>elinks</code> in order to send the formatted text to <code>stdout</code>.

🚨 fr fr, do not skip the -dump thing — the formatted text needs to go to stdout, and that’s the vibe. ✨

👑 BUGS 👑

See the AsciiDoc distribution BUGS file. short and iconic. 🫶

🎀 AUTHOR 🎀

a2x was originally written by Stuart Rackham. Many people have contributed to it. slay, collaborative queen behavior 💖

🌈 RESOURCES 🌈

yes bestie, resources said “run it back” — we don’t make the rules 💅

🦋 SEE ALSO 🦋

asciidoc(1) — go read it, iykyk. 🦋

💖 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.

💖 okay bye bestie — this page is <code>A2X(1)</code>, dated <code>07/17/2024</code>. go off and make something iconic. 💖

📦 where this page comes from