Unix/Linux Go Back    


CentOS 7.0 - man page for a2x (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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.

       -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 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://www.methods.co.nz/asciidoc/

       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    w3m (text format): http://w3m.sourceforge.net/index.en.html

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

  8.6.8 				   17 July 2012 				   A2X(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:03 PM.