Website and documentation updates.

6 files changed, 91 insertions, 36 deletions

diff --git a/INSTALL.txt b/INSTALL.txt
index 6783f91..8c1cc1f 100644
--- a/INSTALL.txt
+++ b/INSTALL.txt
@@ -121,6 +121,14 @@ This will create the folder +asciidoc-{revnumber}+ containing the
 `asciidoc.py` and `a2x.py` executables along with configuration files
 and documentation.
 
+To generate DocBook based outputs (e.g. PDFs) you will also need a
+working DocBook toolchain. Installing and configuring a DocBook
+toolchain on Windows can be a challenge -- this blog post explains
+http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How
+to Create Handsome PDF Documents Without Frustration] using
+http://www.cygwin.com/[Cygwin],
+http://dblatex.sourceforge.net/[dblatex] and AsciiDoc.
+
 
 Testing your installation
 -------------------------
diff --git a/doc/asciidoc.dict b/doc/asciidoc.dict
index 04e4c26..ab8e99e 100644
--- a/doc/asciidoc.dict
+++ b/doc/asciidoc.dict
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 981 
+personal_ws-1.1 en 983 
 mandoc
 colspecs
 API
@@ -378,6 +378,7 @@ subprocess
 outfile
 blandit
 revisionhistory
+EPUBReader
 params
 undefines
 Andrés
@@ -907,6 +908,7 @@ BufRead
 specialwords
 libexslt
 subsnormal
+fxhtml
 Builtin
 hardcoded
 Mery
diff --git a/doc/faq.txt b/doc/faq.txt
index 3ea3b72..897aef9 100644
--- a/doc/faq.txt
+++ b/doc/faq.txt
@@ -12,9 +12,9 @@ AsciiDoc Frequently Asked Questions
 == Can AsciiDoc generate slide shows?

 There are a number of browser based HTML slideshow applications

 written in JavaScript, most could probably be made to work with

-AsciiDoc. Here's how use http://staticfree.info/projects/jqs5/[JQS5]

-to turn an AsciiDoc document (`mydoc.txt`) into a slideshow

-(`mydoc.html`):

+AsciiDoc. Here's how to use

+http://staticfree.info/projects/jqs5/[JQS5] to turn an AsciiDoc

+document (`mydoc.txt`) into a slideshow (`mydoc.html`):

 

 . Download and extract the 'JQS5' tarball.

 . Put this your document's link:userguide.html#X87[docinfo file]

diff --git a/doc/publishing-ebooks-with-asciidoc.txt b/doc/publishing-ebooks-with-asciidoc.txt
index 4d879fd..8cfc663 100644
--- a/doc/publishing-ebooks-with-asciidoc.txt
+++ b/doc/publishing-ebooks-with-asciidoc.txt
@@ -1,6 +1,7 @@
 Publishing eBooks with AsciiDoc
 ===============================
 
+ifdef::backend-wordpress[]
 // Use the same article for both a blog post and on the AsciiDoc
 // website.
 :blogpost-title: Publishing eBooks with AsciiDoc
@@ -9,16 +10,23 @@ Publishing eBooks with AsciiDoc
 :blogpost-posttype: post
 :blogpost-categories: AsciiDoc,eBook,EPUB,DocBook
 
-{backend-wordpress}*Published*: 2010-08-10
+*Published*: 2010-08-23
+endif::backend-wordpress[]
 
 It's easy to write and publish books in
 http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF formats using
 http://www.methods.co.nz/asciidoc/[AsciiDoc].
-
-Here are three examples: The first is a minimal example introducing
-the AsciiDoc format, the second ('The Brothers Karamazov') is a rather
-long multi-part book and the third ('The Adventures of Sherlock
-Holmes') includes a front cover image and customized page styling.
+ifdef::backend-wordpress[]
+This article was originally published on the
+http://www.methods.co.nz/asciidoc/publishing-ebooks-with-asciidoc.html[AsciiDoc
+website].
+endif::backend-wordpress[]
+
+Here are three examples: The first is a <<X1,minimal example>>
+introducing the AsciiDoc format, the second <<X2,The Brothers
+Karamazov>> is a rather long multi-part book and the third <<X3,The
+Adventures of Sherlock Holmes>> includes a front cover image and
+customized page styling.
 
 // Wordpress processing instruction.
 pass::[<!--more-->]
@@ -27,7 +35,14 @@ The examples presented below were created on a PC running Xubuntu
 Linux 10.04 but should be applicable to any UNIX-based operating
 system.
 
+NOTE: A number of 'asciidoc' and 'a2x' features used in this article
+require AsciiDoc version 8.6.1 -- install version 8.6.1 or better to
+compile the examples. The version of
+http://wiki.docbook.org/topic/DocBookXslStylesheets[DocBook XSL
+Stylesheets] used was 1.75.2.
+
 
+[[X1]]
 == Minimal Book
 This didactic example contains a title and two chapters.  The AsciiDoc
 source is a plain text file named `minimal-book.txt`:
@@ -70,13 +85,33 @@ http://dblatex.sourceforge.net/[dblatex] use:
 
   a2x -fpdf -dbook --fop minimal-book.txt
 
