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