mizuho 0.9.6 → 0.9.8

data/asciidoc/configure.ac

@@ -1,4 +1,4 @@
-AC_INIT(asciidoc, 8.3.1) 
+AC_INIT(asciidoc, 8.6.5)
 
 AC_CONFIG_FILES(Makefile)
 

data/asciidoc/dblatex/asciidoc-dblatex.xsl

@@ -15,6 +15,30 @@ See dblatex(1) -p option.
   <xsl:param name="table.in.float">0</xsl:param>
   <xsl:param name="monoseq.hyphenation">0</xsl:param>
   <xsl:param name="latex.output.revhistory">1</xsl:param>
+
+  <!-- This doesn't work, don't know why, see:
+  http://dblatex.sourceforge.net/html/manual/apas03.html
+  ./docbook-xsl/common.xsl
+  -->
+  <!--
+  <xsl:param name="doc.toc.show">
+    <xsl:choose>
+      <xsl:when test="/processing-instruction('asciidoc-toc')">
+1
+      </xsl:when>
+      <xsl:otherwise>
+0
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:param>
+  <xsl:param name="doc.lot.show">
+    <xsl:choose>
+      <xsl:when test="/book">
+figure,table,equation,example
+      </xsl:when>
+    </xsl:choose>
+  </xsl:param>
+  -->
   <xsl:param name="doc.toc.show">1</xsl:param>
 
   <!--
@@ -28,5 +52,23 @@ See dblatex(1) -p option.
     <xsl:text>&#10;\end{alltt}</xsl:text>
   </xsl:template>
 
+  <xsl:template match="processing-instruction('asciidoc-pagebreak')">
+    <!-- force hard pagebreak, varies from 0(low) to 4(high) -->
+    <xsl:text>\pagebreak[4] </xsl:text>
+    <xsl:apply-templates />
+    <xsl:text>&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction('asciidoc-br')">
+    <xsl:text>\newline&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction('asciidoc-hr')">
+    <!-- draw a 444 pt line (centered) -->
+    <xsl:text>\begin{center}&#10; </xsl:text>
+    <xsl:text>\line(1,0){444}&#10; </xsl:text>
+    <xsl:text>\end{center}&#10; </xsl:text>
+  </xsl:template>
+
 </xsl:stylesheet>
 

data/asciidoc/doc/a2x.1

@@ -1,51 +1,67 @@
+'\" t
 .\"     Title: a2x
-.\"    Author: 
-.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\"      Date: 01/02/2009
-.\"    Manual: 
-.\"    Source: 
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\"      Date: 20 May 2011
+.\"    Manual: \ \&
+.\"    Source: \ \& 8.6.5
+.\"  Language: English
 .\"
-.TH "A2X" "1" "01/02/2009" "" ""
+.TH "A2X" "1" "20 May 2011" "\ \& 8\&.6\&.5" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
 .ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
 .SH "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)
 .SH "SYNOPSIS"
-\fBa2x\fR [\fIOPTIONS\fR] \fIFILE\fR
 .sp
+\fBa2x\fR [\fIOPTIONS\fR] \fISOURCE_FILE\fR
 .SH "DESCRIPTION"
-A DocBook toolchain wrapper script that translates an AsciiDoc text file \fIFILE\fR 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\.
 .sp
+A DocBook toolchain manager that translates an AsciiDoc text file \fISOURCE_FILE\fR to PDF, EPUB, DVI, PS, LaTeX, XHTML (single page or chunked), man page, HTML Help or plain text formats using \fIasciidoc(1)\fR and other applications (see REQUISITES section)\&. \fISOURCE_FILE\fR can also be a DocBook file with an \&.xml extension\&.
 .SH "OPTIONS"
 .PP
 \fB\-a, \-\-attribute\fR=\fIATTRIBUTE\fR
 .RS 4
 Set asciidoc(1) attribute value (shortcut for
 \fB\-\-asciidoc\-opts\fR=\fI"\-a ATTRIBUTE"\fR
-option)\. This option may be specified more than once\.
+option)\&. This option may be specified more than once\&.
 .RE
 .PP
 \fB\-\-asciidoc\-opts\fR=\fIASCIIDOC_OPTS\fR
 .RS 4
