Polished a2x man page.

3 files changed, 53 insertions, 35 deletions

diff --git a/a2x.py b/a2x.py
index bbf55d4..07c4f21 100755
--- a/a2x.py
+++ b/a2x.py
@@ -741,7 +741,7 @@ if __name__ == '__main__':
     parser.add_option('-r','--resource-dir',
         action='append', dest='resource_dirs', default=[],
         metavar='PATH',
-        help='directory containing images and stylesheets')
+        help='directory containing image and stylesheet resources')
     #DEPRECATED
     parser.add_option('-s','--skip-asciidoc',
         action='store_true', dest='skip_asciidoc', default=False,
diff --git a/doc/a2x.1.txt b/doc/a2x.1.txt
index 5c5b008..a0f1199 100644
--- a/doc/a2x.1.txt
+++ b/doc/a2x.1.txt
@@ -72,15 +72,13 @@ OPTIONS
   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. Finally, if a resource is still not found
-  then 'a2x' will recursively search directories named 'images' and
-  'stylesheets' in the 'asciidoc' configuration files directory.
-
-*--stylesheet*='PATH'::
-  A path (relative to destination HTML files) specifying the
-  docbook-xsl CSS stylesheet file. Defaults to 'docbook-xsl.css'.
+  Recursively search 'PATH' for required image or CSS <<X3,resource
+  file>>.  This option may be specified more than once.
+
+*--stylesheet*='STYLESHEET'::
+  The file name of the docbook-xsl CSS stylesheet file. Defaults to
+  'docbook-xsl.css'.  The stylesheet must reside in a valid <<X3,
+  resource file>> location.
   Applies to HTML formats: 'xhtml', 'epub', 'chunked', 'htmlhelp'
   formats.
 
@@ -137,11 +135,29 @@ appropriate file name extension: `.html` for 'xhtml'; `.epub` for
 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.
+and 'htmlhelp' formats ensure image and CSS stylesheet <<X3,resource
+files>> are copied to their correct destination directory locations.
+
+
+[[X3]]
+RESOURCES
+---------
+Resources are local CSS and images files that are required by HTML
+based outputs ('xhtml', 'epub', 'chunked', 'htmlhelp' formats).
+
+'a2x' searches for resources in the following locations in the
+following order:
+
+. The source 'FILE' directory.
+. Directories specified by *--resource-dir* options (recursively).
+. The 'asciidoc(1)' `images` and `stylesheets` configuration file directories
+  (recursively).
+. The destination directory.
+
+If a required resource cannot be found a 'missing resource' warning
+message is generated. If the resource is found then it is copied to
+the correct relative destination directory.  Missing destination
+sub-directories are created automatically.
 
 
 EXAMPLES
diff --git a/doc/asciidoc.dict b/doc/asciidoc.dict
index 02d996c..1416eb6 100644
--- a/doc/asciidoc.dict
+++ b/doc/asciidoc.dict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 907 
+personal_ws-1.1 en 909 
 mandoc
 colspecs
 API
@@ -29,8 +29,8 @@ BOM
 Bon
 ungenerated
 zipP
-cmd
 des
+cmd
 ListItems
 dev
 vulputate
@@ -67,6 +67,7 @@ CVS
 DTD
 Graphviz
 toclevel
+plaintext
 hyperlinks
 dsv
 ENV
@@ -90,8 +91,8 @@ hhc
 Chai
 strongwords
 setlocal
-listingblock
 ListingBlock
+listingblock
 exe
 AuthorInfo
 vsides
@@ -104,8 +105,8 @@ magna
 xreflabel
 PDF's
 PDFs
-pede
 MSIE
+pede
 permalinks
 Daly
 arcu
@@ -118,8 +119,8 @@ apos
 ShareSource
 projectname
 hoc
-Maier
 ispum
+Maier
 TableFooter
 blog
 passthroughs
@@ -172,8 +173,8 @@ symlinks
 optionname
 companyname
 pageunits
-loc
 nec
+loc
 latexmath
 articleinfo
 auctor
@@ -201,12 +202,12 @@ endDocument
 odt
 Cygwin
 ultrices
-IndentedParagraph
 indentedparagraph
+IndentedParagraph
 ltr
 doctests
-asciidocapi
 AsciiDocAPI
+asciidocapi
 itemtag
 Dvips
 Jython
@@ -239,9 +240,9 @@ BlockId
 png
 lobortis
 Bowlin
-ASCIIMathML
-AsciiMathML
 asciimathml
+AsciiMathML
+ASCIIMathML
 conf
 RCS
 CalloutList
@@ -289,8 +290,8 @@ pgwide
 RevisionDate
 crlf
 tex
-Bolido
 Bólido
+Bolido
 tabsize
 colpcwidth
 Orry
@@ -305,8 +306,8 @@ Tsawassen
 Aenean
 postsubs
 src
-lastname
 LastName
+lastname
 toc
 tmp
 Knisley
@@ -351,13 +352,13 @@ revisionhistory
 params
 undefines
 Andrés
-HTMLHelp
 htmlhelp
+HTMLHelp
 cellspacing
 Citeaux
 srackham
-Lulea
 Luleå
+Lulea
 Ubuntu
 xml
 XSLTLib
@@ -389,8 +390,8 @@ hg
 guimenu
 toclevels
 xzf
-JB
 gq
+JB
 refactored
 sgml
 backcolor
@@ -411,8 +412,8 @@ js
 blogpost
 xsltproc
 jw
-nd
 ln
+nd
 ne
 oa
 Terje
@@ -434,8 +435,8 @@ ps
 runtime
 tcqn
 epub
-td
 px
+td
 Vivamus
 py
 th
@@ -641,6 +642,7 @@ VariableList
 LiteralBlocks
 Donec
 BLONP
+dbook
 asciimath
 interesset
 formatlistpat
@@ -827,8 +829,8 @@ toolchain
 cellpadding
 entrytbl
 authorinitials
-JavaScripts
 javascripts
+JavaScripts
 undefining
 leveloffset
 CustomBlock
@@ -882,8 +884,8 @@ Redhat
 datadir
 Kumar
 IndentedParagraphs
-Berguvsvägen
 Berguvsvagen
+Berguvsvägen
 executables
 tabledef
 ftdetect
@@ -903,6 +905,6 @@ lectus
 JavaHelp
 unescaped
 mydoc
-MiddleName
 middlename
+MiddleName
 Jimmac's