path: root/source-builder/sb/asciidoc/examples/website/a2x.1.txt

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 <<X1,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 <<X2,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'::
  '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. The default
  behavior is to use 'w3m(1)'.

*-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 <<X3,*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 <<X3, 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"

- 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 <<X3,resource files>> 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:

  <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 <<X4,*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.


[[X1]]
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/

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'                 # 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/

Main web site: http://www.methods.co.nz/asciidoc/


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