Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

a2x (1)

Name

a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to other file formats)

Synopsis

a2x [OPTIONS] SOURCE_FILE

Description

A2X(1)                                                                  A2X(1)



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 based output formats (chunked, epub,
           htmlhelp, xhtml).

       -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 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) to generate text formatted output. Note that this is
           the default behavior on Solaris.

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

       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"

       o   Options spanning multiple such comment lines will be concatenated.

       o   Zero or more white space characters can appear between the leading
           // and a2x:.

       o   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:

       o    Asciidoc: http://asciidoc.org/

       o    xsltproc: (all formats except text): http://xmlsoft.org/XSLT/

       o    DocBook XSL Stylesheets (all formats except text):
           http://docbook.sourceforge.net/projects/xsl/

       o    dblatex (pdf, dvi, ps, tex formats):
           http://dblatex.sourceforge.net/

       o    FOP (pdf format -- alternative PDF file generator):
           http://xmlgraphics.apache.org/fop/

       o    Lynx (text format -- alternative text file generator):
           http://lynx.isc.org/

       o    epubcheck (epub format -- EPUB file validator):
           http://code.google.com/p/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).
           LYNX = 'lynx'               # text generation (--lynx option).
           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/

       Main web site: http://asciidoc.org/

COPYING
       Copyright (C) 2002-2011 Stuart Rackham. Free use of this software is
       granted under the terms of the MIT license.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+---------------------------------------+
       |ATTRIBUTE TYPE |           ATTRIBUTE VALUE             |
       +---------------+---------------------------------------+
       |Availability   | developer/documentation-tool/asciidoc |
       +---------------+---------------------------------------+
       |Stability      | Uncommitted                           |
       +---------------+---------------------------------------+
NOTES
       This software was built from source available at
       https://github.com/oracle/solaris-userland.  The original community
       source was downloaded from
       http://downloads.sourceforge.net/project/asciidoc/asciidoc/8.6.9/asciidoc-8.6.9.tar.gz

       Further information about this software can be found on the open source
       community website at http://www.methods.co.nz/asciidoc/.



  8.6.9                         9 November 2013                         A2X(1)