Added a couple of FAQs and fixed some documentation erratum.

1 files changed, 94 insertions, 16 deletions

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}