Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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. 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://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    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://asciidoc.org/

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

  8.6.9				9 November 2013				A2X(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT FILES | RESOURCES | EXAMPLES | REQUISITES | CONF FILES | BUGS | AUTHOR | RESOURCES | COPYING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=a2x&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help