Added a couple of FAQs and fixed some documentation erratum.

4 files changed, 151 insertions, 25 deletions

diff --git a/doc/asciidoc.dict b/doc/asciidoc.dict
index dd1cda0..05be360 100644
--- a/doc/asciidoc.dict
+++ b/doc/asciidoc.dict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 847 
+personal_ws-1.1 en 892 
 mandoc
 colspecs
 API
@@ -9,6 +9,7 @@ attributelist
 AttributeList
 Blondel
 permalink
+unescapes
 frontmatter
 libxslt
 asc
@@ -23,6 +24,7 @@ passtext
 ZapfDingbats
 CALS
 LiteralParagraph
+del
 BOM
 Bon
 ungenerated
@@ -41,11 +43,13 @@ Lorum
 superceded
 inlinegraphic
 specialcharacters
+cpp
 RevisionLine
 TitleName
 Fusce
 ralink
 scaledwidth
+FooParser
 VMiklos
 DelimitedBlocks
 css
@@ -74,6 +78,7 @@ RevisionNumber
 CommentBlocks
 consequat
 fmt
+Amade
 inline
 monospacedwords
 informaltable
@@ -98,6 +103,7 @@ xreflabel
 PDF's
 PDFs
 MSIE
+pede
 permalinks
 Daly
 arcu
@@ -108,6 +114,7 @@ listcontinuation
 ListContinuation
 apos
 ShareSource
+projectname
 hoc
 ispum
 Maier
@@ -118,6 +125,7 @@ gui
 ile
 sgmlfmt
 formulae
+dbkview
 AsciiDoc's
 BackendBlock
 tbody
@@ -134,6 +142,7 @@ starttags
 tgroup
 Miklos
 porttitor
+Maecenas
 systemIdStartString
 footnoteref
 joe
@@ -161,6 +170,7 @@ optionname
 companyname
 pageunits
 nec
+loc
 latexmath
 articleinfo
 auctor
@@ -183,8 +193,11 @@ ListItem
 coids
 shiftwidth
 nulla
+endDocument
 odt
 Cygwin
+ultrices
+indentedparagraph
 IndentedParagraph
 ltr
 doctests
@@ -195,6 +208,7 @@ Dvips
 Jython
 Solaris
 pdf
+authorgroup
 manpages
 ItemText
 dignissim
@@ -212,6 +226,7 @@ nunc
 CustomBlocks
 informalfigure
 ORed
+yyyy
 online
 LIBDIR
 docinfo
@@ -272,6 +287,7 @@ Bólido
 Bolido
 tabsize
 colpcwidth
+Orry
 onload
 RTF
 quickstart
@@ -280,6 +296,7 @@ bloggs
 tis
 listdef
 Tsawassen
+Aenean
 postsubs
 src
 LastName
@@ -298,24 +315,29 @@ prepended
 resx
 startup
 admonitionblock
+coord
 Blackdown
+mainmatter
 Slackware
 tableabswidth
 BackendBlocks
 VMiklos's
 sys
 doctype
+retrive
 uri
 wnone
 xhtml
 utf
 footrow
 usr
+Hausmann
 TitleBlock
 txt
 elit
 Efros's
 sectiontitle
+CommentLines
 subprocess
 outfile
 blandit
@@ -338,9 +360,12 @@ Morbi
 Blauer
 footdata
 cb
+bg
+al
 cd
 xsl
 backmatter
+ar
 fils
 de
 backends
@@ -349,6 +374,7 @@ br
 cp
 fb
 fermentum
+fi
 cellcount
 et
 fo
@@ -376,6 +402,7 @@ defacto
 mb
 IndentedBlocks
 js
+blogpost
 xsltproc
 jw
 ln
@@ -389,6 +416,7 @@ ly
 mv
 stylesheets
 roff
+YYY
 regex
 config
 tabstop
@@ -401,6 +429,7 @@ epub
 td
 Vivamus
 py
+th
 ru
 docname
 su
@@ -413,7 +442,9 @@ Frédérique
 SidebarBlock
 wj
 Efros
