Updated FAQ and fixed a typo.

3 files changed, 251 insertions, 32 deletions

diff --git a/doc/faq.txt b/doc/faq.txt
index 8ef689d..d09ef0f 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -26,6 +26,33 @@ as a listing block. For example:
   ...........................

 

 

+== How can I customize PDF files generated by dblatex?

+

+There are a number of dblatex XSL parameters that can be used to

+customize PDF output. You can set them globally in the AsciiDoc

+`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also

+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:

+

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

+

+The

+http://dblatex.sourceforge.net/doc/manual/doc.layout.html[doc.layout]

+parameter is used to include the cover page and document body (i.e. excludes

+table of contents and index), the

+http://dblatex.sourceforge.net/doc/manual/doc.publisher.show.html[doc.publisher.show]

+parameter is used to exclude the cover page logo:

+

+  a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt

+

+See also the

+http://dblatex.sourceforge.net/doc/manual/sec-params.html[dblatex XSL

+parameter reference].

+

+

 == How can I add lists of figures and tables to PDFs created by dblatex?

 Set the

 http://dblatex.sourceforge.net/doc/sec-custom.html[doc.lot.show XSL

@@ -35,6 +62,23 @@ option, for example:
   $ a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt

 

 

+== 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'.

+Here's how:

+

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

+- Or by setting `pageunits=pt` in a configuration file

+  `[miscellaneous]` section.

+- Or by setting this AttributeEntry in your document:

+

+  :miscellaneous.pageunits: pt

+

+See the

+http://www.methods.co.nz/asciidoc/userguide.html#X89[DocBook table

+widths] sidebar in the 'AsciiDoc User Guide' for an explanation.

+

+

 == How can I stop the document title being displayed?

 You could simply omit the document title, but this will result in a

 blank 'title' element in HTML outputs. If you want the HTML 'title'

@@ -86,23 +130,6 @@ name, 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'.

-Here's how:

-

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

-- Or by setting `pageunits=pt` in a configuration file

-  `[miscellaneous]` section.

-- Or by setting this AttributeEntry in your document:

-

-  :miscellaneous.pageunits: pt

-

-See the

-http://www.methods.co.nz/asciidoc/userguide.html#X89[DocBook table

-widths] sidebar in the 'AsciiDoc User Guide' for an explanation.

-

-

 == How can I insert XML processing instructions into output documents?

 Use an inline or block passthrough macros. This example inserts

 `<?dblatex bgcolor="#cceeff"?>` into the DocBook output generated by

@@ -849,18 +876,6 @@ and set the attribute `depth=1` instead, for example:
 ................................................

 

 

-== How can I customize PDF files generated by dblatex?

-

-There are a number of dblatex XSL parameters that can be used to

-customize PDF output. You can set them globally in the AsciiDoc

-`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also

-pass them on the a2x(1) command-line, for example:

-

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

-

-See also the http://dblatex.sourceforge.net/[dblatex] documentation.

-

-

 == How can I make the mailto macro work with multiple email addresses?

 

 For the AsciiDoc 'mailto' macro to work with multiple email addresses

diff --git a/examples/website/asciidoc-website.dict b/examples/website/asciidoc-website.dict
index 1617b9f..6855fe5 100644
--- a/examples/website/asciidoc-website.dict
+++ b/examples/website/asciidoc-website.dict
@@ -1,9 +1,10 @@
-personal_ws-1.1 en 198 
+personal_ws-1.1 en 201 
 O'Reilly
 awb
 Blogpost
 Bulleted
 Iisaka
+pygmentize
 callouts
 JavaScript
 asciimath
@@ -20,8 +21,8 @@ AsciiMathML
 asciimathml
 faq
 Efros
-LinuxDoc
 stdin
+LinuxDoc
 Klum
 CentOS
 src
@@ -133,6 +134,7 @@ AsciiDocGen
 CRAN
 jw
 ln
+pygments
 odf
 lt
 monospace
@@ -164,6 +166,7 @@ Obenhuber's
 CHANGLOG
 docbook
 DocBook
+fontlocking
 Rosenkraenzer
 toolchain
 ebuild
