erbook 5.0.0 → 6.0.0

data/doc/manual.erb

@@ -1,812 +0,0 @@
-<%
-  ##
-  # 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')
-  ann_url = File.join(ERBook::WEBSITE, 'ann')
-  dev_url = File.join(ERBook::WEBSITE, 'dev')
-  log_url = File.join(ERBook::WEBSITE, 'log')
-
-  # 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_xhtml
-
-  def introduction
-    %{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 %> <span style="float: right; font-size: larger"><%= xref 'Introduction', 'Read more...' %></span>
-
-  <% paragraph "Resources" do %>
-    * [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 %>
-<% end %>
-
-<% chapter "Introduction" do %>
-  <%= introduction %>
-
-  <% 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!
-  <% 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 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**.
-
-    <% section "Reviews" do %>
-      Vitor Peres in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283052):
-
-      > I actually felt like printing \[this manual], because it's just so well-thought typographically... Even if \[erbook] weren't great by itself, I'd feel good just looking at the manual.
-
-
-      Ara T. Howard in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/282949):
-
-      > \[this manual is] a insanely complete and nice looking bit of documentation \[... erbook] looks like a great project
-
-
-      Martin DeMello in [ruby-talk](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283304):
-
-      > Very nice work indeed!
-    <% end %>
-  <% end %>
-
-  <% section "Logistics" do %>
-    erbook is <%= xref "License", "open source software" %> so feel free to contribute your improvements and discuss your ideas <%= xref "License", "with the author" %>. You can obtain the source code from [this source repository](<%= src_url %>) and monitor for changes by subscribing to [this news feed](<%= dev_url %>).
-
-    <% section "Credits" do %>
-      <%= File.read 'doc/README' %>
-    <% end %>
-
-    <% section "License" do %>
-      <%= File.read 'LICENSE' %>
-    <% end %>
-
-    <% section 'Version numbers' do %>
-      erbook releases are numbered in *major.minor.patch* form, according to the [RubyGems rational versioning policy](http://www.rubygems.org/read/chapter/7) which can be [summarized](http://ablog.apress.com/?p=738) thus:
-
-      <table markdown="1">
-        <thead>
-          <tr>
-            <td rowspan="2">What increased in the version number? </td>
-            <td colspan="3">What does the increase signify about the release? </td>
-          </tr>
-          <tr>
-            <th>Backwards compatible? </th>
-            <th>New features? </th>
-            <th>Bug fixes? </th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <th>major </th>
-            <td style="background-color: #FFE4E1;">No </td>
-            <td>Yes </td>
-            <td>Yes </td>
-          </tr>
-          <tr>
-            <th>minor </th>
-            <td>Yes </td>
-            <td>Yes </td>
-            <td>Yes </td>
-          </tr>
-          <tr>
-            <th>patch </th>
-            <td>Yes </td>
-            <td style="background-color: #FFE4E1;">No </td>
-            <td>Yes </td>
-          </tr>
-        </tbody>
-      </table>
-    <% end %>
-  <% end %>
-<% end %>
-
-<% chapter "Setup" do %>
-  <% section "Requirements" do %>
-    Your system needs the following software to run erbook.
-
-    |                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 trollop maruku coderay
-
-  <% end %>
-
-  <% section "Installation" do %>
-    If your system has [RubyGems](http://rubygems.org), then you can install erbook by running the following commands:
-
-        gem install erbook
-        erbook -v
-
-    Otherwise, follow these instructions:
-
-    1.  Download the newest release package from [the download area](<%= pkg_url %>).
-    2.  Extract the release package somewhere on your system.
-    3.  Go inside the extracted directory and run the following command:
-
-            ruby bin/erbook -v
-
-    If the installation was successful, then you will see output like this:
-    <pre><%= verbatim `ruby bin/erbook -v` %></pre>
-
-    Otherwise, you can <%= xref "License", "contact the author" %> for help.
-  <% end %>
-
-  <% section "Manifest" do %>
-    You will see the following items inside erbook's installation directory, whose path you can determine by running this command:
-
-        erbook -v
-
-    * <tt>bin/</tt> --- contains executable programs.
-
-      * <tt>erbook</tt> --- core logic of erbook.
-
-    * <tt>fmt/</tt> --- contains the predefined set of <%= xref 'SpecFile', "format specification files" %>. If you ever need to install your custom format specification file globally, then put it inside this directory.
-
-    <% ERBook::FORMAT_FILES.each do |file| %>
-      * <tt><%= File.basename(file) %></tt> --- <%= YAML.load_file(file)['desc'] %>
-    <% end %>
-
-    * <tt>lib/</tt> --- erbook automatically adds this directory to Ruby's load path.
-
-      * <tt>erbook.rb</tt> --- project version information.
-
-      * <tt>erbook/</tt>
-
-        * <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.
-
-    * <tt>doc/</tt> --- contains this manual and other documentation.
-
-      * <tt>erbook.svg</tt> --- source file of the erbook logo.
-
-      * <tt>manual.erb</tt> --- source file of this manual.
-
-      * <tt>api/</tt> --- contains API reference documentation for the provided Ruby code.
-
-    * <tt>LICENSE</tt> --- project license and copyright notice.
-  <% end %>
-<% end %>
-
-<% chapter "Theory of operation" do %>
-  When you run erbook, it does the following:
-
-  1.  Loads the <%= xref "SpecFile", "format specification file" %>.
-
-  2.  Creates an **input document** by:
-
-      * Reading the input (the content of either the input file or the standard input stream) into memory.
-
-      * Evaluating <%= xref "include", "include directives" %> in the input.
-
-  3.  Transforms the input document into a **processed document** by:
-
-      * Building a **document tree** data structure from <%= xref "Nodes", "nodes" %> present in the input document.
-
-      * Replacing every node in the input document with the result of its <%= xref "SpecFile.nodes.output", "node output template" %>.
-
-  4.  Transforms the processed document into an **output document** according to the <%= xref "SpecFile.output", "document output template" %>.
-
-  5.  Prints the output document to the standard output stream.
-
-  Although there is only one document being processed here, we refer to it using three distinct terms: **input**, **processed**, and **output**; because the content of the document changes radically with every transformation.
-
-  <% section "Nodes" do %>
-    A node is a block of text that appears like this:
-
-        <%% node_type node_argument1, node_argument2, ... do |node_object| %>
-          node_content
-        <%% end %>
-
-    Or like this:
-
-        <%% node_type node_argument1, node_argument2, ... do %>
-          node_content
-        <%% end %>
-
-    Or like this:
-
-        <%%= node_type node_argument1, node_argument2, ... %>
-
-    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, ...
-
-    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 `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" %>.                                                                                 |
-
-    <%
-      # XXX: "declare" this local variable here (in the parent
-      #      scope) because it is initialized and used in two
-      #      different child scopes that exist at different depths
-      common_template_vars = nil
-    %>
-
-    <% 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" %>. |
-
-      You may define additional parameters in a node definition if you want.
-
-      <% section "Node output template", "SpecFile.nodes.output" do %>
-        A node output template (the **output** parameter in a node definition) is an eRuby template that transforms a node's content into output.  During the processing stage, erbook replaces all nodes in the input document with the result of this template _unless_ the **silent** parameter is enabled in this node's definition.
-
-        The following variables are available for use in this template:
-
-        | Variable |           Type            |                                      Description                                       |
-        | -------- |           ----            |                                      -----------                                       |
-        | `@node`  |      `ERBook::Node`       |                  The node for which this template is being evaluated.                  |
-        <%= common_template_vars = %{
-        | `@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.     |
-        | `@spec[:file]` | `String` | Path of the current format specification file. |
-        }.lstrip.gsub(/^ +/, '')
-        %>
-      <% end %>
-    <% end %>
-
-    <% section "Document output template", "SpecFile.output" do %>
-      A document output template (the **output** parameter in a format specification file) is an eRuby template that transforms a processed document into the final output document.
-
-      The following variables are available for use in this template:
-
-      |  Variable  |   Type   |            Description             |
-      |  --------  |   ----   |            -----------             |
-      | `@content` | `String` | Content of the processed document. |
-      <%= common_template_vars %>
-    <% end %>
-
-    <% section "Creating your own document format", "HelloWorld" do %>
-      Here is a working example to help you digest all that you've learned so far about format specification files. A few things to notice in this example are:
-
-      * We define a `generate_name()` method in <%= xref "HelloWorld.spec" %> and make use of it in the <%= xref "HelloWorld.input" %>. This shows how to provide format-specific functionality to an input document.
-
-      * We define a `$style` variable in <%= xref "HelloWorld.input" %> and make use of it in <%= xref "HelloWorld.spec" %>.  This shows how to pass parameters from an input document to your format specification file.
-
-      To run this example:
-
-      1.  Save the code shown in <%= xref "HelloWorld.spec" %> to a file named <tt>HelloWorld.spec</tt>
-
-      2.  Save the text shown in <%= xref "HelloWorld.input" %> to a file named <tt>HelloWorld.input</tt>
-
-      3.  Run this command:
-
-              erbook HelloWorld.spec HelloWorld.input > HelloWorld.output
-
-      4.  Examine the <tt>HelloWorld.output</tt> file to your satisfaction!
-
-      <% example "HelloWorld format specification file", "HelloWorld.spec" do %>
-        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code>
-      <% end %>
-
-      <% example "Input document for HelloWorld format", "HelloWorld.input" do %>
-        <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code>
-      <% end %>
-
-      <% example "Output of HelloWorld format", "HelloWorld.output" do %>
-        <%= `ruby bin/erbook -u doc/HelloWorld.spec doc/HelloWorld.input` %>
-      <% end %>
-    <% end %>
-  <% end %>
-<% end %>
-
-<% chapter "Usage" do %>
-  <% section "Command-line invocation" do %>
-    <%=
-      `ruby bin/erbook -h`.
-      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 %>
-      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 %>
-    The **include** directive allows you to insert the content of an arbitrary file at a certain place in the input document.  It is written like this:
-
-        <%%# include YOUR_PATH_HERE #%>
-
-    In the above example, **YOUR\_PATH\_HERE** is the path of the file whose content you wish to insert into the input document.
-
-    You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the **include** directive.
-  <% end %>
-
-  <% section "Unindenting nodes hierarchically" do %>
-    When writing erbook documents, I prefer to indent the content of nodes according to their depth (as can be seen in <%= xref "See the source of this manual", "the source of this manual" %>) because my [text editor of choice](http://jedit.org) automatically folds blocks of text based on indentation.
-
-    If you also prefer to write documents in this way, be sure to pass the <tt>--unindent</tt> option to **erbook** so that the indentation will not affect the resulting output.
-  <% end %>
-<% end %>
-
-<% part "Formats" do %>
-  This part describes the default formats provided along with erbook. The <%= xref "SpecFile", "format specification files" %> for these formats can be found in the <tt>fmt/</tt> directory of the erbook installation directory (see <%= xref "Manifest" %>).
-
-  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 "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 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 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 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_xhtml` - Transforms this string into XHTML while ensuring that the result contains one or more block-level 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_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>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 XHTML while ensuring that the
-        # result contains one or more block-level elements at the root.
-        def to_xhtml
-          '<p style="border: thin solid red">' + self + '</p>'
-        end
-
-        # 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
-      </code>
-
-      In addition to supporting Markdown syntax, the default implementation has some additional features which are described in the following subsections.
-
-      <% section "Syntax coloring for source code" do %>
-        Syntax coloring is _automatically added_ to source code found inside the **&lt;code&gt;** and **&lt;/code&gt;** HTML tags.  The syntax coloring library, [CodeRay](http://coderay.rubychan.de), currently supports the following programming languages:
-        * Ruby
-        * C
-        * Delphi
-        * HTML
-        * RHTML (Rails)
-        * Nitro-XHTML
-
-        <% section "Specifying the programming language" do %>
-          Because different programming languages have different syntax coloring schemes, you can specify the language of your source code using the `lang` attribute to ensure that only the appropriate coloring scheme is used. Note that unless the `lang` attribute is specified, _Ruby_ is assumed to be the programming language of all source code by default.
-
-          <% sampleCode = %q{
-          # Ruby ###########################
-          def hello
-            puts "Hello world!"
-          end
-
-
-          /* C ****************************/
-          #include <stdio.h>
-          int main(int argc, char **argv) {
-            printf("Hello world!\n");
-            return 0;
-          }
-
-
-          <!-- HTML ----------------------->
-          <html>
-            <body>
-              Hello world!
-            <body>
-          </html>
-          } %>
-
-          For example, here is some source code _without_ the `lang` attribute:
-
-          <code><%= verbatim sampleCode %></code>
-
-          And here is the same source code with a `lang="c"` attribute:
-
-          <code lang="c"><%= verbatim sampleCode %></code>
-
-          And here is the same source code with a `lang="html"` attribute:
-
-          <code lang="html"><%= verbatim sampleCode %></code>
-        <% end %>
-      <% end %>
-
-      <% section "Smart sizing of source code" do %>
-        Source code is _automatically sized_ to be displayed as either a line or paragraph of text, depending on whether it contains line breaks.
-
-        For example, here is a single line <code>life = true or false</code> of code. And here is a paragraph <code>life =
-        true or
-        false</code> of code.
-      <% end %>
-
-      <% section "Protecting verbatim text" do %>
-        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 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 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.
-
-      <%
-        # load library for parsing method documentation
-        require 'erbook/rdoc'
-
-        RDoc::TopLevel.parse @spec['code']
-        RDoc::TopLevel.parse_file 'lib/erbook/to_xhtml.rb'
-        RDoc::TopLevel.all_methods.each do |m|
-          section "`#{m.decl}`" do
-            m.comment_html
-          end
-        end
-      %>
-    <% end %>
-
-    <% 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 "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 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)?  |
-
-      <% section "Structural nodes" do %>
-        The nodes described in this section form the overall structure of the output document.
-
-        <% 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", "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", "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", "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.
-
-          The second argument of this node overrides the default link text of the cross-reference.
-
-          For example, this node in the input document:
-
-              <%%= xref "SpecFile" %>
-
-          appears in the output document like this: <%= xref "SpecFile" %>.
-
-          As another example, this node in the input document:
-
-              <%%= xref "SpecFile", "custom link text" %>
-
-          appears in the output document like this: <%= xref "SpecFile", "custom link text" %>.
-        <% end %>
-      <% end %>
-
-      <% 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", "xhtml.nodes.part" do %>
-          A collection of chapters.
-
-          <% part "An example" do %>
-            This is how a **part** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "chapter", "xhtml.nodes.chapter" do %>
-          A collection of sections.
-
-          <% chapter "An example" do %>
-            This is how a **chapter** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "section", "xhtml.nodes.section" do %>
-          A collection of paragraphs about a particular topic.
-
-          <% section "An example" do %>
-            This is how a **section** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "paragraph", "xhtml.nodes.paragraph" do %>
-          A collection of sentences about a particular idea.
-
-          <% paragraph "An example" do %>
-            This is how a **paragraph** node appears.  Notice that there is no LaTeX-style index number in the heading of this **paragraph** node.
-          <% end %>
-        <% end %>
-      <% end %>
-
-      <% section "Admonition nodes" do %>
-        An admonition is basically a box that is indented more deeply than the text surrounding it.  It is typically used to convey extraneous or pertinent information about the application of ideas discussed in the surrounding text.
-
-        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 <%= hyperlink 'http://l10n.kde.org/docs/markup/tips-hints-etc.html' %>
-        <% end %>
-
-        <% 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 %>
-            This is how a **warning** node appears.
-          <% end %>
-        <% end %>
-
-        <% 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 %>
-            This is how a **caution** node appears.
-          <% end %>
-        <% end %>
-
-        <% 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" %>
-
-          <% important "An example" do %>
-            This is how a **important** node appears.
-          <% end %>
-        <% end %>
-
-        <% 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" %>
-
-          <% note "An example" do %>
-            This is how a **note** node appears.
-          <% end %>
-        <% end %>
-
-        <% 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" %>
-
-          <% tip "An example" do %>
-            This is how a **tip** node appears.
-          <% end %>
-        <% end %>
-      <% end %>
-
-      <% section "Auxilary materials" 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 %>
-            This is how a **figure** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "table", "xhtml.nodes.table" do %>
-          Information (typically measurement data) represented in tabular form for easy reading, comparison, and analysis.
-
-          <% table "An example" do %>
-            This is how a **table** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "example", "xhtml.nodes.example" do %>
-          A sample application of an idea or thought.
-
-          <% example "An example" do %>
-            This is how a **example** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "equation", "xhtml.nodes.equation" do %>
-          A mathematical equation or formula.
-
-          <% equation "An example" do %>
-            This is how a **equation** node appears.
-          <% end %>
-        <% end %>
-
-        <% section "procedure", "xhtml.nodes.procedure" do %>
-          An outline; a series of steps outlining some kind of process.
-
-          <% procedure "An example" do %>
-            This is how a **procedure** node appears.
-          <% end %>
-        <% end %>
-      <% end %>
-
-      <% section "Bibliographical nodes" do %>
-        The nodes in this section deal with attribution of ideas---an important weapon against plagiarism.
-
-        <% 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 "xhtml.nodes.cite" %>) to perform the citation.
-
-          <% paragraph "An example" do %>
-            See <%= xref 'xhtml.nodes.reference.example' %> for an example of how a **reference** node appears.
-          <% end %>
-
-          <% reference 'xhtml.nodes.reference.example' do %>
-            This is how a **reference** node appears.
-          <% end %>
-        <% end %>
-
-        <% 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 "xhtml.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 "xhtml.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 %>
-    <%= patches_are_welcome %>
-
-    <%= hyperlink 'http://en.wikipedia.org/wiki/Plain_text' %>
-  <% end %>
-
-  <% chapter "LaTeX (PDF)", 'latex' do %>
-    <%= patches_are_welcome %>
-
-    <%= hyperlink 'http://www.latex-project.org' %>
-  <% end %>
-
-  <% chapter "man (UNIX manual page)", 'man' do %>
-    <%= patches_are_welcome %>
-
-    <%= hyperlink 'http://en.wikipedia.org/wiki/Man_page' %>
-  <% end %>
-<% end %>