More FAQs and documentation updates.

5 files changed, 93 insertions, 15 deletions

diff --git a/asciidoc.conf b/asciidoc.conf
index 03e05ec..acf940f 100644
--- a/asciidoc.conf
+++ b/asciidoc.conf
@@ -16,7 +16,10 @@ toclevels=2
 sectids=

 iconsdir=./images/icons

 encoding=UTF-8

+# Uncomment to use xhtml11 quirks mode CSS.

 quirks=

+# Uncomment to use the Pygments source highlighter.

+#pygments=

 empty=

 # Attribute and AttributeList element patterns.

 attributeentry-pattern=^:(?P<attrname>\w[^.]*?)(\.(?P<attrname2>.*?))?:(\s+(?P<attrvalue>.*))?$

diff --git a/doc/asciidoc.dict b/doc/asciidoc.dict
index 05be360..6ce4559 100644
--- a/doc/asciidoc.dict
+++ b/doc/asciidoc.dict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 892 
+personal_ws-1.1 en 893 
 mandoc
 colspecs
 API
@@ -406,6 +406,7 @@ blogpost
 xsltproc
 jw
 ln
+nd
 ne
 Terje
 lt
diff --git a/doc/asciidoc.txt b/doc/asciidoc.txt
index 5ed3ea5..dcf7750 100644
--- a/doc/asciidoc.txt
+++ b/doc/asciidoc.txt
@@ -1956,8 +1956,8 @@ Which renders:
   escape it with a backslash to prevent it being interpreted as a
   callout mark.
 
-NOTE: To include callout icons in PDF files generated by
-<<X43,a2x(1)>> you need to use the `--icons` command-line option.
+NOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a
+icons` command-line option) to display callout icons.
 
 Implementation Notes
 ~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/faq.txt b/doc/faq.txt
index 120c400..9f1ea0c 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -9,6 +9,70 @@ AsciiDoc Frequently Asked Questions
   newer FAQs may apply to the trunk and not the current release.

 ======

 

+== DocBook has many elements for document meta-data -- how can I use them from AsciiDoc?

+If the 'docinfo' attribute is defined then AsciiDoc looks for a file

+named like the source file but ending in `-docinfo.xml` and includes

+it in the output document. See the link:userguide.html#X87[Additional

+document header information] section in the AsciiDoc User Guide for

+details.

+

+

+== Do element titles automatically generate link captions?

+If you go the DocBook route then yes -- just omit the caption from the

+AsciiDoc 'xref' (`<<...>>`) macro. Both dblatex and DocBook XSL will

+use the target element's title text. Examples:

+

+[listing]

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

+[[X1]]

+Section One

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

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

+ultrices justo porttitor augue. Vestibulum pretium. Donec porta

+

+See also <<X3>> (this link displays the text 'A titled paragraph').

+

+[id="X2",reftext="2nd section"]

+Section Two

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

+See also <<X1>> (this link displays the text 'Section One').

+

+[[X3]]

+.A titled paragraph

+Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

+

+See also <<X2>> (this link displays the text '2nd section').

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

+

+The AsciiDoc 'reftext' attribute has been used to explicitly set the

+link text to '2nd section' for 'Section Two'.

+

+

+== Can I define my own table styles?

+In addition to the built-in styles you can define your own. This

+example (for the 'xhtml11' backend) defines a table style called 'red'

+which sets the background cell color to red. First put the definition

+in a configuration file:

+

+[listing]

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

+[tabledef-default]

+red-style=tags="red"

+

+[tabletags-red]

+bodydata=<td style="background-color:red;">|</td>

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

+

+Now you can use the style name to style cells or columns (in this

+example we use an unambiguous shortened abbreviation 'r'):

+

+[listing]

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

+|==================================

+|Normal cell      r|Red cell

+|==================================

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

+

 

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

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

diff --git a/doc/source-highlight-filter.txt b/doc/source-highlight-filter.txt
index 70962ad..992529c 100644
--- a/doc/source-highlight-filter.txt
+++ b/doc/source-highlight-filter.txt
@@ -5,19 +5,28 @@ The AsciiDoc distribution includes a source code syntax highlight
 filter (`source-highlight-filter.conf`). It uses
 http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
 highlight HTML outputs. You also have the option of using the
-http://pygments.org/[Pygments] syntax highlighter for 'xhtm11' outputs
--- define an AsciiDoc attribute named 'pygments' to switch to Pygments
-(you will also need to have Pygments installed and the 'pygmentize'
-command in your PATH).  You can customize Pygments CSS styles by
-editing `./stylesheets/pygments.css`.
+http://pygments.org/[Pygments] syntax highlighter for 'xhtm11'
+outputs.
+
+To use Pygments you need to define an AsciiDoc attribute named
+'pygments' (either from the command-line or in the global
+`asciidoc.conf` configuration file) and you will also need to have
+Pygments installed and the 'pygmentize' command in your PATH.  You can
+customize Pygments CSS styles by editing `./stylesheets/pygments.css`.
+To make Pygments your default highlighter put the following line your
+`~/.asciidoc/asciidoc.conf` file:
 
 DocBook outputs are highlighted by toolchains that have
 `programlisting` element highlight support, for example 'dblatex'.
 
-TIP: If the source 'language' attribute has been set (using an
-'AttributeEntry' or from the command-line) you don't have to specify
-it in each source code block.
-
+[TIP]
+=====
+- If the source 'language' attribute has been set (using an
+  'AttributeEntry' or from the command-line) you don't have to specify
+  it in each source code block.
+- You may need to place callout markers inside source code comments to
+  ensure they are not misinterpereted and mangled by the hightlighter.
+=====
 
 Examples
 --------
@@ -178,9 +187,10 @@ Installation
 HTML
 ~~~~
 If you want to syntax highlight AsciiDoc HTML outputs (`html4` and
-`xhtml11` backends) you need to
-install http://www.gnu.org/software/src-highlite/[GNU
-source-highlight] (most distributions have this package).
+`xhtml11` backends) you need to install
+http://www.gnu.org/software/src-highlite/[GNU source-highlight] or
+http://pygments.org/[Pygments] (most distributions have these
+packages).
 
 DocBook
 ~~~~~~~