diff --git a/examples/website/source-highlight-filter.txt b/examples/website/source-highlight-filter.txt
index eb67d23..7ec24be 120000..100644
--- a/examples/website/source-highlight-filter.txt
+++ b/examples/website/source-highlight-filter.txt
@@ -1 +1,202 @@
-../../doc/source-highlight-filter.txt
\ No newline at end of file
+Source Code Highlight Filter
+============================
+
+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 'xhtml11' 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`.
+
+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.
+
+
+Examples
+--------
+Source code paragraphs
+~~~~~~~~~~~~~~~~~~~~~~
+The `source` paragraph style will highlight a paragraph of source
+code. These three code paragraphs:
+
+---------------------------------------------------------------------
+[source,python]
+if n < 0: print 'Hello World!'
+
+:language: python
+
+[source]
+if n < 0: print 'Hello World!'
+
+[source,ruby,numbered]
+[true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
+    puts "#{a.inspect} => #{b.inspect}"
+---------------------------------------------------------------------
+
+Render this highlighted source code:
+
+[source,python]
+if n < 0: print 'Hello World!'
+
+:language: python
+
+[source]
+if n < 0: print 'Hello World!'
+
+[source,ruby,numbered]
+[true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
+    puts "#{a.inspect} => #{b.inspect}"
+
+
+Unnumbered source code listing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This source-highlight filtered block:
+
+---------------------------------------------------------------------
+ [source,python]
+ ---------------------------------------------------------------------
+ ''' A multi-line
+     comment.'''
+ def sub_word(mo):
+     ''' Single line comment.'''
+     word = mo.group('word')   # Inline comment
+     if word in keywords[language]:
+         return quote + word + quote
+     else:
+         return word
+ ---------------------------------------------------------------------
+---------------------------------------------------------------------
+
+Renders this highlighted source code:
+
+[source,python]
+---------------------------------------------------------------------
+''' A multi-line
+    comment.'''
+def sub_word(mo):
+    ''' Single line comment.'''
+    word = mo.group('word')     # Inline comment
+    if word in keywords[language]:
+        return quote + word + quote
+    else:
+        return word
+---------------------------------------------------------------------
+
+Numbered source code listing with callouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This source-highlight filtered block:
+
+---------------------------------------------------------------------
+ [source,ruby,numbered]
+ ---------------------------------------------------------------------
+ #
+ # Useful Ruby base class extensions.
+ #
+
+ class Array
+
+   # Execute a block passing it corresponding items in
+   # +self+ and +other_array+.
+   # If self has less items than other_array it is repeated.
+
+   def cycle(other_array)  # :yields: item, other_item
+     other_array.each_with_index do |item, index|
+       yield(self[index % self.length], item)
+     end
+   end
+
+ end
+
+ if $0 == __FILE__                                 \<1>
+   # Array#cycle test
+   # true => 0
+   # false => 1
+   # true => 2
+   # false => 3
+   # true => 4
+   puts 'Array#cycle test'                         \<2>
+   [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
+     puts "#{a.inspect} => #{b.inspect}"
+   end
+ end
+ ---------------------------------------------------------------------
+
+ \<1> First callout.
+ \<2> Second callout.
+
+---------------------------------------------------------------------
+
+Renders this highlighted source code:
+
+[source,ruby,numbered]
+---------------------------------------------------------------------
+#
+# Useful Ruby base class extensions.
+#
+
+class Array
+
+  # Execute a block passing it corresponding items in
+  # +self+ and +other_array+.
+  # If self has less items than other_array it is repeated.
+
+  def cycle(other_array)  # :yields: item, other_item
+    other_array.each_with_index do |item, index|
+      yield(self[index % self.length], item)
+    end
+  end
+
+end
+
+if $0 == __FILE__                                 <1>
+  # Array#cycle test
+  # true => 0
+  # false => 1
+  # true => 2
+  # false => 3
+  # true => 4
+  puts 'Array#cycle test'                         <2>
+  [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
+    puts "#{a.inspect} => #{b.inspect}"
+  end
+end
+---------------------------------------------------------------------
+
+<1> First callout.
+<2> Second callout.
+
+
+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).
+
+DocBook
+~~~~~~~
+AsciiDoc encloses the source code in a DocBook 'programlisting'
+element and leaves source code highlighting to the DocBook toolchain
+(dblatex has a particularly nice programlisting highlighter). The
+DocBook programlisting element is assigned two attributes:
+
+. The 'language' attribute is set to the AsciiDoc 'language'
+  attribute.
+. The 'linenumbering' attribute is set to the AsciiDoc 'src_numbered'
+  attribute ('numbered' or 'unnumbered').
+
+Testing
+~~~~~~~
+Test the filter by converting the test file to HTML with AsciiDoc:
+
+  $ asciidoc -v ./filters/source/source-highlight-filter-test.txt
+  $ firefox ./filters/source/source-highlight-filter-test.html &