+param
 Movet
+hcol
 manpurpose
 colalign
 debian
@@ -451,7 +482,7 @@ ExampleBlocks
 linux
 commodo
 Fernandes
-Pretium
+pretium
 notitle
 manvolnum
 homero
@@ -465,14 +496,17 @@ doctitle
 Dmitry
 backtick
 Bouchers
+strikethrough
 indexterm
 Daitx
+vestibulum
 quote's
 noteblock
 refentry
 Xubuntu
 captionless
 orgname
+OpenOffice
 asciidocEmphasized
 chapt
 necessitatibus
@@ -537,11 +571,14 @@ java
 Sakellariou
 postulant
 Vasilev
+barchart
 Calixto
 sudo
+coverpage
 starttag
 whitespace
 DelimitedBlock
+foofoo
 retab
 changelog
 ChangeLog
@@ -567,6 +604,7 @@ POSIX
 builtins
 bulleted
 globals
+porta
 OpenBlock
 colabswidth
 Bushuev
@@ -631,6 +669,7 @@ RevisionRemark
 TableHeader
 Mihai
 KeyboardInterrupt
+justo
 sectionbody
 SectionBody
 nnoremap
@@ -664,7 +703,7 @@ blockmacro
 BlockMacro
 mailto
 http
-Pychart
+pychart
 Wiki
 euismod
 arounds
@@ -696,6 +735,7 @@ screenshot
 noout
 Wieers
 Artem
+startDocument
 ifdef
 manmanual
 Konqueror
@@ -705,6 +745,7 @@ LaTeXMathML
 latexmathml
 sectnum
 BlockMacros
+cceeff
 unfloat
 snabbköp
 snabbkop
@@ -747,6 +788,7 @@ revdate
 stylesheet
 eleifend
 ListTerm
+augue
 loweralpha
 subdirectory
 consectetuer
@@ -758,6 +800,7 @@ FreeBSD
 Araquil
 setuptools
 bfoobar
+lacinia
 entrytag
 muellner
 ifndef
@@ -832,6 +875,7 @@ ftdetect
 Greaves
 SimpleList
 superscripting
+baz
 lorem
 Comidas
 bodyrows
@@ -840,6 +884,7 @@ greek
 comspec
 refmiscinfo
 Firefox
+lectus
 JavaHelp
 unescaped
 mydoc
diff --git a/doc/asciidoc.txt b/doc/asciidoc.txt
index e4f29eb..87ebf27 100644
--- a/doc/asciidoc.txt
+++ b/doc/asciidoc.txt
@@ -2284,9 +2284,12 @@ single-file XHTML documents with embedded images and CSS, for example:
 
   $ asciidoc -a data-uri mydocument.txt
 
-NOTE: All current popular browsers support 'data URIs', although
-versions of Internet Explorer prior to version 8 do not support 'data
-URIs'.
+[NOTE]
+======
+- All current popular browsers support data URIs, although versions
+  of Internet Explorer prior to version 8 do not.
+- Some browsers limit the size of data URIs.
+======
 *********************************************************************
 
 [[X25]]
@@ -4961,8 +4964,8 @@ If the indentation and layout of the asciidoc(1) output is not to your
 liking you can:
 
 1. Change the indentation and layout of configuration file markup
-   template sections. The `{empty}` glossary entry is useful for
-   outputting trailing blank lines in markup templates.
+   template sections. The `{empty}` attribute is useful for outputting
+   trailing blank lines in markup templates.
 
 2. Use Dave Raggett's http://tidy.sourceforge.net/[HTML Tidy] program
    to tidy asciidoc(1) output. Example:
diff --git a/doc/faq.txt b/doc/faq.txt
index d09ef0f..120c400 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -2,6 +2,55 @@ AsciiDoc Frequently Asked Questions
 ===================================

 

 

+[NOTE]

+======

+- New FAQs are normally added at the top of this document.

+- The FAQ may be updated between AsciiDoc releases so some of the

+  newer FAQs may apply to the trunk and not the current release.

+======

+

+

