erbook 4.0.0 → 5.0.0

data/doc/manual.erb

@@ -1,4 +1,17 @@
 <%
+  ##
+  # Welcome to the source of the erbook user manual.
+  #
+  # The nodes in this file are hierarchically indented.  As a result, you must
+  # process this file using the "--unindent" option to obtain proper output:
+  #
+  #   erbook --unindent xhtml manual.erb > manual.xhtml
+  #
+  # Notice the '.xhtml' file extension in the output file name.  Without that,
+  # most web browsers will not display the embedded graphics in the output file.
+  #
+  ##
+
   # local variables for this document
   pkg_url = File.join(ERBook::WEBSITE, 'pkg')
   src_url = File.join(ERBook::WEBSITE, 'src')
@@ -6,28 +19,25 @@
   dev_url = File.join(ERBook::WEBSITE, 'dev')
   log_url = File.join(ERBook::WEBSITE, 'log')
 
-  # parameters for the HTML format
+  # parameters for the XHTML format
   $title   = "#{ERBook::DISPLAY} user manual"
   $authors = { 'Suraj N. Kurapati' => 'http://snk.tuxfamily.org' }
   $feeds   = { ann_url => :rss }
-  $logo    = '![erbook logo](erbook.png)'.to_html
+  $logo    = '![erbook logo](erbook.png)'.to_xhtml
 
   def introduction
