Linux Certif

Toute la documentation sur la certification Linux LPI

a2x

NAME

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

SYNOPSIS

a2x [OPTIONS] FILE

DESCRIPTION

A DocBook toolchain manager that translates an AsciiDoc text file 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). 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.

--conf-file=CONF_FILE

Load configuration file. See CONF FILES section.

-D, --destination-dir=PATH

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

-f, --format=FORMAT

Output formats: chunked, docbook, dvi, epub, htmlhelp, manpage, pdf (default), ps, tex, text, xhtml.

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

--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-dir=PATH

If a relative image or CSS resource is not found relative to the source FILE then search the PATH recursively. This option may be specified more than once.

--stylesheet=PATH

A path (relative to destination HTML files) specifying the docbook-xsl CSS stylesheet file. Defaults to docbook-xsl.css. 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.

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

--dblatex-opts=DBLATEX_OPTS

Additional dblatex(1) options.

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 copy images and CSS stylesheet files referenced in the generated HTML outputs from locations relative to the asciidoc input FILE to the correct relative destination directory locations generating required sub-directories if necessary. See also the --resource-dir option.

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 searches ../images for any missing resources.

a2x -f manpage doc/asciidoc.1.txt

Generate doc/asciidoc.1 manpage.

REQUISITES

a2x uses the following programs:

•
Asciidoc: m[blue]http://www.methods.co.nz/asciidoc/m[]

•
xsltproc: (all formats except text): m[blue]http://xmlsoft.org/XSLT/m[]

•
DocBook XSL Stylesheets (all formats except text): m[blue]http://docbook.sourceforge.net/projects/xsl/m[]

•
dblatex (pdf, dvi, ps, tex formats): m[blue]http://dblatex.sourceforge.net/m[]

•
FOP (pdf format --- alternative PDF file generator): m[blue]http://xmlgraphics.apache.org/fop/m[]

•
w3m (text format): m[blue]http://w3m.sourceforge.net/index.en.htmlm[]

•
Lynx (text format --- alternative text file generator): m[blue]http://lynx.isc.org/m[]

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 AsciiDoc global configuration directory.

2.
a2x.conf from the AsciiDoc $HOME/.asciidoc configuration directory.

3.
a2x.conf from the directory containing a2x.py.

4. The CONF_FILE specified in the --conf-file option.

BUGS

See the AsciiDoc distribution BUGS file.

AUTHOR

Written by Stuart Rackham, <m[blue]srackham@gmail.comm[][1]>

RESOURCES

SourceForge: m[blue]http://sourceforge.net/projects/asciidoc/m[]

Main web site: m[blue]http://www.methods.co.nz/asciidoc/m[]

COPYING

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

NOTES

1.

srackham@gmail.com

mailto:srackham@gmail.com