+== How can I add highlighted editorial comments to an AsciiDoc document?

+Both block and inline link:userguide.html#X25[comment lines] are

+displayed on the output if the 'showcomments' attribute is defined.

+Example:

+

+[listing]

+.........................................

+:showcomments:

+// A *block comment line*.

+

+Qui in magna commodo, est labitur dolorum an. Est ne magna primis

+// An *inline comment line*.

+adolescens.

+.........................................

+

+Is rendered as:

+

+:showcomments:

+// A *block comment line*.

+

+Qui in magna commodo, est labitur dolorum an. Est ne magna primis

+// An *inline comment line*.

+adolescens.

+

+NOTE: link:userguide.html#X26[Comment blocks] are never displayed.

+

+

+== What is the preferred file name extension for AsciiDoc files?

+The `.txt` http://en.wikipedia.org/wiki/Text_file[text file] extension

+is preferred, but it's just a convention and it's not enforced by the

+software.

+

+AsciiDoc source files are human readable

+http://en.wikipedia.org/wiki/Plain_text[plain text] files which is

+what the `.txt` extension is for. All text editors recognize and open

+files with a `.txt` extension. The `.txt` extension is universally

+recognized and unambiguous -- you are not left asking questions like

+``What on earth is this file with the funny extension?'', ``How do I

+open it?'' and ``Is it safe to open?''.

+

+

 == How can I generate numbered bibliographic entries?

 If your outputs are DocBook generated then adding the following inline

 macro to a custom configuration file will result in auto-incrementing

@@ -35,7 +84,7 @@ pass them on the a2x(1) command-line. Here are some examples:
 

 The

 http://dblatex.sourceforge.net/doc/manual/latex.output.revhistory.html[latex.output.revhistory]

-parameter is used to supress the revision history:

+parameter is used to suppress the revision history:

 

   a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt

 

@@ -64,7 +113,7 @@ option, for example:
 

 == Why don't tables generated by dblatex obey the width attribute?

 Tables generated by dblatex will take 100% of the available space

-unless you change the 'pageunits' micellaneous parameter to 'pt'.

+unless you change the 'pageunits' miscellaneous parameter to 'pt'.

 Here's how:

 

 - From the command-line with the `-a pageunits=pt` option

@@ -93,7 +142,7 @@ attribute (this will just suppress displaying the title), for example:
 == Why am I having trouble getting nested macros to work?

 The following example expands the 'image' inline macro, but the

 expansion contains double-quote characters which confuses the ensuing

-'footnoteref' macro epansion:

+'footnoteref' macro expansion:

 

   footnoteref:["F1","A footnote, with an image image:smallnew.png[]"]

 

@@ -110,7 +159,7 @@ values using the `"` character entity.
 Not all valid AsciiDoc source generates valid DocBook, for example

 'special sections' (abstract, preface, colophon, dedication,

 bibliography, glossary, appendix, index, synopsis) have different

-DocBook schemas to normal document sections. For example, a paragraph

+DocBook schema's to normal document sections. For example, a paragraph

 is illegal in a bibliography.

 

 Don't forget if your document is a book you need to specify the

@@ -188,7 +237,7 @@ User Guide].
 This is the response to a question posted on the AsciiDoc discussion

 list, it illustrates a number of useful techniques. The question arose

 because the source highlight filter language identifier for the C++

-language is `c++` when generating PDF's via dblatex (LaTeX listings

+language is `c++` when generating PDFs via dblatex (LaTeX listings

 package) or `cpp` when generating HTML (GNU source-highlight).

 

 Using straight `ifdef::[]` block macros we have:

@@ -284,7 +333,7 @@ public:
 Most likely the passthrough encloses another passthrough with a higher

 precedence. For example trying to render this +\pass:[]+ with this

 +\`\pass:[]`+ results in a blank string because the +\pass:[]+

-passthrough evaluates first, instead use monspaced quoting  and escape

+passthrough evaluates first, instead use monospaced quoting  and escape

 the passthrough i.e. ++ \+\\pass:[]+ ++

 

 