-NOTE: A number of 'asciidoc' and 'a2x' features used in this article
-require AsciiDoc version 8.6.1 -- install version 8.6.1 or better to
-compile the examples. The version of
-http://wiki.docbook.org/topic/DocBookXslStylesheets[DocBook XSL
-Stylesheets] used was 1.75.2.
+You can also generate an HTML formatted book, either using DocBook XSL
+Stylesheets:
+
+  a2x -fxhtml -dbook minimal-book.txt
+
+or directly using the 'asciidoc' command:
+
+  asciidoc -dbook minimal-book.txt
+
+[NOTE]
+======
+The http://www.methods.co.nz/asciidoc/a2x.1.html[a2x toolchain
+wrapper] uses the following programs (most will be available
+prepackaged for your Linux distribution):
+
+- http://xmlsoft.org/XSLT/[xsltproc]
+- http://docbook.sourceforge.net/projects/xsl/[DocBook XSL
+  Stylesheets]
+- http://dblatex.sourceforge.net/[dblatex] (PDF file generator)
+- http://xmlgraphics.apache.org/fop/[FOP] (alternative PDF file
+  generator)
+- http://code.google.com/p/epubcheck/[epubcheck] (optional EPUB file
+  validator)
+======
 
 
+[[X2]]
 The Brothers Karamazov
 ----------------------
 'The Brothers Karamazov' is an example of a multi-part book. To
@@ -192,6 +227,7 @@ Alexey Fyodorovitch Karamazov was the third son of Fyodor Pavlovitch
     entries].
 
 
+[[X3]]
 The Adventures of Sherlock Holmes
 ---------------------------------
 This book includes a front cover image and a customized page design.
@@ -214,9 +250,8 @@ this command:
 
 |====================================================================
 
-Here's a screenshot of the first page of the first chapter (rendered by
-the https://addons.mozilla.org/en-US/firefox/addon/45281/[Firefox
-PUBReader addon]):
+Here's a screenshot of the first page of the first chapter (rendered
+by the http://www.epubread.com/en/[Firefox EPUBReader addon]):
 
 image::images/epub.png[]
 
@@ -324,10 +359,9 @@ http://epubzengarden.com/[ePub Zen Garden].
 Reading EPUB documents
 ----------------------
 My current favorite software epub reader is the
-https://addons.mozilla.org/en-US/firefox/addon/45281/[Firefox
-PUBReader addon].  Browsers are a natural fit for EPUB (EPUB is just a
-bunch of zipped XHTML files) -- I'd like to see browsers support EPUB
-natively.
+http://www.epubread.com/en/[Firefox EPUBReader addon].  Browsers are a
+natural fit for EPUB (EPUB is just a bunch of zipped XHTML files) --
+I'd like to see browsers support EPUB natively.
 
 As of writing this article most eBook readers (with the notable
 exception of Amazon's Kindle) support the EPUB format.
diff --git a/doc/source-highlight-filter.txt b/doc/source-highlight-filter.txt
index 35aad77..1949ee4 100644
--- a/doc/source-highlight-filter.txt
+++ b/doc/source-highlight-filter.txt
@@ -2,11 +2,15 @@ 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.
+filter (`source-highlight-filter.conf`).
+
+
+HTML Outputs
+------------
+The highlighter uses http://www.gnu.org/software/src-highlite/[GNU
+source-highlight] to highlight 'html4' and 'xhtml11' outputs. You also
+have the option of using the http://pygments.org/[Pygments] syntax
+highlighter for 'xhtml11' outputs.
 
 To use Pygments you need to define an AsciiDoc attribute named
 'pygments' (either from the command-line or in the global
@@ -16,20 +20,18 @@ customize Pygments CSS styles by editing `./stylesheets/pygments.css`.
 To make Pygments your default highlighter put the following line your
 `~/.asciidoc/asciidoc.conf` file:
 
+  pygments=
+
+
+DocBook Outputs
+---------------
 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.
-- You may need to place callout markers inside source code comments to
-  ensure they are not misinterpreted and mangled by the highlighter.
-=====
 
 Examples
 --------
+
 Source code paragraphs
 ~~~~~~~~~~~~~~~~~~~~~~
 The `source` paragraph style will highlight a paragraph of source
@@ -181,6 +183,15 @@ end
 <1> First callout.
 <2> Second callout.
 
+[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 misinterpreted and mangled by the highlighter.
+=====
+
 
 Installation
 ------------
diff --git a/examples/website/index.txt b/examples/website/index.txt
index e36cf48..cabc238 100644
--- a/examples/website/index.txt
+++ b/examples/website/index.txt
@@ -10,7 +10,7 @@ This release follows hard on the heels of 8.6.0, it includes:
   been simplified and generalized (this change is not backward

   compatible).

 - A cover image and customized page design have been added to the

-  link:publishing-ebooks-with-asciidoc.html#_the_adventures_of_sherlock_holmes[Sherlock

+  link:publishing-ebooks-with-asciidoc.html#X3[Sherlock

   Holmes example eBook] on the

   link:publishing-ebooks-with-asciidoc.html[publishing eBooks with

   AsciiDoc] web page.