-Additional asciidoc(1) options\. This option may be specified more than once\.
+Additional
+\fIasciidoc(1)\fR
+options\&. This option may be specified more than once\&.
 .RE
 .PP
-\fB\-\-copy\fR
+\fB\-\-conf\-file\fR=\fICONF_FILE\fR
 .RS 4
-Copy distributed docbook\-xsl CSS stylesheet admonition and navigation icons to their respective destinations\. Applies to
-\fIxhtml\fR,
-\fIchunked\fR,
-\fIhtmlhelp\fR
-formats\. The default behavior is to suppress copying\.
+Load configuration file\&. See
+CONF FILES section\&.
 .RE
 .PP
-\fB\-D, \-\-destination\-dir\fR=\fIPATH\fR
+\fB\-D, \-\-destination\-dir\fR=\fIDESTINATION_DIR\fR
 .RS 4
-Output directory\. Defaults to source
-\fIFILE\fR
-directory\.
+Output directory\&. Defaults to
+\fISOURCE_FILE\fR
+directory\&.
 .RE
 .PP
 \fB\-d, \-\-doctype\fR=\fIDOCTYPE\fR
@@ -54,204 +70,645 @@ DocBook document type:
 \fIarticle\fR,
 \fImanpage\fR
 or
-\fIbook\fR\. Default document type is
+\fIbook\fR\&. Default document type is
 \fIarticle\fR
 unless the format is
 \fImanpage\fR
 (in which case it defaults to
-\fImanpage\fR)\.
+\fImanpage\fR)\&.
 .RE
 .PP
 \fB\-f, \-\-format\fR=\fIFORMAT\fR
 .RS 4
-Output format:
+Output formats:
 \fIchunked\fR,
+\fIdocbook\fR,
 \fIdvi\fR,
+\fIepub\fR,
 \fIhtmlhelp\fR,
 \fImanpage\fR,
-\fIpdf\fR,
+\fIpdf\fR
+(default),
 \fIps\fR,
 \fItex\fR,
-\fItext\fR
-or
-\fIxhtml\fR\.
+\fItext\fR,
+\fIxhtml\fR\&.
 .RE
 .PP
 \fB\-h, \-\-help\fR
 .RS 4
-Print command\-line syntax and program options to stdout\.
+Print command\-line syntax and program options to stdout\&.
 .RE
 .PP
 \fB\-\-icons\fR
 .RS 4
-Use admonition or navigation icon images in output documents\. The default behavior is to use text in place of icons\.
+Use admonition or navigation icon images in output documents\&. The default behavior is to use text in place of icons\&.
 .RE
 .PP
 \fB\-\-icons\-dir\fR=\fIPATH\fR
 .RS 4
-A path (relative to destination HTML files) containing admonition and navigation icons\. Defaults to
-\fI\./images/icons/\fR\. Applies to
-\fIxhtml\fR,
-\fIchunked\fR,
-\fIhtmlhelp\fR
-formats\.
+A path (relative to output files) containing admonition and navigation icons\&. Defaults to
+images/icons\&. The
+\fI\-\-icons\fR
+option is implicit if this option is used\&.
+.RE
+.PP
+\fB\-k, \-\-keep\-artifacts\fR
+.RS 4
+Do not delete temporary build files\&.
+.RE
+.PP
+\fB\-\-lynx\fR
+.RS 4
+Use
+\fIlynx(1)\fR
+to generate text formatted output\&. The default behavior is to use
+\fIw3m(1)\fR\&.
 .RE
 .PP
 \fB\-L, \-\-no\-xmllint\fR
 .RS 4
