mizuho 0.9.6 → 0.9.8

data/asciidoc/doc/a2x.1.txt

@@ -1,49 +1,44 @@
 A2X(1)
 ======
-Stuart Rackham <srackham@gmail.com>
+:doctype: manpage
 
 
 NAME
 ----
-a2x - convert Asciidoc text file to PDF, XHTML, HTML Help, manpage or
-plain text
+a2x - A toolchain manager for AsciiDoc (converts Asciidoc text files to other
+      file formats)
 
 
 SYNOPSIS
 --------
-*a2x* ['OPTIONS'] 'FILE'
+*a2x* ['OPTIONS'] 'SOURCE_FILE'
 
 
 DESCRIPTION
 -----------
-A DocBook toolchain wrapper script that translates an AsciiDoc text
-file 'FILE' to PDF, DVI, PS, LaTeX, XHTML (single page or chunked),
-man page, HTML Help or plain text formats. PDF, XHTML, man page and
-HTML Help formats are are generated using the asciidoc(1),
-xsltproc(1), DocBook XSL Stylesheets, dblatex (or FOP) toolchain.
-Plain text is produced by passing asciidoc(1) generated HTML through
-lynx(1). The htmlhelp format option generates .hhp, .hhc and .html
-files suitable for compilation to an HTML Help .chm file.
+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.
+  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.
+  Additional 'asciidoc(1)' options.
+  This option may be specified more than once.
 
-*--copy*::
-  Copy distributed docbook-xsl CSS stylesheet admonition and
-  navigation icons to their respective destinations. Applies to
-  'xhtml', 'chunked', 'htmlhelp' formats. The default behavior is to
-  suppress copying.
+*--conf-file*='CONF_FILE'::
+  Load configuration file. See <<X2,CONF FILES section>>.
 
-*-D, --destination-dir*='PATH'::
-  Output directory. Defaults to source 'FILE' directory.
+*-D, --destination-dir*='DESTINATION_DIR'::
+  Output directory. Defaults to 'SOURCE_FILE' directory.
 
 *-d, --doctype*='DOCTYPE'::
   DocBook document type: 'article', 'manpage' or 'book'.  Default
@@ -51,8 +46,8 @@ OPTIONS
   case it defaults to 'manpage').
 
 *-f, --format*='FORMAT'::
-  Output format: 'chunked', 'dvi', 'htmlhelp', 'manpage', 'pdf', 'ps',
-  'tex', 'text' or 'xhtml'.
+  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.
@@ -62,24 +57,42 @@ OPTIONS
   default behavior is to use text in place of icons.
 
 *--icons-dir*='PATH'::
-  A path (relative to destination HTML files) containing admonition
-  and navigation icons. Defaults to './images/icons/'.
-  Applies to 'xhtml', 'chunked', 'htmlhelp' formats.
+  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*::
-  Don't check asciidoc output with 'xmllint(1)'.
+  Do not check asciidoc output with 'xmllint(1)'.
+
+*---epubcheck*::
+  Check EPUB output with 'epubcheck(1)'.
 
 *-n, --dry-run*::
-  Don't do anything just print what would have been done.
+  Do not do anything just print what would have been done.
 
-*-s, --skip-asciidoc*::
-  Skip asciidoc execution. This is useful for converting DocBook XML
-  files not derived from AsciiDoc sources. Ignored if '--format=text'.
+*-r, --resource*='RESOURCE_SPEC'::
+  Specify a resource.  This option may be specified more than once.
+  See the <<X3,*RESOURCES*>> section for more details.
 
-*--stylesheet*='PATH'::
-  A path (relative to destination HTML files) specifying the
-  docbook-xsl CSS stylesheet file. Defaults to './docbook-xsl.css'.
-  Applies to 'xhtml', 'chunked', 'htmlhelp' formats.
+*-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.
@@ -89,105 +102,234 @@ OPTIONS
   Print program version to stdout.
 
 *--xsltproc-opts*='XSLTPROC_OPTS'::
-  Additional xsltproc(1) options.  This option may be specified more
-  than once.
+  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.
+  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 options.  This option may be specified more than
-  once. If this option is specified FOP is used to generate PDFs.
+  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 options.  This option may be specified more than once.
+  Additional 'dblatex(1)' options.
+  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 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'; .hhp for
-'htmlhelp'; .pdf for 'pdf'; .text for 'text'. 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.
+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.
 
-Intermediate output files are written to the source 'FILE' directory
-and are not automatically deleted.
-
-Intermediate DocBook XML files generated by AsciiDoc are only
-regenerated if out of date with respect to the AsciiDoc source 'FILE'.
+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.
 
-In addition to generating HTML files the 'xhtml', 'chunked' and
-'htmlhelp' formats copy the DocBook XSL stylesheet plus admonition and
-navigation icons distributed with AsciiDoc to their respective
-destination locations. Existing stylesheets and icons are only copied
-if they are newer than the destination files or if the destination
-files are missing.
 
