diff options
Diffstat (limited to 'doc/asciidoc/doc/a2x.1.txt')
| -rw-r--r-- | doc/asciidoc/doc/a2x.1.txt | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/doc/asciidoc/doc/a2x.1.txt b/doc/asciidoc/doc/a2x.1.txt new file mode 100644 index 0000000..56cc956 --- /dev/null +++ b/doc/asciidoc/doc/a2x.1.txt @@ -0,0 +1,358 @@ +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. + |