erbook 5.0.0 → 6.0.0

data/doc/intro.erb

@@ -0,0 +1,97 @@
+<% chapter "Introduction" do %>
+  <% eruby_url = "http://en.wikipedia.org/wiki/ERuby" %>
+
+  <% project_summary do %>
+    **<%= $project %>** is an extensible document processor that emits <%= xref "HelloWorld", "any document you can imagine" %> from [eRuby templates](<%= eruby_url %>) that allow scripting and dynamic content generation.
+
+    A working <%= xref "xhtml", "XHTML (web page)" %> format is provided, while <%= xref "latex", "LaTeX (PDF)" %>, <%= xref "man", "UNIX manual page" %>, and <%= xref "text", "plain text" %> formats are planned... <%= xref "License", "patches are welcome" %>!
+  <% end %>
+
+  **<%= $project %>** is exciting because:
+  * Its documents are scriptable [eRuby templates](<%= eruby_url %>).
+  * It lets you <%= xref "HelloWorld", "define your own document formats" %>.
+  * Its core contains less than 300 lines of code.
+
+  These features distinguish **<%= $project %>** from the competition, which offers neither scriptable documents nor definable document formats:
+  * [DocBook](http://www.docbook.org)
+  * [Deplate](http://deplate.sourceforge.net)
+  * [SiSU](http://www.jus.uio.no/sisu/SiSU/)
+  * [AsciiDoc](http://www.methods.co.nz/asciidoc/)
+  * [txt2tags](http://txt2tags.sourceforge.net)
+  * [Grutatxt](http://www.triptico.com/software/grutatxt.html)
+
+  <% section "Logistics" do %>
+    * <%= xref "history", "Release notes" %> --- history of project releases.
+    * [Source code](http://github.com/sunaku/<%= $program %>) --- obtain via [Git](http://git.or.cz) or browse online.
+    * [API reference](api/index.html) --- documentation for source code.
+
+    To get help or provide feedback, simply
+    <%= xref "License", "contact the authors" %>.
+
+    <% paragraph "Version numbers" do %>
+      **<%= $project %>** 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 thus:
+
+      <table markdown="1">
+        <thead>
+          <tr>
+            <td rowspan="2">What increased in the version number?</td>
+            <td colspan="3">The increase indicates that the release:</td>
+          </tr>
+          <tr>
+            <th>Is backward compatible?</th>
+            <th>Has new features?</th>
+            <th>Has 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 %>
+
+  <% section "License" do %>
+    <%# include ../LICENSE #%>
+  <% end %>
+
+  <% section "Credits" do %>
+    <%= $logo = "![#{$project} logo](#{$program}.png)".to_inline_xhtml %>
+    <%# include README #%>
+  <% end %>
+
+  <% 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 \[**<%= $project %>**] 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 \[... **<%= $project %>**] 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 %>

data/doc/setup.erb

@@ -0,0 +1,62 @@
+<% chapter "Setup" do %>
+  <% section "Requirements" do %>
+    Your system needs the following software to run **<%= $project %>**.
+
+    | Software                        | Description               | Notes                               |
+    | --------                        | -----------               | -----                               |
+    | [Ruby](http://ruby-lang.org)    | Ruby language interpreter | Version 1.8.7 or newer is required. |
+    | [RubyGems](http://rubygems.org) | Ruby packaging system     | Version 1.0.0 or newer is required. |
+  <% end %>
+
+  <% section "Installation" do %>
+    You can install **<%= $project %>** by running this command:
+
+        gem install <%= $program %>
+
+    To check whether the installation was sucessful, run this command:
+
+        <%= $program %> -v
+
+    If the installation was successful, you will see output like this:
+
+    <pre><%= verbatim `ruby bin/#{$program} -v` %></pre>
+
+    Otherwise, you can <%= xref "License", "contact the author" %> for help.
+  <% end %>
+
+  <% section "Manifest" do %>
+    You will see the following items inside **<%= $project %>**'s installation directory, whose path you can determine by running this command:
+
+        <%= $program %> -v
+
+    * <tt>bin/</tt>
+
+      * <tt><%= $program %></tt> --- the main **<%= $project %>** executable.
+
+    * <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>
+
+      * <tt><%= $program %>.rb</tt> --- the main **<%= $project %>** library.
+
+      * <tt><%= $program %>/</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><%= $program %>.svg</tt> --- source file of the **<%= $project %>** logo.
+
+      * <tt>index.erb</tt> --- source file of this manual.
+
+      * <tt>api/</tt> --- API reference documentation.
+
+    * <tt>LICENSE</tt> --- project license and copyright notice.
+  <% end %>
+<% end %>

data/doc/theory.erb

@@ -0,0 +1,187 @@
+<% chapter "Theory of operation" do %>
+  When you run <%= $project %>, 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::Document::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::Document::Node` class", "Node.class" do %>
+      When <%= $project %> builds a document tree from the nodes in an input document, it stores information about these nodes into `ERBook::Document::Node` objects.  A `ERBook::Document::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::Document::Node`            | The `ERBook::Document::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::Document::Node` | List of child nodes from the document tree.                                                                                                                |
+
+      Furthermore, the `ERBook::Document::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::Document::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 <%= $project %> 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" %>.  |
+      | inline    | Boolean  | Is node's output an in-line string of text that can be embedded anywhere in the document? |
+
+      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, <%= $project %> 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::Document::Node`            | The node for which this template is being evaluated.                                             |
+        <%= common_template_vars = %{
+        | `@roots`         | `Array` of `ERBook::Document::Node` | All root nodes in the document tree.                                                             |
+        | `@nodes`         | `Array` of `ERBook::Document::Node` | All nodes in the document tree.                                                                  |
+        | `@nodes_by_type` | `Hash`                              | Mapping from node type (`String`) to array of `ERBook::Document::Node` objects having that type. |
+        | `@format`        | `Hash`                              | Data from the format specification file.                                                         |
+
+        #{PROJECT} also provides the following mappings inside the `@format` variable:
+
+        | Expression       | Type     | Description                                    |
+        | ----------       | ----     | -----------                                    |
+        | `@format[:name]` | `String` | Short-hand name of the current format.         |
+        | `@format[: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:
+
+              <%= $program %> 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/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input` %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/doc/usage.erb

@@ -0,0 +1,39 @@
+<% chapter "Usage" do %>
+  <% section "Command-line interface" do %>
+    <pre><%= `ruby bin/erbook -h` %></pre>
+
+    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" %>).
+
+    <% section "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 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 %>

data/fmt/xhtml.yaml

@@ -41,40 +41,40 @@ code: |
   module ERBook
     class Template
       # Protects the given content from the text-to-XHTML conversion process.
-      def verbatim aContent
-        ERB::Util.html_escape aContent
+      def verbatim content
+        ERB::Util.html_escape content
       end
 
       # Returns XHTML for a hyperlink to the given
       # URL of the given label and mouse-hover title.
-      def hyperlink aUrl, aLabel = aUrl, aTitle = nil
-        %{<a href="#{aUrl}"#{%{ title="#{aTitle}"} if aTitle}>#{aLabel}</a>}
+      def hyperlink url, label = url, title = nil
+        %{<a href="#{url}"#{%{ title="#{title}"} if title}>#{label}</a>}
       end
 
       # Returns an <img/> tag that embeds the given image file.
       #
-      # aPath:: path to the image file
-      # aFormat:: format of the image file (e.g. PNG, JPEG, GIF, etc.)
-      # aAtts:: additional attributes for the <img> tag
+      # path::    path to the image file
+      # format::  format of the image file (e.g. PNG, JPEG, GIF, etc.)
+      # atts::    additional attributes for the <img> tag
       #
-      def embed_image_file aPath, aFormat = aPath[/\w+/], aAtts = {}
-        data = ERBook.base_64_encode File.read(aPath)
-        embed_image_data data, aFormat, aAtts
+      def embed_image_file path, format = path[/\w+/], atts = {}
+        data = ERBook.base_64_encode File.read(path)
+        embed_image_data data, format, atts
       end
 
       # Returns an <img/> tag that embeds the given raw image data.
       #
-      # aData:: raw image data
-      # aFormat:: format of the image file (e.g. PNG, JPEG, GIF, etc.)
-      # aAtts:: additional attributes for the <img> tag
+      # data::    raw image data
+      # format::  format of the image file (e.g. PNG, JPEG, GIF, etc.)
+      # atts::    additional attributes for the <img> tag
       #
-      def embed_image_data aData, aFormat, aAtts = {}
-        aAtts[:src] = ERBook.base_64_embed_image_data(aData, aFormat)
-        "<img#{aAtts.to_xml_atts}/>"
+      def embed_image_data data, format, atts = {}
+        atts[:src] = ERBook.base_64_embed_image_data(data, format)
+        "<img#{atts.to_xml_atts}/>"
       end
     end
 
-    class Node
+    class Document::Node
       # Returns the user-defined title for this node's content.
       def title
         @title ||= args[0]
@@ -85,7 +85,6 @@ code: |
         @id ||= args[1]
       end
 
-
       ##
       # utility methods
       #
@@ -94,11 +93,6 @@ code: |
         type.to_s.capitalize
       end
 
-      def type_label_here_link #:nodoc:
-        s = type_label
-        here_link s, s
-      end
-
       # Returns the title of this node as XHTML.
       def title_xhtml
         title.to_s.to_inline_xhtml
@@ -115,19 +109,19 @@ code: |
       end
 
       # Returns a hyperlink to this node containing its title.
-      def title_link aTitle = nil
-        here_link here_frag, aTitle || title_xhtml
+      def title_link title = nil
+        title || title_xhtml
       end
 
       # Returns a hyperlink to this node
       # containing its LaTeX-style index number.
       def index_link
-        list_link here_frag, list_frag, index
+        index
       end
 
       # Returns a hyperlink to this node containing its occurrence number.
       def number_link
-        list_link here_frag, list_frag, [type_label, number].compact.join(' ')
+        [type_label, number].compact.join(' ')
       end
 
       # Returns a hyperlink to this node containing
@@ -142,6 +136,65 @@ code: |
         "#{index_link}&nbsp;&nbsp;#{title_link}"
       end
 
+      # Returns a navigation menu relative to this node.
+      def navigation
+        self.class.navigation(
+          here_frag,
+          (list_frag if defn['toc'] || defn['lof']),
+          (prev_node.here_frag if prev_node),
+          (next_node.here_frag if next_node)
+        )
+      end
+
+      LIST_SIGN = '&equiv;'  # identical to
+      HERE_SIGN = '&#x25CE;' # bullseye
+      PREV_SIGN = '&#x25B3;' # white up-pointing triangle
+      NEXT_SIGN = '&#x25BD;' # white down-pointing triangle
+
+      # Calculates a local navigation menu containing links
+      # to the given URI fragments (which can be nil).
+      def self.navigation here_frag, list_frag, prev_frag, next_frag
+        list_link = list_frag ? %{<a title="Reverse jump to listing" href="##{list_frag}">#{LIST_SIGN}</a>} : LIST_SIGN
+
+        here_link = here_frag ? %{<a title="Jump to this segment" href="##{here_frag}">#{HERE_SIGN}</a>} : HERE_SIGN
+
+        prev_link = prev_frag ? %{<a title="Jump to previous segment" href="##{prev_frag}">#{PREV_SIGN}</a>} : PREV_SIGN
+
+        next_link = next_frag ? %{<a title="Jump to next segment" href="##{next_frag}">#{NEXT_SIGN}</a>} : NEXT_SIGN
+
+        %{<a name="#{here_frag}"/><div class="nav" id="#{here_frag}">#{list_link}#{prev_link}#{next_link}#{here_link}</div>}
+      end
+
+      # Returns a hyperlink to this node.
+      #
+      # @param [String] label
+      #   Optional label (may contain XHTML) for the hyperlink.
+      #
+      #   If not specified, the title and designation of
+      #   this node will be used as the label instead.
+      #
+      def xref_link label = nil
+        prefix = [type_label, index || number].compact.join(' ')
+
+        title_text =
+          if type == 'reference'
+            prefix
+          else
+            [prefix, title].compact.join('. ')
+          end
+
+        title_xhtml =
+          if label
+            label
+          else
+            title_text
+          end.to_s.to_inline_xhtml
+
+        %{<a class="xref" href="##{here_frag}"#{
+          %( title="#{ERB::Util.h title_text}") if label
+        }>#{title_xhtml}</a>}
+      end
+
 
       ##
       # URI fragments
@@ -172,37 +225,28 @@ code: |
       def list_frag #:nodoc:
         @list_frag ||= "rev:#{here_frag}"
       end
-
-
-      private
-
-      def here_link aHereFrag, aLabel #:nodoc:
-        %{<a class="here" title="Permanent link to this section" href="##{aHereFrag}">#{aLabel}</a>}
-      end
-
-      def list_link aHereFrag, aListFrag, aLabel #:nodoc:
-        %{<a class="list" title="Return to table of contents" id="#{aHereFrag}" href="##{aListFrag}">#{aLabel}</a>}
-      end
     end
 
     # Encodes the given input in base64 format.
-    def ERBook.base_64_encode aInput #:nodoc:
-      [aInput].pack('m')
+    def ERBook.base_64_encode input #:nodoc:
+      [input].pack('m')
     end
 
     # Returns a string denoting embedded, base64 encoded data.
-    def ERBook.base_64_embed aData, aFormat #:nodoc:
-      "data:#{aFormat.to_s.downcase};base64,#{aData.tr("\n", '')}"
+    def ERBook.base_64_embed data, format #:nodoc:
+      "data:#{format.to_s.downcase};base64,#{data.tr("\n", '')}"
     end
 
     # Returns a string denoting embedded, base64 encoded image data.
-    # aFormat:: format of the image data (e.g. PNG, JPEG, GIF, etc.)
-    def ERBook.base_64_embed_image_data aData, aFormat #:nodoc:
-      base_64_embed aData, "image/#{aFormat}"
+    #
+    # format:: format of the image data (e.g. PNG, JPEG, GIF, etc.)
+    #
+    def ERBook.base_64_embed_image_data data, format #:nodoc:
+      base_64_embed data, "image/#{format}"
     end
 
     ##
-    # load admonition icons
+    # admonition icons
     #
 
     ICONS_DIR = File.join(ERBook::FORMATS_DIR, 'xhtml.icons')
@@ -234,11 +278,11 @@ code: |
 
       # Returns an <img/> tag that renders the image
       # data embedded as an ENTITY in the html DOCTYPE.
-      def to_xhtml aAtts = {}
-        aAtts[:alt] ||= name
-        aAtts[:src] = entity_xml
-        aAtts[:class] = :icon
-        "<img#{aAtts.to_xml_atts}/>"
+      def to_xhtml atts = {}
+        atts[:alt] ||= name
+        atts[:src] = entity_xml
+        atts[:class] = :icon
+        "<img#{atts.to_xml_atts}/>"
       end
     end
 
@@ -259,249 +303,253 @@ code: |
 
 
 nodes:
-  ##
-  # Structure
-  #
-
-  header: &header
-    toc: false
-    lof: false
-    index: false
-    number: false
-    silent: true
-    output: <%= @node.content_xhtml %>
-
-  header_outside_above: &header_insert
-    toc: false
-    lof: false
-    index: false
-    number: false
-    silent: true
-    output: <div class="<%= @node.type %>"><%= @node.content_xhtml %></div>
-
-  header_inside_above:  *header_insert
-  header_inside_below:  *header_insert
-  header_outside_below: *header_insert
-
-  footer:               *header
-  footer_outside_above: *header_insert
-  footer_inside_above:  *header_insert
-  footer_inside_below:  *header_insert
-  footer_outside_below: *header_insert
-
-  abstract:
-    toc: false
-    lof: false
-    index: false
-    number: false
-    silent: true
-    output: |
-      <div id="<%= @node.type_label %>">
-        <h1 class="title"><%= @node.type_label_here_link %></h1>
-        <%= @node.content_xhtml_div %>
-      </div>
+  # object model
+    node:
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: false
+      inline: true
+      output: <%= @node.content_xhtml %>
 
+  # Structure
+    header: &header
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: true
+      inline: true
+      output: <%= @node.content_xhtml %>
+
+    header_outside_above: &header_insert
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: true
+      inline: true
+      output: <div class="<%= @node.type %>"><%= @node.content_xhtml %></div>
+
+    header_inside_above:  *header_insert
+    header_inside_below:  *header_insert
+    header_outside_below: *header_insert
+
+    footer:               *header
+    footer_outside_above: *header_insert
+    footer_inside_above:  *header_insert
+    footer_inside_below:  *header_insert
+    footer_outside_below: *header_insert
+
+    abstract:
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: true
+      output: |
+        <div id="<%= @node.type_label %>">
+          <%= @node.navigation %>
+          <h1 class="title"><%= @node.type_label %></h1>
+          <%= @node.content_xhtml_div %>
+        </div>
 
-  ##
   # Organization
-  #
-
-  part: &latex
-    toc: true
-    lof: false
-    index: true
-    number: true
-    output: |
-      <div class="<%= @node.type %>">
-        <h1 class="title">
-          <%= @node.type_label %>&nbsp;<%= @node.index_link %>
-          <br/>
-          <big><%= @node.title_link %></big>
-        </h1>
-        <%= @node.content_xhtml_div %>
-      </div>
-
-  chapter: *latex
-
-  section:
-    toc: true
-    lof: false
-    index: true
-    number: true
-    output: |
-      <% depth = [6, @node.depth + 1].min %>
-      <div class="<%= @node.type %>">
-        <h<%= depth %> class="title">
-          <%= @node.index_and_title_link %>
-        </h<%= depth %>>
-        <%= @node.content_xhtml_div %>
-      </div>
+    part: &latex
+      toc: true
+      lof: false
+      depth: true
+      index: true
+      number: true
+      silent: false
+      output: |
+        <div class="<%= @node.type %>">
+          <%= @node.navigation %>
+          <h1 class="title">
+            <%= @node.type_label %>&nbsp;<%= @node.index_link %>
+            <br/>
+            <big><%= @node.title_link %></big>
+          </h1>
+          <%= @node.content_xhtml_div %>
+        </div>
 
-  paragraph:
-    toc: false
-    lof: false
-    index: false
-    number: false
-    output: |
-      <div class="<%= @node.type %>">
-        <p class="title"><%= @node.title_link %></p>
-        <%= @node.content_xhtml_div %>
-      </div>
+    chapter: *latex
+
+    section:
+      toc: true
+      lof: false
+      depth: true
+      index: true
+      number: true
+      silent: false
+      output: |
+        <% depth = [6, @node.depth + 1].min %>
+        <div class="<%= @node.type %>">
+          <%= @node.navigation %>
+          <h<%= depth %> class="title">
+            <%= @node.index_and_title_link %>
+          </h<%= depth %>>
+          <%= @node.content_xhtml_div %>
+        </div>
 
+    paragraph:
+      toc: true
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: false
+      output: |
+        <div class="<%= @node.type %>">
+          <%= @node.navigation %>
+          <p class="title"><%= @node.title_link %></p>
+          <%= @node.content_xhtml_div %>
+        </div>
 
-  ##
   # Admonitions
-  #
-
-  tip: &admonition
-    toc: false
-    lof: true
-    index: false
-    number: true
-    output: |
-      <div class="<%= @node.type %>">
-        <p class="title"><%= @node.number_and_title_link %></p>
-        <div class="content"><%= ICON_BY_NAME[@node.type].to_xhtml %><%= @node.content_xhtml %></div>
-      </div>
-
-  note: *admonition
-  caution: *admonition
-  warning: *admonition
-  important: *admonition
+    tip: &admonition
+      toc: false
+      lof: true
+      depth: true
+      index: false
+      number: true
+      silent: false
+      output: |
+        <div class="<%= @node.type %>">
+          <%= @node.navigation %>
+          <p class="title"><%= @node.number_and_title_link %></p>
+          <div class="content">
+            <%= ICON_BY_NAME[@node.type].to_xhtml %>
+            <%= @node.content_xhtml %>
+          </div>
+        </div>
 
+    note: *admonition
+    caution: *admonition
+    warning: *admonition
+    important: *admonition
 
-  ##
   # Auxilary materials (formal blocks)
   # see http://www.sagehill.net/docbookxsl/FormalTitles.html
-  #
-
-  figure: &formal
-    toc: false
-    lof: true
-    index: false
-    number: true
-    output: |
-      <div class="<%= @node.type %>">
-        <p class="title"><%= @node.number_and_title_link %></p>
-        <%= @node.content_xhtml_div %>
-      </div>
-
-  table: *formal
-  example: *formal
-  equation: *formal
-  procedure: *formal
+    figure: &formal
+      toc: false
+      lof: true
+      depth: true
+      index: false
+      number: true
+      silent: false
+      output: |
+        <div class="<%= @node.type %>">
+          <%= @node.navigation %>
+          <p class="title"><%= @node.number_and_title_link %></p>
+          <%= @node.content_xhtml_div %>
+        </div>
 
+    table: *formal
+    example: *formal
+    equation: *formal
+    procedure: *formal
 
-  ##
   # cross-references
-  #
-
-  xref:
-    toc: false
-    lof: false
-    index: false
-    number: false
-    output: |
-      <%=
-        scope = @nodes.select {|n| n.content}
-
-        target = scope.find {|n| n.id == @node.args[0]} || # id has 1st priority
-                 scope.find {|n| n.title == @node.args[0]}
-
-        if target
-          prefix = "#{target.type_label} #{target.index || target.number}"
-
-          title_text =
-            if target.type == 'reference'
-              prefix
-            else
-              [prefix, target.title].compact.join('. ')
-            end
-
-          title_auto = @node.args.length < 2
-
-          title_xhtml =
-            if title_auto
-              title_text
-            else
-              @node.args[1].to_s
-            end.to_inline_xhtml
-
-          %{<a class="#{@node.type}" href="##{target.here_frag}"#{
-            %( title="#{title_text}") unless title_auto
-          }>#{title_xhtml}</a>}
-        else
-          raise ArgumentError, "invalid cross-reference to #{@node.title.inspect}", @node.trace
-        end
-      %>
+    xref:
+      toc: false
+      lof: false
+      depth: true
+      index: false
+      number: false
+      silent: false
+      inline: true
+      output: |
+        <%=
+          query, label = @node.args
+
+          scope = @nodes.select {|n| n.content }
+          target = scope.find {|n| n.id == query } || # id has 1st priority
+                   scope.find {|n| n.title == query }
 
+          if target
+            target.xref_link label
+          else
+            raise ArgumentError, "invalid cross-reference to #{@node.title.inspect}", @node.trace
+          end
+        %>
 
-  ##
   # Bibliography
-  #
-
-  reference:
-    toc: false
-    lof: false
-    index: false
-    number: true
-    silent: true
-
-  cite:
-    toc: false
-    lof: false
-    index: false
-    number: false
-    output: |
-      <%=
-        target = @types['reference'].find {|n| n.title == @node.args[0]}
-
-        if target
-          '<sup>[%s]</sup>' % [
-
-            '<a class="%s" href="#%s">%s</a>' % [
-              @node.type,
-              target.here_frag,
-              target.number
-            ],
-
-            *@node.args[1..-1]
-
-          ].join(', ')
-        else
-          raise ArgumentError, "invalid citation for #{@node.title.inspect}", @node.trace
-        end
-      %>
+    reference:
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: true
+      silent: true
+      inline: true
+
+    cite:
+      toc: false
+      lof: false
+      depth: false
+      index: false
+      number: false
+      silent: false
+      inline: true
+      output: |
+        <%=
+          target = @nodes_by_type['reference'].find {|n| n.title == @node.args[0]}
+
+          if target
+            '<sup>[%s]</sup>' % [
+
+              '<a class="%s" href="#%s">%s</a>' % [
+                @node.type,
+                target.here_frag,
+                target.number
+              ],
+
+              *@node.args[1..-1]
+
+            ].join(', ')
+          else
+            raise ArgumentError, "invalid citation for #{@node.title.inspect}", @node.trace
+          end
+        %>
 
 output: |
   <%
     # set default parameter values
-    $title   = '$title' unless defined? $title
-    $authors = {'$authors' => nil} unless defined? $authors
-    $date    = Time.now.strftime("%d %B %Y") unless defined? $date
+    $title    = '$title' unless defined? $title
+    $subtitle = '$subtitle' unless defined? $subtitle
+    $authors  = {'$authors' => nil} unless defined? $authors
+    $date     = Time.now.strftime("%d %B %Y") unless defined? $date
 
-    abstract = @types['abstract'].first
+    abstract = @nodes_by_type['abstract'].first
 
-    references = @types['reference']
+    references = @nodes_by_type['reference']
     if references.empty?
       references = nil
     end
 
     # compute table of contents
       toc_builder = lambda do |n|
-        if @spec['nodes'][n.type]['toc']
+        nested = n.children.inject('') {|s,c| s << toc_builder[c] }
+        nested = nil if nested.empty?
+
+        if n.defn['toc']
           entry = '%s<a id="%s" href="#%s">%s</a>' % [
             (n.index.to_s + '&nbsp;&nbsp;' if n.index),
             n.list_frag,
             n.here_frag,
             n.title.to_s.to_inline_xhtml
           ]
-          nested = n.children.inject('') {|s,c| s << toc_builder[c] }
 
-          %{<li>#{entry}#{ "<ul>#{nested}</ul>" unless nested.empty? }</li>}
+          %{<li>#{entry}#{"<ul>#{nested}</ul>" if nested}</li>}
         else
-          ''
-        end
+          nested
+        end.to_s
       end
 
       toc = @roots.inject('') {|s,n| s << toc_builder[n] }
@@ -509,16 +557,16 @@ output: |
     # compute list of figures
       lof_enums = {} # type => nodes
 
-      @spec['nodes'].each_pair do |name, info|
+      @format['nodes'].each_pair do |name, info|
         if info['lof']
-          nodes = @types[name]
+          nodes = @nodes_by_type[name]
           lof_enums[name] = nodes unless nodes.empty?
         end
       end
 
       lof_sections = []
 
-      lof = lof_enums.sort.map do |(type, nodes)|
+      lof = lof_enums.sort.map do |type, nodes|
         nested = nodes.map do |n|
           %{<li><a id="#{n.list_frag}" href="##{n.here_frag}">#{n.title.to_s.to_inline_xhtml}</a></li>}
         end
@@ -526,7 +574,7 @@ output: |
         label = type.capitalize << 's' # TODO: pluralize this properly
         lof_sections << label
 
-        %{<h2 id="#{label}" class="title"><a class="here" href="##{label}">#{label}</a></h2> <ol>#{nested}</ol>}
+        %{#{ERBook::Document::Node.navigation label, "rev:#{label}", nil, nil}<h2 class="title">#{label}</h2> <ol>#{nested}</ol>}
       end
   %>
   <?xml version="1.0" encoding="utf-8"?>
@@ -539,10 +587,19 @@ output: |
   <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
       <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
-      <meta name="date" content="<%= $date %>"/>
-      <meta name="author" content="<%= $authors.keys.join(', ') %>"/>
       <meta name="generator" content="<%= ERBook::DISPLAY %>"/>
-      <title><%= $title.to_s.to_inline_xhtml %></title>
+
+      <% if $title %>
+        <title><%= $title.to_s.to_inline_xhtml %></title>
+      <% end %>
+
+      <% if $authors %>
+        <meta name="author" content="<%= $authors.keys.join(', ') %>"/>
+      <% end %>
+
+      <% if $date %>
+        <meta name="date" content="<%= $date %>"/>
+      <% end %>
 
       <% if $feeds %>
         <% $feeds.each_pair do |url, fmt| %>
@@ -550,18 +607,19 @@ output: |
         <% end %>
       <% end %>
 
-      <% @spec['styles'].each_pair do |media, style| %>
-        <style type="text/css" media="<%= media %>">
-        <![CDATA[<%= style %>]]>
-        </style>
+      <% @format['styles'].each do |style| %>
+        <% style.each_pair do |media, code| %>
+          <style type="text/css" media="<%= media %>">
+          <![CDATA[<%= ERB.new(code).result(binding) %>]]>
+          </style>
+        <% end %>
       <% end %>
 
       <style type="text/css" media="screen">
       <![CDATA[
         /* decorate external hyperlinks with a visual indicator */
-        a:not([href^="#"])
+        a[href]:not([href^="#"])
         {
-            color               : #3366BB;
             background          : <%= ICON_BY_NAME['link'].data_css %>;
             background-position : center right;
             background-repeat   : no-repeat;
@@ -581,6 +639,7 @@ output: |
       </style>
     </head>
     <body>
+    <div id="body">
       <%
         # menu of links to link sections
         nav = [
@@ -592,41 +651,54 @@ output: |
 
         if nav.length > 1
       %>
-      <div id="nav">
-        <%=
-          nav.map do |section|
-            %{<a href="##{section}">#{section}</a>}
-          end.join(' &middot; ')
-        %>
-      </div>
+      <ul id="nav" class="nav">
+        <% nav.each do |section| %>
+          <li><a id="rev:<%= section %>" href="#<%= section %>"><%= section %></a></li>
+        <% end %>
+      </ul>
       <% end %>
 
       <br style="display: none"/>
       <hr style="display: none"/>
       <br style="display: none"/>
 
-      <%= node = @types['header_outside_above'].first and node.output %>
+      <%= node = @nodes_by_type['header_outside_above'].first and node.output %>
       <div id="header">
-      <%= node = @types['header_inside_above'].first and node.output %>
-      <% if header = @types['header'].first %>
+      <%= node = @nodes_by_type['header_inside_above'].first and node.output %>
+      <% if header = @nodes_by_type['header'].first %>
         <%= header.output %>
       <% else %>
-        <%= $logo if defined? $logo %>
-        <h1 class="title"><%= $title.to_s.to_inline_xhtml %></h1>
-        <h2 class="authors"><%=
-          $authors.map do |(name, url)|
-            if url
-              %{<a href="#{url}">#{name}</a>}
-            else
-              name
-            end
-          end.join(', ')
-        %></h2>
-        <h3 class="date"><%= $date %></h3>
+        <% if $logo %>
+          <div class="logo"><%= $logo %></div>
+        <% end %>
+
+        <% if $title %>
+          <h1 class="title"><%= $title.to_s.to_inline_xhtml %></h1>
+        <% end %>
+
+        <% if $subtitle %>
+          <h2 class="subtitle"><%= $subtitle.to_s.to_inline_xhtml %></h2>
+        <% end %>
+
+        <% if $authors %>
+          <h3 class="authors"><%=
+            $authors.map do |name, url|
+              if url
+                %{<a href="#{url}">#{name}</a>}
+              else
+                name
+              end
+            end.join(', ')
+          %></h3>
+        <% end %>
+
+        <% if $date %>
+          <h3 class="date"><%= $date %></h3>
+        <% end %>
       <% end %>
-      <%= node = @types['header_inside_below'].first and node.output %>
+      <%= node = @nodes_by_type['header_inside_below'].first and node.output %>
       </div>
-      <%= node = @types['header_outside_below'].first and node.output %>
+      <%= node = @nodes_by_type['header_outside_below'].first and node.output %>
 
       <%= abstract.output if abstract %>
 
@@ -636,12 +708,13 @@ output: |
 
       <% unless toc.empty? %>
         <div id="toc">
-          <h1 class="title" id="Contents"><a class="here" href="#Contents">Contents</a></h1>
+          <%= ERBook::Document::Node.navigation "Contents", "rev:Contents", nil, nil %>
+          <h1 class="title">Contents</h1>
           <ul>
             <%= toc %>
 
             <% if references %>
-            <li><a href="#References">References</a></li>
+            <li><a id="rev:References" href="#References">References</a></li>
             <% end %>
           </ul>
         </div>
@@ -659,7 +732,8 @@ output: |
 
       <% if references %>
       <div id="bib">
-        <h1 class="title" id="References"><a class="here" href="#References">References</a></h1>
+        <%= ERBook::Document::Node.navigation "References", "rev:References", nil, nil %>
+        <h1 class="title" >References</h1>
         <ol>
         <% references.each do |n| %>
           <li id="<%= n.here_frag %>"><%= n.content_xhtml %></li>
@@ -672,10 +746,10 @@ output: |
       <hr style="display: none"/>
       <br style="display: none"/>
 
-      <%= node = @types['footer_outside_above'].first and node.output %>
+      <%= node = @nodes_by_type['footer_outside_above'].first and node.output %>
       <div id="footer">
-      <%= node = @types['footer_inside_above'].first and node.output %>
-      <% if footer = @types['footer'].first %>
+      <%= node = @nodes_by_type['footer_inside_above'].first and node.output %>
+      <% if footer = @nodes_by_type['footer'].first %>
         <%= footer.content.to_s.to_xhtml %>
       <% else %>
         Generated by <a href="<%= ERBook::WEBSITE %>"><%= ERBook::DISPLAY %></a> on <%= Time.now %>.
@@ -702,24 +776,31 @@ output: |
           The icons shown above are &copy; 2007 <a href="https://www.ohloh.net/projects/mediawiki/contributors">MediaWiki contributors</a>. They are part of the <a href="http://www.mediawiki.org/wiki/MediaWiki">MediaWiki</a> software, which is distributed under the <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License, version 2</a>.
         </p>
       </div>
-      <%= node = @types['footer_inside_below'].first and node.output %>
+      <%= node = @nodes_by_type['footer_inside_below'].first and node.output %>
       </div>
-      <%= node = @types['footer_outside_below'].first and node.output %>
+      <%= node = @nodes_by_type['footer_outside_below'].first and node.output %>
+    </div>
     </body>
   </html>
 
+# definition of font families for use in the CSS styles
+fonts:
+  serif:      Constantia, "Book Antiqua", "URW Bookman L", serif
+  sans-serif: Calibri, Verdana, sans-serif
+  monospace:  Monaco, Consolas, "Lucida Console", monospace
+
 styles:
-  all: |
-    body
-    {
-        color               : #000000;
-        background-color    : #FFFFFF;
-        line-height         : 1.5em;
-        font-family         : Calibri, Verdana, sans-serif;
-    }
+- all: |
+    /* general */
+      body
+      {
+          color             : #000000;
+          background-color  : #FFFFFF;
+          line-height       : 1.5em;
+          font-family       : <%= @format['fonts']['sans-serif'] %>;
+      }
 
     /* emphasis */
-
       blockquote
       {
           color             : #333;
@@ -728,6 +809,8 @@ styles:
 
       em
       {
+          font-family       : <%= @format['fonts']['serif'] %>;
+          font-size         : 105%;
       }
 
       hr
@@ -738,17 +821,15 @@ styles:
       }
 
     /* source code */
-
       tt,
       code,
       pre
       {
-          font-family       : Monaco, Consolas, "Lucida Console", monospace;
+          font-family       : <%= @format['fonts']['monospace'] %>;
           font-size         : 100%; /* appears like "size: small" otherwise */
       }
 
     /* hyperlinks */
-
       a > img
       {
           border            : none;
@@ -759,20 +840,7 @@ styles:
           _border           : none; /* for IE6 */
       }
 
-    /* lists */
-
-      #content li:first-child
-      {
-          margin-top        : 1em;
-      }
-
-      #content li
-      {
-          margin-bottom     : 1em;
-      }
-
     /* headings */
-
       h1,
       h2,
       h3,
@@ -782,7 +850,7 @@ styles:
       .title
       {
           font-weight       : lighter;
-          font-family       : Constantia, "Book Antiqua", "URW Bookman L", serif;
+          font-family       : <%= @format['fonts']['serif'] %>;
       }
 
       #lof h1,
@@ -837,7 +905,6 @@ styles:
       }
 
     /* tables */
-
       table
       {
           border-collapse   : collapse; /* no spacing between cell borders */
@@ -851,7 +918,7 @@ styles:
           padding           : 1em;
           border            : 1px solid #bbb;
           vertical-align    : top;
-          background-color  : inherit;
+          background-color  : #FFFFFF;
           _background-color : #FFFFFF; /* for IE6 */
       }
 
@@ -861,18 +928,12 @@ styles:
       }
 
     /* document structure */
-
-      #nav
-      {
-          text-align        : center;
-          margin-bottom     : 4em;
-      }
-
       #header
       {
           text-align        : center;
       }
 
+      .logo,
       .header_outside_above,
       #header,
       .header_outside_below
@@ -945,7 +1006,6 @@ styles:
       }
 
     /* document nodes */
-
       .part    > .title,
       .chapter > .title
       {
@@ -1014,6 +1074,20 @@ styles:
           margin            : 3em;
       }
 
+      .tip       .nav,
+      .note      .nav,
+      .caution   .nav,
+      .warning   .nav,
+      .important .nav,
+      .figure    .nav,
+      .table     .nav,
+      .example   .nav,
+      .equation  .nav,
+      .procedure .nav
+      {
+          margin-left       : -7.65em;
+      }
+
       .tip       > .content,
       .note      > .content,
       .caution   > .content,
@@ -1069,16 +1143,30 @@ styles:
           _margin           : auto; /* for IE6 */
       }
 
-  screen: |
-    body
-    {
+- screen: |
+    /* general */
+      body
+      {
+          margin            : 0;
+          padding           : 0;
+          padding-left      : 10em; /* room for local navigation menus */
+          padding-right     : 10em; /* keep #body visually centered */
+          background-color  : #808080;
+      }
+
+      /* the actual content of the <body> element */
+      #body
+      {
           margin            : auto;
-          max-width         : 36em;
-          padding           : 0.5em;
-    }
+          max-width         : 38em;
 
-    /* source code */
+          background-color  : #FFFFFF;
+          border-left       : 0.35em solid #696969;
+          border-right      : 0.35em solid #696969;
+          padding           : 2em;
+      }
 
+    /* source code */
       tt
       {
           background-color  : #F0F8FF;
@@ -1091,7 +1179,11 @@ styles:
           border            : 1px solid #b1d827;
           background-color  : #F5FFDF;
           padding           : 1em;
-          overflow          : auto;
+
+          /* fit container to content; no overflow! */
+          display           : inline-block;
+          margin            : 0;
+          min-width         : 92.5%;
       }
 
       /* output of the syntax coloring library */
@@ -1102,7 +1194,6 @@ styles:
       }
 
     /* hyperlinks */
-
       a
       {
           text-decoration   : none;
@@ -1115,39 +1206,77 @@ styles:
 
       a:link
       {
-          color             : #002BB8;
+          color             : #0038E1; /* maximum saturation of RoyalBlue */
       }
 
       a:visited
       {
-          color             : #5A3696;
+          color             : #800080;
       }
 
-      a.here,
-      a.list
+      #toc a:target:after,
+      #lof a:target:after,
+      #nav a:target:after
       {
-          color             : #000000;
+          content           : "★"; /* &#x2605; */
+          color             : #FF0000;
+          font-size         : x-large;
+          padding-left      : 0.125em;
       }
 
-      a:target,
-      a:target *,
-      *:target a.list
+    /* document structure */
+      /* mini navigation menu beside every block node */
+      .nav
       {
-          background-color  : #FF4500 !important;
-          color             : #FFFFFF !important;
+          width             : 4em;
+          float             : left; /* detach from main content */
+          margin-left       : -6.075em;
+
+          font-size         : 1.9em;
+          letter-spacing    : 0.25em;
+          text-align        : center;
+
+          color             : #696969; /* same colors to hide non-links */
+          background-color  : #696969;
+          padding           : 0.5em;
+          margin-top        : -0.5em;
       }
 
-      a:target,
-      *:target a.list
+      .nav:target,
+      .nav:hover
       {
-          padding           : 0.1em;
-          font-weight       : bolder;
+          color             : #333; /* same colors to hide non-links */
+          background-color  : #333;
+      }
+
+      .nav a:link,
+      .nav a:visited
+      {
+          color             : #D3D3D3;
+      }
+
+      .nav a:hover,
+      #nav a:target:after {
+          color             : #9ACD32;
           text-decoration   : none;
       }
 
-  print: |
-    /* source code */
+      /* global navigation menu at the top of the page */
+      #nav
+      {
+          font-size         : 1em;
+          letter-spacing    : 0;
+          width             : 8.5em;
+          margin-left       : -11.5em;
+      }
+
+      #nav li
+      {
+          list-style-type   : none;
+      }
 
+- print: |
+    /* source code */
       tt
       {
           font-weight       : normal;
@@ -1159,7 +1288,6 @@ styles:
       }
 
     /* headings */
-
       h1,
       h2,
       h3,
@@ -1172,7 +1300,6 @@ styles:
       }
 
     /* hyperlinks */
-
       /* blend all hyperlinks with normal text */
       a:link,
       a:visited
@@ -1182,8 +1309,8 @@ styles:
       }
 
       /* emphasize external and cross-reference hyperlinks */
-      a:not([href^="#"]):link,
-      a:not([href^="#"]):visited,
+      a[href]:not([href^="#"]):link,
+      a[href]:not([href^="#"]):visited,
       a.xref[title]:link,
       a.xref[title]:visited
       {
@@ -1193,10 +1320,10 @@ styles:
       }
 
       /* show URL of destination for external hyperlinks */
-      a:not([href^="#"]):after
+      a[href]:not([href^="#"]):after
       {
           content           : " " attr(href);
-          font-family       : Monaco, Consolas, "Lucida Console", monospace;
+          font-family       : <%= @format['fonts']['monospace'] %>;
       }
 
       /* show name of destination for cross-references */
@@ -1212,8 +1339,8 @@ styles:
       }
 
     /* document structure */
-
       #nav,
+      .nav,
       #lof
       {
           display           : none;
@@ -1228,7 +1355,6 @@ styles:
       }
 
     /* document nodes */
-
       .part    > .title > big,
       .chapter > .title > big
       {
@@ -1240,4 +1366,3 @@ styles:
       {
           _padding-bottom   : 0.5em; /* for IE6 */
       }
-