-The 'xhtml' format generates a single XHTML output page.  The
-'chunked' format writes multiple per-section HTML pages to a chunked
-directory in the destination directory. The chunked directory has the
-same name as the source 'FILE' name plus a .chunked extension.
+[[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.
+  Generates `doc/source-highlight-filter.pdf` file.
 
-`a2x -f chunked -D ../webpages guide.txt`::
-  Creates chunked directory `../webpages/guide.chunked` containing
-  chunked HTML files. Also copies `docbook-xsl.css` stylesheet to the
-  `../webpages/guide.chunked` directory plus admonition and navigation
-  icons to the `../webpages/guide.chunked/images/icons` directory.
+`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
 ----------
-This script runs under the bash(1) shell and requires the following
-programs (which may or may not be prepackaged with your Linux
-distribution):
+'a2x' uses the following programs:
 
-Asciidoc::
+- *Asciidoc*:
   http://www.methods.co.nz/asciidoc/
-
-xsltproc::
+- *xsltproc*: (all formats except text):
   http://xmlsoft.org/XSLT/
-
-DocBook XSL Stylesheets::
+- *DocBook XSL Stylesheets* (all formats except text):
   http://docbook.sourceforge.net/projects/xsl/
-
-dblatex (for PDF, DVI, PostScript and LaTeX file generation)::
+- *dblatex* (pdf, dvi, ps, tex formats):
   http://dblatex.sourceforge.net/
-
-FOP (alternative PDF file generation)::
+- *FOP* (pdf format -- alternative PDF file generator):
   http://xmlgraphics.apache.org/fop/
-
-w3m (text file generation)::
+- *w3m* (text format):
   http://w3m.sourceforge.net/index.en.html
-
-Lynx (used for text file generation if `w3m(1)` not installed)::
+- *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
 ----
-- The odt output format is undocumented and experimental.
-- See also the AsciiDoc distribution BUGS file.
+See the AsciiDoc distribution BUGS file.
 
 
 AUTHOR
 ------
-Written by Stuart Rackham, <srackham@gmail.com>
+a2x was originally written by Stuart Rackham. Many people have
+contributed to it.
 
 
 RESOURCES
@@ -199,6 +341,6 @@ Main web site: http://www.methods.co.nz/asciidoc/
 
 COPYING
 -------
-Copyright \(C) 2002-2008 Stuart Rackham. Free use of this software is
-granted under the terms of the GNU General Public License (GPL).
+Copyright \(C) 2002-2011 Stuart Rackham. Free use of this software is
+granted under the terms of the MIT license.
 

data/asciidoc/doc/article-docinfo.xml

@@ -0,0 +1,87 @@
+<!--
+  article-docinfo.xml
+  Example DocBook document information file for article.txt.
+-->
+
+<authorgroup>
+  <author>
+    <honorific>Dr</honorific>
+    <firstname>Lois</firstname>
+    <surname>Common-Demoninator</surname>
+    <affiliation>
+      <shortaffil>Director, M. Behn School of Coop. Eng.</shortaffil>
+      <jobtitle>Director of Cooperative Efforts</jobtitle>
+      <orgname>The Marguerite Behn International School of
+               Cooperative Engineering</orgname>
+    </affiliation>
+  </author>
+
+  <author>
+    <honorific>Mr</honorific>
+    <firstname>Steven</firstname>
+    <surname>Norman</surname>
+    <othername role='mi'>T</othername>
+    <affiliation>
+      <shortaffil>ATI</shortaffil>
+      <jobtitle>Senior Application Analyst</jobtitle>
+      <orgname>Foobar, Inc.</orgname>
+      <orgdiv>Application Development</orgdiv>
+    </affiliation>
+  </author>
+
+  <editor>
+    <firstname>Peter</firstname>
+    <surname>Pan</surname>
+    <lineage>Sr.</lineage>
+    <othername>Spiderman</othername>
+    <authorblurb>
+      <para>
+      Peter's a super hero in his spare time.
+      </para>
+    </authorblurb>
+  </editor>
+</authorgroup>
+
+<copyright>
+  <year>2009</year>
+  <holder>Behn International</holder>
+</copyright>
+
+<legalnotice>
+  <simpara>
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+  </simpara>
+  <simpara>
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+  </simpara>
+  <simpara>
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+  </simpara>
+</legalnotice>
+
+<revhistory>
+  <revision>
+    <revnumber>1.1</revnumber>
+    <date>May 2009</date>
+    <authorinitials>PP</authorinitials>
+    <revremark>
+      Updates.
+    </revremark>
+  </revision>
+  <revision>
+    <revnumber>1.0</revnumber>
+    <date>October 2003</date>
+    <authorinitials>PP</authorinitials>
+    <revremark>
+      First release.
+    </revremark>
+  </revision>
+</revhistory>