-    %{erbook is an extensible document processor that emits #{ xref 'html', "HTML (web page)" }, #{ xref 'latex', "LaTeX (PDF)" }, #{ xref "man", "man (UNIX manual page)" }, #{ xref 'text', 'plain text' }, and #{ xref "HelloWorld", "any document format you can imagine" } from [eRuby templates](http://en.wikipedia.org/wiki/ERuby) that allow scripting and dynamic content generation.}
+    %{erbook is an extensible document processor that emits #{ xref 'xhtml', "XHTML (web page)" }, #{ xref 'latex', "LaTeX (PDF)" }, #{ xref "man", "man (UNIX manual page)" }, #{ xref 'text', 'plain text' }, and #{ xref "HelloWorld", "any document format you can imagine" } from [eRuby templates](http://en.wikipedia.org/wiki/ERuby) that allow scripting and dynamic content generation.}
   end
 %>
 
 <% abstract do %>
-  <%= introduction %>
-
-  <%= xref 'Introduction', '&rarr; Continue reading...' %>
-  {: style="text-align: center; font-size: larger" }
+  <%= introduction %> <span style="float: right; font-size: larger"><%= xref 'Introduction', 'Read more...' %></span>
 
   <% paragraph "Resources" do %>
-    * [Releases](<%= log_url %>) - release notes and project news. [![RSS feed](feed-icon-28x28.png)](<%= ann_url %>)
-    * [Downloads](<%= pkg_url %>) - obtain the newest release package.
-    * [Reference](api/index.html) - API documentation for source code.
-    * [Source code](<%= src_url %>) - obtain via [Git](http://git.or.cz) or browse online. [![RSS feed](feed-icon-28x28.png)](<%= dev_url %>)
+    * [Release notes](<%= log_url %>) --- news of project releases. [![RSS feed](feed-icon-28x28.png)](<%= ann_url %>)
+    * [Downloads](<%= pkg_url %>) --- obtain the newest release package.
+    * [Source code](<%= src_url %>) --- obtain via [Git](http://git.or.cz) or browse online. [![RSS feed](feed-icon-28x28.png)](<%= dev_url %>)
+    * [API reference](api/index.html) --- documentation for source code.
 
     To get help or provide feedback, simply <%= xref "License", "contact the author" %>.
   <% end %>
@@ -38,16 +48,11 @@
 
   <% note "See the source of this manual" do %>
     Did you know that this manual was generated by erbook? Here is [the source document](manual.erb) to prove it!
-
-    You may notice that the source document is hierarchically indented.  As a result, it must be processed with the <tt>--unindent</tt> option to produce proper output:
-
-        erbook --unindent html manual.erb
-
   <% end %>
 
   <% section "Relevance" do %>
     Unlike document processors such as [DocBook](http://www.docbook.org), [Deplate](http://deplate.sourceforge.net), and [SiSU](http://www.jus.uio.no/sisu/SiSU/), erbook is:
-    * *tiny* because its core contains less than 200 source lines of code
+    * *tiny* because its core contains less than 210 source lines of code
     * *extensible* because it lets you define <%= xref "HelloWorld", "your own custom document format" %>
 
     Unlike the documents of raw text processors such as [AsciiDoc](http://www.methods.co.nz/asciidoc/), [txt2tags](http://txt2tags.sourceforge.net), and [Grutatxt](http://www.triptico.com/software/grutatxt.html), erbook documents are *scriptable* eRuby templates, which means that you can inject arbitrary Ruby code into your documents for **dynamic content generation**.
@@ -124,15 +129,16 @@
   <% section "Requirements" do %>
     Your system needs the following software to run erbook.
 
-    | Software | Notes |
-    |----------|-------|
-    | [Ruby](http://ruby-lang.org) | Version 1.8.x is required. |
-    | [Maruku](http://maruku.rubyforge.org) | Required by the <%= xref 'html', "default HTML format" %>. |
-    | [CodeRay](http://coderay.rubychan.de) | Required by the <%= xref 'html', "default HTML format" %>. |
+    |                Software                 |        Description         |                            Notes                             |
+    |                --------                 |        -----------         |                            -----                             |
+    |      [Ruby](http://ruby-lang.org)       | Ruby language interpreter  |                  Version 1.8.x is required.                  |
+    |  [Maruku](http://maruku.rubyforge.org)  |     Markdown processor     | Required by the <%= xref 'xhtml', "default XHTML format" %>. |
+    |  [CodeRay](http://coderay.rubychan.de)  |     Syntax highlighter     | Required by the <%= xref 'xhtml', "default XHTML format" %>. |
+    | [Trollop](http://trollop.rubyforge.org) | Command-line option parser |             Required by the *erbook* executable.             |
 
     If your system has [RubyGems](http://rubygems.org), then you can install Maruku and CodeRay by running the following command:
 
-        gem install maruku coderay
+        gem install trollop maruku coderay
 
   <% end %>
 
@@ -151,7 +157,7 @@
             ruby bin/erbook -v
 
     If the installation was successful, then you will see output like this:
-    <pre><%=h `ruby bin/erbook -v` %></pre>
+    <pre><%= verbatim `ruby bin/erbook -v` %></pre>
 
     Otherwise, you can <%= xref "License", "contact the author" %> for help.
   <% end %>
@@ -177,7 +183,7 @@
 
       * <tt>erbook/</tt>
 
-        * <tt>html.rb</tt> --- provides methods (see <%= xref "Text to HTML conversion" %>) for the <%= xref 'html' %> format.
+        * <tt>to_xhtml.rb</tt> --- provides methods (see <%= xref "Text to XHTML conversion" %>) for the <%= xref 'xhtml' %> format.
 
         * <tt>rdoc.rb</tt> --- provides RDoc parse trees to Ruby code.
 
@@ -233,47 +239,63 @@
 
         <%%= node_type node_argument1, node_argument2, ... %>
 
-      Technically, nodes are Ruby method invocations composed of the following:
+    Alternatively, you may omit the leading "<" and trailing "%>" characters from an eRuby directive if the directive spans an _entire_ line.  So, the above examples become:
+
+        %% node_type node_argument1, node_argument2, ... do |node_object|
+          node_content
+        %% end
+
+    And:
+
+        %% node_type node_argument1, node_argument2, ... do
+          node_content
+        %% end
+
+    And:
+
+        %%= node_type node_argument1, node_argument2, ...
 
-    | Component | Description |
-    |-----------|-------------|
-    | `node_type`                           | name of the method being invoked                                                   |
-    | `node_argument1, node_argument2, ...` | arguments for the method invocation                                                |
-    | `node_content`                        | a block argument being passed to the method invocation                             |
-    | `node_object`                         | a `Node` object (see <%= xref "Node.class" %>) representing this method invocation |
+    Technically, nodes are Ruby method invocations composed of the following:
+
+    |               Component               |                                        Description                                         |
+    |               ---------               |                                        -----------                                         |
+    |              `node_type`              |                              name of the method being invoked                              |
+    | `node_argument1, node_argument2, ...` |                            arguments for the method invocation                             |
+    |            `node_content`             |                   a block argument being passed to the method invocation                   |
+    |             `node_object`             | a `ERBook::Node` object (see <%= xref "Node.class" %>) representing this method invocation |
 
     A <%= xref 'SpecFile', 'format specification file' %> defines what types of nodes an input document may use.
 
-    <% section "The `Node` class", "Node.class" do %>
-      When erbook builds a document tree from the nodes in an input document, it stores information about these nodes into `Node` objects.  A `Node` object has the following properties (methods):
-
-      | Property | Type          | Description |
-      |----------|---------------|-------------|
-      | type       | `String`          | Name of the type of this node. |
-      | args       | `Array`           | Arguments passed to this node. |
-      | content    | `String`          | The block of text passed to this node. |
-      | output     | `String`          | Result of the node output template for the content of this node. |
-      | digest     | `String`          | A unique identifier for the content of this node. |
-      | trace      | `Array`           | A stack trace describing the location of this node in the input document. |
-      | index      | `String`          | A LaTeX-style section number for this node.  This property is only present if the **index** parameter is enabled in the definition of this type of node. |
-      | number     | `Integer`         | An order-of-occurrence number for this node.  This property is only present if the **number** parameter is enabled in the definition of this type of node. |
-      | depth      | `Integer`         | Distance from the root of the document tree to this node. |
-      | parent     | `Node`          | The `Node` object which contains this node. The value of this property will be `nil` if this node is a root of the document tree. |
-      | children   | `Array` of `Node` | List of child nodes from the document tree. |
-
-      Furthermore, the `Node` class is derived from [Ruby's `OpenStruct` class](http://www.ruby-doc.org/stdlib/libdoc/ostruct/rdoc/classes/OpenStruct.html), so you can define new properties for `Node` objects dynamically.
+    <% section "The `ERBook::Node` class", "Node.class" do %>
+      When erbook builds a document tree from the nodes in an input document, it stores information about these nodes into `ERBook::Node` objects.  A `ERBook::Node` object has the following properties (methods):
+
+      | Property |           Type            |                                                                        Description                                                                         |
+      | -------- |           ----            |                                                                        -----------                                                                         |
+      |   type   |         `String`          |                                                               Name of the type of this node.                                                               |
+      |   args   |          `Array`          |                                                               Arguments passed to this node.                                                               |
+      | content  |         `String`          |                                                           The block of text passed to this node.                                                           |
+      |  output  |         `String`          |                                              Result of the node output template for the content of this node.                                              |
+      |  digest  |         `String`          |                                                     A unique identifier for the content of this node.                                                      |
+      |  trace   |          `Array`          |                                         A stack trace describing the location of this node in the input document.                                          |
+      |  index   |         `String`          |  A LaTeX-style section number for this node.  This property is only present if the **index** parameter is enabled in the definition of this type of node.  |
+      |  number  |         `Integer`         | An order-of-occurrence number for this node.  This property is only present if the **number** parameter is enabled in the definition of this type of node. |
+      |  depth   |         `Integer`         |                                                 Distance from the root of the document tree to this node.                                                  |
+      |  parent  |      `ERBook::Node`       |         The `ERBook::Node` object which contains this node. The value of this property will be `nil` if this node is a root of the document tree.          |
+      | children | `Array` of `ERBook::Node` |                                                        List of child nodes from the document tree.                                                         |
+
+      Furthermore, the `ERBook::Node` class is derived from [Ruby's `OpenStruct` class](http://www.ruby-doc.org/stdlib/libdoc/ostruct/rdoc/classes/OpenStruct.html), so you can define new properties for `ERBook::Node` objects dynamically.
     <% end %>
   <% end %>
 
   <% section "Format specification file", 'SpecFile' do %>
     A format specification file is a plain-text file marked up in [YAML syntax](http://yaml4r.sourceforge.net/cookbook/). Through the following parameters, it defines (1) what types of nodes an input document may contain, (2) how the content of those nodes is transformed into output, and (3) how the processed document is transformed into the output document.
 
-    | Parameter | Type | Description |
-    |-------------|--------|---------------|
-    | desc        | `String` | A short description of the output format. |
-    | code        | `String` | Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main erbook executable, so any file-system or path-dependent portions of this source code should take appropriate precautions. |
-    | nodes       | Hash   | A listing of <%= xref "SpecFile.nodes", "node definitions" %>. |
-    | output      | `String` | An eRuby template for the final output document. See <%= xref "SpecFile.output" %>. |
+    | Parameter |   Type   |                                                                                                                    Description                                                                                                                     |
+    | --------- |   ----   |                                                                                                                    -----------                                                                                                                     |
+    |   desc    | `String` |                                                                                                     A short description of the output format.                                                                                                      |
+    |   code    | `String` | Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main erbook executable, so any file-system or path-dependent portions of this source code should take appropriate precautions. |
+    |   nodes   |   Hash   |                                                                                           A listing of <%= xref "SpecFile.nodes", "node definitions" %>.                                                                                           |
+    |  output   | `String` |                                                                                An eRuby template for the final output document. See <%= xref "SpecFile.output" %>.                                                                                 |
 
     <%
       # XXX: "declare" this local variable here (in the parent
@@ -285,12 +307,12 @@
     <% section "Node definition", "SpecFile.nodes" do %>
       A node definition is a mapping from a name (the "node type") to the following set of parameters:
 
-      | Parameter | Type  | Description |
-      |-----------|-------|-------------|
-      | index       | Boolean | Assign a LaTeX-style section number to this node? |
-      | number      | Boolean | Assign an order-of-occurrence number to this node? |
-      | silent      | Boolean | Suppress the output of this node? |
-      | output      | `String`  | An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>. |
+      | Parameter |   Type   |                                       Description                                        |
+      | --------- |   ----   |                                       -----------                                        |
+      |   index   | Boolean  |                    Assign a LaTeX-style section number to this node?                     |
+      |  number   | Boolean  |                    Assign an order-of-occurrence number to this node?                    |
+      |  silent   | Boolean  |                            Suppress the output of this node?                             |
+      |  output   | `String` | An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>. |
 
       You may define additional parameters in a node definition if you want.
 
@@ -299,20 +321,20 @@
 
         The following variables are available for use in this template:
 
-        | Variable | Type          | Description |
-        |----------|---------------|-------------|
-        | `@node`     | `Node`          | the node for which this template is being evaluated |
+        | Variable |           Type            |                                      Description                                       |
+        | -------- |           ----            |                                      -----------                                       |
+        | `@node`  |      `ERBook::Node`       |                  The node for which this template is being evaluated.                  |
         <%= common_template_vars = %{
-        | `@roots`     | `Array` of `Node` | All root nodes in the document tree. |
-        | `@nodes`     | `Array` of `Node` | All nodes in the document tree. |
-        | `@types`     | `Hash`            | Mapping from node type (`String`) to array of `Node` objects having that type. |
-        | `@spec`     | `Hash`            | Data from the format specification file. |
+        | `@roots` | `Array` of `ERBook::Node` |                          All root nodes in the document tree.                          |
+        | `@nodes` | `Array` of `ERBook::Node` |                            All nodes in the document tree.                             |
+        | `@types` |          `Hash`           | Mapping from node type (`String`) to array of `ERBook::Node` objects having that type. |
+        | `@spec`  |          `Hash`           |                        Data from the format specification file.                        |
 
         erbook also provides the following mappings inside the `@spec` variable:
 
-        | Expression   | Type | Description |
-        |--------------|------|-------------|
-        | `@spec[:name]` | `String` | Short-hand name of the current format. |
+        |   Expression   |   Type   |                  Description                   |
+        |   ----------   |   ----   |                  -----------                   |
+        | `@spec[:name]` | `String` |     Short-hand name of the current format.     |
         | `@spec[:file]` | `String` | Path of the current format specification file. |
         }.lstrip.gsub(/^ +/, '')
         %>
@@ -324,9 +346,9 @@
 
       The following variables are available for use in this template:
 
-      | Variable | Type | Description |
-      |-|-|-|
-      | `@content`   | `String` | Content of the processed document. |
+      |  Variable  |   Type   |            Description             |
+      |  --------  |   ----   |            -----------             |
+      | `@content` | `String` | Content of the processed document. |
       <%= common_template_vars %>
     <% end %>
 
@@ -350,11 +372,11 @@
       4.  Examine the <tt>HelloWorld.output</tt> file to your satisfaction!
 
       <% example "HelloWorld format specification file", "HelloWorld.spec" do %>
-        <code lang="rhtml"><%=h File.read('doc/HelloWorld.spec') %></code>
+        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code>
       <% end %>
 
       <% example "Input document for HelloWorld format", "HelloWorld.input" do %>
-        <code lang="rhtml"><%=h File.read('doc/HelloWorld.input') %></code>
+        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code>
       <% end %>
 
       <% example "Output of HelloWorld format", "HelloWorld.output" do %>
@@ -368,17 +390,31 @@
   <% section "Command-line invocation" do %>
     <%=
       `ruby bin/erbook -h`.
-      gsub(/^ {4}(\S+(?:, \S+)?) {4,}(.*)$/, "\\1\n: \\2\n"). # option listing
-      gsub(/-\w\b|--\w{2,}/, '<tt>\&</tt>').                  # option names
-      gsub(/^\S+?: */, "<b>\\&</b>\n").                       # section headings
-      sub(/^erbook \[.*/, '<pre>\&</pre>')
+      gsub(/^ +(.*?):(.*)$/, "\\1\n: \\2\n").   # option listing
+      gsub(/-\w\b|--\w{2,}/, '<tt>\&</tt>').    # option names
+      gsub(/^\S+?: */, "<b>\\&</b>\n").         # section headings
+      gsub(/^ *(erbook \[.*)/, '<pre>\1</pre>') # usage syntax
     %>
 
     <% paragraph "Command-line arguments" do %>
-      As the <tt>{Format|SpecFile}</tt> token in the usage syntax above denotes, erbook requires its first command-line argument to be either (1) the name of a predefined format or (2) the path to a <%= xref 'SpecFile', 'format specification file' %>.
+      The first command-line argument to erbook is either the name of a predefined format (FormatName) or the path to a <%= xref 'SpecFile', 'format specification file' %> (FormatFile).
 
       Predefined formats are simply short-hand names of format specification files located in the <tt>fmt/</tt> subdirectory of the erbook installation directory (see <%= xref "Manifest" %>).
     <% end %>
+
+    <% paragraph "Saving the output to a file" do %>
+      Simply redirect the standard ouput stream (STDOUT) to a file like this:
+
+          erbook > YOUR_PATH_HERE
+
+      In the above example, **YOUR\_PATH\_HERE** is the path of the file in which the output should be saved.
+
+      <% important "Save XHTML output as <tt>.xhtml</tt>" do %>
+        When you use the XHTML format, ensure that the file extension of your saved output document is either <tt>.xhtml</tt> or <tt>.xml</tt>. Alternatively, ensure that your saved output document is served to web browsers under the <tt>application/xhtml+xml</tt> mime type.
+
+        Otherwise, most web browsers _will not display_ the icons and graphics embedded in the saved XHTML output document because they will treat it as HTML instead of as XML.  See this [QuirksMode.org bug report](http://www.quirksmode.org/bugreports/archives/2005/02/custom_dtds_int_1.html) for details.
+      <% end %>
+    <% end %>
   <% end %>
 
   <% section "Including external documents", "include" do %>
@@ -403,35 +439,35 @@
 
   These formats are meant to serve as working examples. If you require more functionality from one of these formats, simply make a copy of the corresponding format specification file and edit the copy to suit your needs. If you would like to contribute or discuss your enhancements to these default formats, you can <%= xref "License", "contact the author" %>.
 
-  <% chapter "HTML", 'html' do %>
-    This format generates a _monolithic_ HTML document that allows users to easily search for a particular topic using nothing more than their web browser's built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.
+  <% chapter "XHTML (web page)", 'xhtml' do %>
+    This format generates a _monolithic_ XHTML document that allows users to easily search for a particular topic using nothing more than their web browser's built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.
 
-    In the HTML document, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate the HTML document, especially for users of text-only web browsers.
+    In the XHTML document, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate the XHTML document, especially for users of text-only web browsers.
 
-    Furthermore, the HTML document comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the [Mozilla](http://mozilla.org) and [Opera](http://www.opera.com/) family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the "print preview" function of a graphical web browser to see how the HTML document will appear when printed.
+    Furthermore, the XHTML document comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the [Mozilla](http://mozilla.org) and [Opera](http://www.opera.com/) family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the "print preview" function of a graphical web browser to see how the XHTML document will appear when printed.
 
-    <% section "Text to HTML conversion" do %>
-      Inside the <tt>fmt/</tt> subdirectory of the erbook installation directory (see <%= xref "Manifest" %>), you will see a <tt>html.rb</tt> file. This file defines methods that transform text in an input document into HTML:
+    <% section "Text to XHTML conversion" do %>
+      The <tt>lib/erbook/to_xhtml.rb</tt> file inside erbook's installation directory (see <%= xref "Manifest" %>) defines the following methods:
 
-      * `String#to_html` - Transforms this string into HTML while ensuring that the result contains one or more block-level elements at the root.
+      * `String#to_xhtml` - Transforms this string into XHTML while ensuring that the result contains one or more block-level elements at the root.
 
-      * `String.to_inline_html` - Transforms this string into an *inline* HTML string (one that does not contain any block-level HTML elements at the root).
+      * `String.to_inline_xhtml` - Transforms this string into an *inline* XHTML string (one that does not contain any block-level XHTML elements at the root).
 
-      The default implementation of the `String#to_html` method employs the [Markdown](http://daringfireball.net/projects/markdown/) markup system. If you do not like Markdown or wish to use a different markup system for text in your documents, then simply edit the <tt>html.rb</tt> file and adjust the source code of the default `String#to_html` and `String.to_inline_html` methods accordingly.
+      The default implementation of the `String#to_xhtml` method employs the [Markdown](http://daringfireball.net/projects/markdown/) markup system. If you do not like Markdown or wish to use a different markup system for text in your documents, then simply edit the <tt>to_xhtml.rb</tt> file and adjust the source code of the default `String#to_xhtml` and `String.to_inline_xhtml` methods accordingly.
 
-      For example, if you replace the entire <tt>html.rb</tt> file with the following code, then the output of all nodes will appear within red boxes in the final output document.
+      For example, if you replace the entire <tt>to_xhtml.rb</tt> file with the following code, then the output of all nodes will appear within red boxes in the final output document.
 
       <code>
       class String
-        # Transforms this string into HTML while ensuring that the
+        # Transforms this string into XHTML while ensuring that the
         # result contains one or more block-level elements at the root.
-        def to_html
+        def to_xhtml
           '<p style="border: thin solid red">' + self + '</p>'
         end
 
-        # Transforms this string into an *inline* HTML string (one that
-        # does not contain any block-level HTML elements at the root).
-        def to_inline_html
+        # Transforms this string into an *inline* XHTML string (one that
+        # does not contain any block-level XHTML elements at the root).
+        def to_inline_xhtml
           self
         end
       end
@@ -476,15 +512,15 @@
 
           For example, here is some source code _without_ the `lang` attribute:
 
-          <code><%=h sampleCode %></code>
+          <code><%= verbatim sampleCode %></code>
 
           And here is the same source code with a `lang="c"` attribute:
 
-          <code lang="c"><%=h sampleCode %></code>
+          <code lang="c"><%= verbatim sampleCode %></code>
 
           And here is the same source code with a `lang="html"` attribute:
 
-          <code lang="html"><%=h sampleCode %></code>
+          <code lang="html"><%= verbatim sampleCode %></code>
         <% end %>
       <% end %>
 
@@ -497,25 +533,24 @@
       <% end %>
 
       <% section "Protecting verbatim text" do %>
-        Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process . In such cases, you can wrap the text you want to proctect within **&lt;noformat&gt;** and **&lt;/noformat&gt;** tags.
+        Sometimes you just need to protect some text from being mangled by the text-to-XHTML conversion process . In such cases, you can wrap the text you want to proctect within **&lt;noformat&gt;** and **&lt;/noformat&gt;** tags.
       <% end %>
     <% end %>
 
     <% section "Parameters" do %>
-      The HTML format accepts the following document parameters.
-
-      | Parameter   | Type  | Default value | Description |
-      |-|-|-|-|
-      | `$title`      | `String`  | `"$title"`                               | Title of the document. |
-      | `$authors`    | `Hash`    | `{"$authors" => nil}`                    | A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided `String#to_html_entities` method like this: `{ "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_html_entities }` |
-      | `$date`       | `String`  | `Time.now.strftime("%d %B %Y")`          | Date when the document was written. |
-      | `$logo`       | `String`  | `nil`                                    | Arbitrary content that goes above the document title in the default header. |
-      | `$feeds`      | `Hash`    | `nil`                                    | A mapping of feed URL to feed format. Here is an example: <code>$feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" }</code>|
-      | `$use_icons`  | Boolean | `true`                                   | Use [Tango icons](http://tango.freedesktop.org/Tango_Icon_Library) in admonitions (see <%= xref "Admonition nodes" %>)? |
+      The XHTML format accepts the following document parameters.
+
+      |  Parameter   |   Type   |          Default value          |                                                                                                  Description                                                                                                  |
+      |  ---------   |   ----   |          -------------          |                                                                                                  -----------                                                                                                  |
+      |   `$title`   | `String` |           `"$title"`            |                                                                                            Title of the document.                                                                                             |
+      |  `$authors`  |  `Hash`  |      `{"$authors" => nil}`      | A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided `String#to_xml_entities` method like this: `{ "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_xml_entities }` |
+      |   `$date`    | `String` | `Time.now.strftime("%d %B %Y")` |                                                                                      Date when the document was written.                                                                                      |
+      |   `$logo`    | `String` |              `nil`              |                                                                  Arbitrary content that goes above the document title in the default header.                                                                  |
+      |   `$feeds`   |  `Hash`  |              `nil`              |                                 A mapping of feed URL to feed format. Here is an example: <code>$feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" }</code>                                  |
     <% end %>
 
     <% section "Methods" do %>
-      The HTML format provides the following methods. In the method declarations shown below,
+      The XHTML format provides the following methods. In the method declarations shown below,
       * a pound sign (#) indicates that the method is an *instance method*, meaning that it can only be invoked on instances of a class, not on the classes themselves.
       * a double colon sign (::) indicates that the method is a *class method*, meaning that it can only be invoked on a class.
 
@@ -524,7 +559,7 @@
         require 'erbook/rdoc'
 
         RDoc::TopLevel.parse @spec['code']
-        RDoc::TopLevel.parse_file 'lib/erbook/html.rb'
+        RDoc::TopLevel.parse_file 'lib/erbook/to_xhtml.rb'
         RDoc::TopLevel.all_methods.each do |m|
           section "`#{m.decl}`" do
             m.comment_html
@@ -533,36 +568,36 @@
       %>
     <% end %>
 
-    <% chapter "Nodes", "html.nodes" do %>
-      Unless otherwise noted, all nodes defined by the HTML format accept two arguments, in this order:
+    <% chapter "Nodes", "xhtml.nodes" do %>
+      Unless otherwise noted, all nodes defined by the XHTML format accept two arguments, in this order:
       1.  a required *title* for the node
       2.  an optional *unique identifier* for the node
 
-      The second argument is used by the cross-referencing nodes (see <%= xref "html.nodes.xref" %> and <%= xref "html.nodes.cite" %>), which allow you to refer to another node in the document by its unique identifier.
+      The second argument is used by the cross-referencing nodes (see <%= xref "xhtml.nodes.xref" %> and <%= xref "xhtml.nodes.cite" %>), which allow you to refer to another node in the document by its unique identifier.
 
-      Furthermore, <%= xref "SpecFile.nodes", "node definitions" %> in the HTML format have two additional parameters:
+      Furthermore, <%= xref "SpecFile.nodes", "node definitions" %> in the XHTML format have two additional parameters:
 
-      | Parameter | Type  | Description |
-      |-|-|-|
-      | toc         | Boolean | Include this node in the **Table of Contents** (TOC)? |
-      | lof         | Boolean | Include this node in the **List of Figures** (LOF)? |
+      | Parameter |  Type   |                      Description                      |
+      | --------- |  ----   |                      -----------                      |
+      |    toc    | Boolean | Include this node in the **Table of Contents** (TOC)? |
+      |    lof    | Boolean |  Include this node in the **List of Figures** (LOF)?  |
 
       <% section "Structural nodes" do %>
         The nodes described in this section form the overall structure of the output document.
 
-        <% section "header", "html.nodes.header" do %>
+        <% section "header", "xhtml.nodes.header" do %>
           This node overrides the logo, title, list of authors, and date when the document was written, all of which are shown at the top of the document.
         <% end %>
 
-        <% section "footer", "html.nodes.footer" do %>
+        <% section "footer", "xhtml.nodes.footer" do %>
           This node overrides (1) the date when this document was generated and (2) the hyperlink to the erbook website, shown at the bottom of the document. The hyperlink is there as a way of saying thanks for erbook, the _wonderful_ little utility you have grown so fond of! ;-)
         <% end %>
 
-        <% section "abstract", "html.nodes.abstract" do %>
+        <% section "abstract", "xhtml.nodes.abstract" do %>
           A summary of the entire document.  This is what most readers will _skim_ through, if you are lucky.  Alas, nobody reads entire documents these days! :-(
         <% end %>
 
-        <% section "xref", "html.nodes.xref" do %>
+        <% section "xref", "xhtml.nodes.xref" do %>
           A cross-reference; a hyperlink that takes you to any node in the document.
 
           The first argument of this node is either the unique identifier or the user-defined title of the node you wish to cross-reference. If no nodes in the document have the given identifier or user-defined title, then an error will be raised.
@@ -586,7 +621,7 @@
       <% section "Organizational nodes" do %>
         The nodes described in this section are meant to help organize the document's content logically.  Based on how deeply these nodes are nested in the document, their heading will be larger (shallow depth) or smaller (deep depth).
 
-        <% section "part", "html.nodes.part" do %>
+        <% section "part", "xhtml.nodes.part" do %>
           A collection of chapters.
 
           <% part "An example" do %>
@@ -594,7 +629,7 @@
           <% end %>
         <% end %>
 
-        <% section "chapter", "html.nodes.chapter" do %>
+        <% section "chapter", "xhtml.nodes.chapter" do %>
           A collection of sections.
 
           <% chapter "An example" do %>
@@ -602,7 +637,7 @@
           <% end %>
         <% end %>
 
-        <% section "section", "html.nodes.section" do %>
+        <% section "section", "xhtml.nodes.section" do %>
           A collection of paragraphs about a particular topic.
 
           <% section "An example" do %>
@@ -610,7 +645,7 @@
           <% end %>
         <% end %>
 
-        <% section "paragraph", "html.nodes.paragraph" do %>
+        <% section "paragraph", "xhtml.nodes.paragraph" do %>
           A collection of sentences about a particular idea.
 
           <% paragraph "An example" do %>
@@ -625,10 +660,10 @@
         I like to follow the KDE guidelines<%= cite "KDE.admonitions" %> when determining which admonition to use in my documents.
 
         <% reference "KDE.admonitions" do %>
-          L. Watts, "Admonitions: Tips, hints, and Warnings", in _The KDE DocBook Authors guide_, Chapter 13, \[Online document], 22 September 2004 (Revision 1.00.00), \[cited 8 December 2007], Available at <%= link 'http://l10n.kde.org/docs/markup/tips-hints-etc.html' %>
+          L. Watts, "Admonitions: Tips, hints, and Warnings", in _The KDE DocBook Authors guide_, Chapter 13, \[Online document], 22 September 2004 (Revision 1.00.00), \[cited 8 December 2007], Available at <%= hyperlink 'http://l10n.kde.org/docs/markup/tips-hints-etc.html' %>
         <% end %>
 
-        <% section "warning", "html.nodes.warning" do %>
+        <% section "warning", "xhtml.nodes.warning" do %>
           Use a **warning** node when "data loss could occur if you follow the procedure being described." <%= cite "KDE.admonitions" %>
 
           <% warning "An example" do %>
@@ -636,7 +671,7 @@
           <% end %>
         <% end %>
 
-        <% section "caution", "html.nodes.caution" do %>
+        <% section "caution", "xhtml.nodes.caution" do %>
           bq. A note of caution. Use this for example when the reader may lose easily recovered or replaceable information (e.g. user settings), or when they could cause data loss if they don't correctly follow the procedure being outlined. <%= cite "KDE.admonitions" %>
 
           <% caution "An example" do %>
@@ -644,7 +679,7 @@
           <% end %>
         <% end %>
 
-        <% section "important", "html.nodes.important" do %>
+        <% section "important", "xhtml.nodes.important" do %>
           Use an **important** node when:
 
           bq. When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn't immediately obvious (e.g. when changing the font for one instance of a program also changes the default setting, and this isn't clear from the GUI.) <%= cite "KDE.admonitions" %>
@@ -654,7 +689,7 @@
           <% end %>
         <% end %>
 
-        <% section "note", "html.nodes.note" do %>
+        <% section "note", "xhtml.nodes.note" do %>
           Use a **note** node to convey:
 
           bq. Information the user should be aware of, but is peripheral to the actual task being described. <%= cite "KDE.admonitions" %>
@@ -664,7 +699,7 @@
           <% end %>
         <% end %>
 
-        <% section "tip", "html.nodes.tip" do %>
+        <% section "tip", "xhtml.nodes.tip" do %>
           Use a **tip** node when:
 
           bq. When you're giving a hint to make things easier or more productive for the reader. <%= cite "KDE.admonitions" %>
@@ -676,7 +711,7 @@
       <% end %>
 
       <% section "Auxilary materials" do %>
-        <% section "figure", "html.nodes.figure" do %>
+        <% section "figure", "xhtml.nodes.figure" do %>
           A diagram, sketch, image, or illustration; something that visually depicts an idea or thought.
 
           <% figure "An example" do %>
@@ -684,7 +719,7 @@
           <% end %>
         <% end %>
 
-        <% section "table", "html.nodes.table" do %>
+        <% section "table", "xhtml.nodes.table" do %>
           Information (typically measurement data) represented in tabular form for easy reading, comparison, and analysis.
 
           <% table "An example" do %>
@@ -692,7 +727,7 @@
           <% end %>
         <% end %>
 
-        <% section "example", "html.nodes.example" do %>
+        <% section "example", "xhtml.nodes.example" do %>
           A sample application of an idea or thought.
 
           <% example "An example" do %>
@@ -700,7 +735,7 @@
           <% end %>
         <% end %>
 
-        <% section "equation", "html.nodes.equation" do %>
+        <% section "equation", "xhtml.nodes.equation" do %>
           A mathematical equation or formula.
 
           <% equation "An example" do %>
@@ -708,7 +743,7 @@
           <% end %>
         <% end %>
 
-        <% section "procedure", "html.nodes.procedure" do %>
+        <% section "procedure", "xhtml.nodes.procedure" do %>
           An outline; a series of steps outlining some kind of process.
 
           <% procedure "An example" do %>
@@ -720,50 +755,58 @@
       <% section "Bibliographical nodes" do %>
         The nodes in this section deal with attribution of ideas---an important weapon against plagiarism.
 
-        <% section "reference", "html.nodes.reference" do %>
+        <% section "reference", "xhtml.nodes.reference" do %>
           This node stores bibliography information about an information source that is relevant to your document.
 
-          If you wish to cite a certain source in several places in your document, start by creating a **reference** node first and then use a **cite** node (see <%= xref "html.nodes.cite" %>) to perform the citation.
+          If you wish to cite a certain source in several places in your document, start by creating a **reference** node first and then use a **cite** node (see <%= xref "xhtml.nodes.cite" %>) to perform the citation.
 
           <% paragraph "An example" do %>
-            See <%= xref 'html.nodes.reference.example' %> for an example of how a **reference** node appears.
+            See <%= xref 'xhtml.nodes.reference.example' %> for an example of how a **reference** node appears.
           <% end %>
 
-          <% reference 'html.nodes.reference.example' do %>
+          <% reference 'xhtml.nodes.reference.example' do %>
             This is how a **reference** node appears.
           <% end %>
         <% end %>
 
-        <% section "cite", "html.nodes.cite" do %>
-          A citation to a **reference** node (see <%= xref 'html.nodes.reference' %>) in the document's bibliography.
+        <% section "cite", "xhtml.nodes.cite" do %>
+          A citation to a **reference** node (see <%= xref 'xhtml.nodes.reference' %>) in the document's bibliography.
 
           The first argument of this node is the unique identifier of the reference node you wish to cite. You can specify additional arguments to give more detail about the citation.
 
           For example, this node in the input document:
 
-              <%%= cite "html.nodes.reference.example" %>
+              <%%= cite "xhtml.nodes.reference.example" %>
 
-          appears in the output document like this: <%= cite "html.nodes.reference.example" %>
+          appears in the output document like this: <%= cite "xhtml.nodes.reference.example" %>
 
           As another example, this node in the input document:
 
-              <%%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>
+              <%%= cite "xhtml.nodes.reference.example", "chapter 10", "page 53", "..." %>
 
-          appears in the output document like this: <%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>
+          appears in the output document like this: <%= cite "xhtml.nodes.reference.example", "chapter 10", "page 53", "..." %>
         <% end %>
       <% end %>
     <% end %>
   <% end %>
 
+  <% patches_are_welcome = "This format is not yet implemented.  I will do this evenually, but until then, **patches are welcome!** :-)" %>
+
   <% chapter "Plain text", 'text' do %>
-    [This format is not yet implemented.](http://en.wikipedia.org/wiki/Plain_text)
+    <%= patches_are_welcome %>
+
+    <%= hyperlink 'http://en.wikipedia.org/wiki/Plain_text' %>
   <% end %>
 
-  <% chapter "LaTeX", 'latex' do %>
-    [This format is not yet implemented.](http://www.latex-project.org)
+  <% chapter "LaTeX (PDF)", 'latex' do %>
+    <%= patches_are_welcome %>
+
+    <%= hyperlink 'http://www.latex-project.org' %>
   <% end %>
 
-  <% chapter "UNIX man page", 'man' do %>
-    [This format is not yet implemented.](http://en.wikipedia.org/wiki/Man_page)
+  <% chapter "man (UNIX manual page)", 'man' do %>
+    <%= patches_are_welcome %>
+
+    <%= hyperlink 'http://en.wikipedia.org/wiki/Man_page' %>
   <% end %>
 <% end %>