@@ -402,18 +451,47 @@ This will restyle the entire document by indenting all paragraphs
 which is normally what you want to do (mixed paragraph styles produce

 ugly documents).

 

-To selectively indent paragraphs with the 'indented' style add the

-following line to the `xhtml11.css` stylesheet (or a custom

+To selectively indent paragraphs you could either create an 'indented'

+paragraph style from scratch or use the 'role' attribute.

+

+[float]

+==== Create an indented paragraph style

+Define an 'indented' paragraph style, for example, by putting this in

+a configuration file:

+

+---------------------------------------------------------------------

+[paradef-default]

+indented-style=template="indentedparagraph"

+

+[indentedparagraph]

+<div class="paragraph"{id? id="{id}"} style="text-indent:3em;">{title?<div class="title">{title}</div>}<p>

+|

+</p></div>

+---------------------------------------------------------------------

+

+Now apply the 'indented' style to normal paragraphs, for example:

+

+---------------------------------------------------------------------

+[indented]

+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas

+ultrices justo porttitor augue. Vestibulum pretium. Donec porta

+vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed

+lacinia. Vivamus at lectus.

+---------------------------------------------------------------------

+

+[float]

+==== Use the role attribute

+Add the following line to the `xhtml11.css` stylesheet (or a custom

 stylesheet).

 

 ---------------------------------------------------------------------

 div.paragraph.indented p {text-indent: 3em;}

 ---------------------------------------------------------------------

 

-Then apply the 'indented' style to normal paragraphs, for example:

+Apply the 'role' attribute to indented paragraphs, for example:

 

 ---------------------------------------------------------------------

-[indented]

+[role="indented"]

 Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas

 ultrices justo porttitor augue. Vestibulum pretium. Donec porta

 vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed

@@ -421,9 +499,9 @@ lacinia. Vivamus at lectus.
 ---------------------------------------------------------------------

 

 NOTE: This FAQ applies to XHTML output not DocBook. To achieve the

-same results with DocBook you would need to customize the DocBook XSL

-stylesheets to indent paragraphs with the `simpara` element

-`role="indented"` attribute.

+same results with DocBook use the 'role' attribute and customize the

+DocBook XSL stylesheets to indent paragraphs with the `simpara`

+element `role="indented"` attribute.

 

 

 == Is there a way to set default image height and width attributes?

@@ -442,7 +520,7 @@ image:images/tiger.png[]
 ---------------------------------------------------------------------

 

 NOTE: Setting the global 'width' attribute will also set the default

-table width and you will need to explicitly table widths.

+table width and you will need to explicitly set table widths.

 

 == How can I place a backslash character in front of an attribute reference without escaping the reference?

 

@@ -621,7 +699,7 @@ into OpenOffice Writer.
 This tip was contributed by Bernard Amade.

 

 

-== How can I supress cell separators in included table data files?

+== How can I suppress cell separators in included table data files?

 

 Use the `{include:}` system attribute instead of the `include::[]`

 macro (the former is not expanded until after the table data has been

@@ -777,7 +855,7 @@ asciidoc(1) `-a` command-line option:
 

   $ asciidoc -a localdate=`date +%d-%d-%Y` mydoc.txt

 

-You could also set it by adding an Attribute Entry to your souce

+You could also set it by adding an Attribute Entry to your source

 document, for example:

 

   :localdate: {sys: date +%Y-%m-%d}

diff --git a/doc/main.aap b/doc/main.aap
index c3281b4..d03158d 100644
--- a/doc/main.aap
+++ b/doc/main.aap
@@ -232,7 +232,7 @@ clean:
     :del {f} *.bak          # Remove aspell backups.

 

 spell: $INFILES ../CHANGELOG.txt ../README.txt ../BUGS.txt ../INSTALL.txt \

-        a2x.1.txt asciidocapi.txt testasciidoc.txt

+        a2x.1.txt faq.txt asciidocapi.txt testasciidoc.txt

     # Interactively spell check all files.

     @for s in source_list:

         :sys {i} $ASPELL check -p ./asciidoc.dict $s