-Don\(cqt check asciidoc output with
-\fIxmllint(1)\fR\.
+Do not check asciidoc output with
+\fIxmllint(1)\fR\&.
+.RE
+.PP
+\fB\-\-\-epubcheck\fR
+.RS 4
+Check EPUB output with
+\fIepubcheck(1)\fR\&.
 .RE
 .PP
 \fB\-n, \-\-dry\-run\fR
 .RS 4
-Don\(cqt do anything just print what would have been done\.
+Do not do anything just print what would have been done\&.
 .RE
 .PP
-\fB\-s, \-\-skip\-asciidoc\fR
+\fB\-r, \-\-resource\fR=\fIRESOURCE_SPEC\fR
 .RS 4
-Skip asciidoc execution\. This is useful for converting DocBook XML files not derived from AsciiDoc sources\. Ignored if
-\fI\-\-format=text\fR\.
+Specify a resource\&. This option may be specified more than once\&. See the
+\fBRESOURCES\fR
+section for more details\&.
 .RE
 .PP
-\fB\-\-stylesheet\fR=\fIPATH\fR
+\fB\-m, \-\-resource\-manifest\fR=\fIFILE\fR
 .RS 4
-A path (relative to destination HTML files) specifying the docbook\-xsl CSS stylesheet file\. Defaults to
-\fI\./docbook\-xsl\.css\fR\. Applies to
+
+\fIFILE\fR
+contains a list resources (one per line)\&. Manifest
+\fIFILE\fR
+entries are formatted just like
+\fB\-\-resource\fR
+option arguments\&. Environment variables and tilde home directories are allowed\&.
+.RE
+.PP
+\fB\-\-stylesheet\fR=\fISTYLESHEET\fR
+.RS 4
+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
+\fIdocbook\-xsl\&.css\fR\&. The stylesheets are processed in list order\&. The stylesheets must reside in a valid
+resource file
+location\&. Applies to HTML formats:
 \fIxhtml\fR,
+\fIepub\fR,
 \fIchunked\fR,
 \fIhtmlhelp\fR
-formats\.
+formats\&.
 .RE
 .PP
 \fB\-v, \-\-verbose\fR
 .RS 4
-Print operational details to stderr\. A second
+Print operational details to stderr\&. A second
 \fB\-v\fR
-option applies the verbose option to toolchain commands\.
+option applies the verbose option to toolchain commands\&.
 .RE
 .PP
 \fB\-\-version\fR
 .RS 4
-Print program version to stdout\.
+Print program version to stdout\&.
 .RE
 .PP
 \fB\-\-xsltproc\-opts\fR=\fIXSLTPROC_OPTS\fR
 .RS 4
-Additional xsltproc(1) options\. This option may be specified more than once\.
+Additional
+\fIxsltproc(1)\fR
+options\&. This option may be specified more than once\&.
+.RE
+.PP
+\fB\-\-xsl\-file\fR=\fIXSL_FILE\fR
+.RS 4
+Override the built\-in XSL stylesheet with the custom XSL stylesheet
+\fIXSL_FILE\fR\&.
 .RE
 .PP
 \fB\-\-fop\fR
 .RS 4
-Use FOP to generate PDFs\.
+Use FOP to generate PDFs\&. The default behavior is to use
+\fIdblatex(1)\fR\&. The
+\fI\-\-fop\fR
+option is implicit if this option is used\&.
 .RE
 .PP
 \fB\-\-fop\-opts\fR=\fIFOP_OPTS\fR
 .RS 4
-Additional fop options\. This option may be specified more than once\. If this option is specified FOP is used to generate PDFs\.
+Additional
+\fIfop(1)\fR
+options\&. If this option is specified FOP is used to generate PDFs\&. This option may be specified more than once\&.
 .RE
 .PP
 \fB\-\-dblatex\-opts\fR=\fIDBLATEX_OPTS\fR
 .RS 4
-Additional dblatex options\. This option may be specified more than once\.
+Additional
+\fIdblatex(1)\fR
+options\&. This option may be specified more than once\&.
+.RE
+.sp
+Options can also be set in the AsciiDoc source file\&. If \fISOURCE_FILE\fR contains a comment line beginning with \fB// a2x:\fR then the remainder of the line will be treated as \fIa2x\fR command\-line options\&. For example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+// a2x default options\&.
+//    a2x: \-dbook \-\-epubcheck
+// Suppress revision history in dblatex outputs\&.
+//    a2x: \-\-dblatex\-opts "\-P latex\&.output\&.revhistory=0"
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Options spanning multiple such comment lines will be concatenated\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Zero or more white space characters can appear between the leading
+\fB//\fR
+and
+\fBa2x:\fR\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+Command\-line options take precedence over options set in the source file\&.
 .RE
 .SH "OUTPUT FILES"
-Output files are written to the directory specified by the \fB\-\-destination\-dir\fR option\. If no \fB\-\-destination\-dir\fR option is set output files are written to the source FILE directory\.
 .sp
-Output files have the same name as the source \fIFILE\fR but with an appropriate file name extension: \.html for \fIxhtml\fR; \.hhp for \fIhtmlhelp\fR; \.pdf for \fIpdf\fR; \.text for \fItext\fR\. 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 are written to the directory specified by the \fB\-\-destination\-dir\fR option\&. If no \fB\-\-destination\-dir\fR option is set output files are written to the \fISOURCE_FILE\fR directory\&.
+.sp
+Output files have the same name as the \fISOURCE_FILE\fR but with an appropriate file name extension: \&.html for \fIxhtml\fR; \&.epub for \fIepub\fR; \&.hhp for \fIhtmlhelp\fR; \&.pdf for \fIpdf\fR; \&.text for \fItext\fR, \&.xml for \fIdocbook\fR\&. 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\&.
 .sp
-Same named existing files are overwritten\.
+Same named existing files are overwritten\&.
+.sp
+In addition to generating HTML files the \fIxhtml\fR, \fIepub\fR, \fIchunked\fR and \fIhtmlhelp\fR formats ensure resource files are copied to their correct destination directory locations\&.
+.SH "RESOURCES"
+.sp
+Resources are files (typically CSS and images) that are required by HTML based outputs (\fIxhtml\fR, \fIepub\fR, \fIchunked\fR, \fIhtmlhelp\fR formats)\&. \fIa2x\fR scans the generated HTML files and builds a list of required CSS and image files\&. Additional resource files can be specified explicitly using the \fB\-\-resource\fR option\&.
+.sp
+\fIa2x\fR searches for resource files in the following locations in the following order:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+The
+\fISOURCE_FILE\fR
+directory\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+Resource directories specified by the
+\fB\-\-resource\fR
+option (searched recursively)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+Resource directories specified by the
+\fB\-\-resource\-manifest\fR
+option (searched recursively in the order they appear in the manifest file)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+The stock
+images
+and
+stylesheets
+directories in the
+\fIasciidoc(1)\fR
+configuration files directories (searched recursively)\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 5.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  5." 4.2
+.\}
+The destination directory\&.
+.RE
+.sp
+When a resource file is found it is copied to the correct relative destination directory\&. Missing destination sub\-directories are created automatically\&.
+.sp
+There are two distinct mechanisms for specifying additional resources:
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+A resource directory which will be searched recursively for missing resource files\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+A resource file which will be copied to the output destination directory\&.
+.RE
 .sp
-Intermediate output files are written to the source \fIFILE\fR directory and are not automatically deleted\.
+Resources are specified with \fB\-\-resource\fR option values which can be one of the following formats:
 .sp
-Intermediate DocBook XML files generated by AsciiDoc are only regenerated if out of date with respect to the AsciiDoc source \fIFILE\fR\.
+.if n \{\
+.RS 4
+.\}
+.nf
+<resource_dir>
+<resource_file>[=<destination_file>]
+\&.<ext>=<mimetype>
+.fi
+.if n \{\
+.RE
+.\}
 .sp
-In addition to generating HTML files the \fIxhtml\fR, \fIchunked\fR and \fIhtmlhelp\fR 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\.
+Where:
+.PP
+<resource_dir>
+.RS 4
+Specifies a directory (absolute or relative to the
+\fISOURCE_FILE\fR) which is searched recursively for missing resource files\&. To eliminate ambiguity the
+<resource_dir>
+name should end with a directory separator character\&.
+.RE
+.PP
+<resource_file>
+.RS 4
+Specifies a resource file (absolute or relative to the
+\fISOURCE_FILE\fR) which will be copied to
+<destination_file>\&. If
+<destination_file>
+is not specified then it is the same as the
+<resource_file>\&.
+.RE
+.PP
+<destination_file>
+.RS 4
+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
+\fIFORMAT\fR
+(see the
+\fBOUTPUT FILES\fR
+section for details):
+.PP
+chunked, htmlhelp
+.RS 4
+The chunked output directory\&.
+.RE
+.PP
+epub
+.RS 4
+The archived
+OEBPS
+directory\&.
+.RE
+.PP
+xhtml
+.RS 4
+The output
+\fBDESTINATION_DIR\fR\&.
+.RE
+.RE
+.PP
+\&.<ext>=<mimetype>
+.RS 4
+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\&.
+.RE
 .sp
-The \fIxhtml\fR format generates a single XHTML output page\. The \fIchunked\fR 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 \fIFILE\fR name plus a \.chunked extension\.
+Resource option examples:
 .sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\-\-resource \&.\&./images/
+\-\-resource doc/README\&.txt=README\&.txt
+\-\-resource ~/images/tiger\&.png=images/tiger\&.png
+\-\-resource \&.ttf=application/x\-font\-ttf
+.fi
+.if n \{\
+.RE
+.\}
 .SH "EXAMPLES"
 .PP
-a2x \-f pdf doc/source\-highlight\-filter\.txt
+a2x \-f pdf doc/source\-highlight\-filter\&.txt
 .RS 4
-Generates doc/source\-highlight\-filter\.pdf file\.
+Generates
+doc/source\-highlight\-filter\&.pdf
+file\&.
 .RE
 .PP
-a2x \-f chunked \-D \.\./webpages guide\.txt
+a2x \-f xhtml \-D \&.\&./doc \-\-icons \-r \&.\&./images/ team\&.txt
 .RS 4
-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\.
+Creates HTML file
+\&.\&./doc/team\&.html, uses admonition icons and recursively searches the
+\&.\&./images/
+directory for any missing resources\&.
 .RE
-.SH "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):
 .PP
-Asciidoc
+a2x \-f manpage doc/asciidoc\&.1\&.txt
+.RS 4
+Generate
+doc/asciidoc\&.1
+manpage\&.
+.RE
+.SH "REQUISITES"
+.sp
+\fIa2x\fR uses the following programs:
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://www\.methods\.co\.nz/asciidoc/
+\fBAsciidoc\fR:
+http://www\&.methods\&.co\&.nz/asciidoc/
 .RE
-.PP
-xsltproc
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://xmlsoft\.org/XSLT/
+\fBxsltproc\fR: (all formats except text):
+http://xmlsoft\&.org/XSLT/
 .RE
-.PP
-DocBook XSL Stylesheets
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://docbook\.sourceforge\.net/projects/xsl/
+\fBDocBook XSL Stylesheets\fR
+(all formats except text):
+http://docbook\&.sourceforge\&.net/projects/xsl/
 .RE
-.PP
-dblatex (for PDF, DVI, PostScript and LaTeX file generation)
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://dblatex\.sourceforge\.net/
+\fBdblatex\fR
+(pdf, dvi, ps, tex formats):
+http://dblatex\&.sourceforge\&.net/
 .RE
-.PP
-FOP (alternative PDF file generation)
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://xmlgraphics\.apache\.org/fop/
+\fBFOP\fR
+(pdf format \(em alternative PDF file generator):
+http://xmlgraphics\&.apache\&.org/fop/
 .RE
-.PP
-w3m (text file generation)
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://w3m\.sourceforge\.net/index\.en\.html
+\fBw3m\fR
+(text format):
+http://w3m\&.sourceforge\&.net/index\&.en\&.html
 .RE
-.PP
-Lynx (used for text file generation if w3m(1) not installed)
+.sp
 .RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 
-http://lynx\.isc\.org/
+\fBLynx\fR
+(text format \(em alternative text file generator):
+http://lynx\&.isc\&.org/
 .RE
-See also the latest README file\.
 .sp
-.SH "BUGS"
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+
+\fBepubcheck\fR
+(epub format \(em EPUB file validator):
+http://code\&.google\&.com/p/epubcheck/
+.RE
+.sp
+See also the latest README file\&.
+.SH "CONF FILES"
+.sp
+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:
 .sp
 .RS 4
-\h'-04'\(bu\h'+03'The odt output format is undocumented and experimental\.
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+
+a2x\&.conf
+from the directory containing the
+\fIa2x\&.py\fR
+executable\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+
+a2x\&.conf
+from the AsciiDoc global configuration directory\&. Skip this step if we are executing a locally installed (non system wide) copy\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 3.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  3." 4.2
+.\}
+
+a2x\&.conf
+from the AsciiDoc
+$HOME/\&.asciidoc
+configuration directory\&.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 4.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  4." 4.2
+.\}
+The
+\fICONF_FILE\fR
+specified in the
+\fI\-\-conf\-file\fR
+option\&.
 .RE
 .sp
+Here are the default configuration file option values:
+.sp
+.if n \{\
 .RS 4
-\h'-04'\(bu\h'+03'See also the AsciiDoc distribution BUGS file\.
+.\}
+.nf
+# Optional environment variable dictionary passed to
+# executing programs\&. If set to None the existing
+# environment is used\&.
+ENV = None
+
+# External executables\&.
+ASCIIDOC = \*(Aqasciidoc\*(Aq
+XSLTPROC = \*(Aqxsltproc\*(Aq
+DBLATEX = \*(Aqdblatex\*(Aq         # pdf generation\&.
+FOP = \*(Aqfop\*(Aq                 # pdf generation (\-\-fop option)\&.
+W3M = \*(Aqw3m\*(Aq                 # text generation\&.
+LYNX = \*(Aqlynx\*(Aq               # text generation (if no w3m)\&.
+XMLLINT = \*(Aqxmllint\*(Aq         # Set to \*(Aq\*(Aq to disable\&.
+EPUBCHECK = \*(Aqepubcheck\*(Aq     # Set to \*(Aq\*(Aq to disable\&.
+# External executable default options\&.
+ASCIIDOC_OPTS = \*(Aq\*(Aq
+DBLATEX_OPTS = \*(Aq\*(Aq
+FOP_OPTS = \*(Aq\*(Aq
+XSLTPROC_OPTS = \*(Aq\*(Aq
+.fi
+.if n \{\
 .RE
+.\}
+.SH "BUGS"
+.sp
+See the AsciiDoc distribution BUGS file\&.
 .SH "AUTHOR"
-Written by Stuart Rackham, <srackham@gmail\.com>
 .sp
+a2x was originally written by Stuart Rackham\&. Many people have contributed to it\&.
 .SH "RESOURCES"
-SourceForge: http://sourceforge\.net/projects/asciidoc/
 .sp
-Main web site: http://www\.methods\.co\.nz/asciidoc/
+SourceForge: http://sourceforge\&.net/projects/asciidoc/
 .sp
+Main web site: http://www\&.methods\&.co\&.nz/asciidoc/
 .SH "COPYING"
-Copyright (C) 2002\-2008 Stuart Rackham\. Free use of this software is granted under the terms of the GNU General Public License (GPL)\.
 .sp
+Copyright (C) 2002\-2011 Stuart Rackham\&. Free use of this software is granted under the terms of the MIT license\&.