Abstract

Gerbil is an extensible document generator based on eRuby that outputs to any format you want: HTML (web page), LaTeX, UNIX man page, plain text, your own custom format, and so on.

Resources

Releases – release notes and project news.
Downloads – obtain the newest release package.
Reference – API documentation for source code.
Source code – obtain via Darcs 2 or browse online.

To get help or provide feedback, simply contact the author.

Chapter 1
Introduction

Gerbil is an extensible document generator based on eRuby that outputs to any format you want: HTML (web page), LaTeX, UNIX man page, plain text, your own custom format, and so on.

Gerbil is light and flexible against DocBook, Deplate, and SiSU because it is tiny (less than 200 lines!) and it lets you define your own custom format. Furthermore, Gerbil is scriptable unlike raw text generators such as AsciiDoc, txt2tags, and Grutatxt because it lets you inject Ruby code directly into your documents for dynamic content generation.

Gerbil is open-source software (see Section 1.2. License) so feel free to contribute your improvements and discuss your ideas with the author. You can obtain the source code from the project Darcs repository by running the following command:

darcs get http://gerbil.rubyforge.org/src gerbil

In addition, you can monitor for changes to the above repository by subscribing to this news feed.

Note 1. See the source of this guide

Did you know that this user guide was generated by Gerbil? Here is the source document to prove it!

1.1 Features

Composed of less than 200 lines of code!
Lets you define your own document format.
Supports any text-based output format.
Generates a table of contents automatically.

1.2 License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

All copies and substantial portions of the Software (the "Derivatives") and their corresponding machine-readable source code (the "Code") must include the above copyright notice and this permission notice.

Upon distribution, the Derivatives must be accompanied by either the Code or—provided that the Code is obtainable for no more than the cost of distribution plus a nominal fee—information on how to obtain the Code.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

1.3 Reviews

I actually felt like printing it [this user guide], because it’s just so well-thought typographically… Even if it [Gerbil] weren’t great by itself, I’d feel good just looking at the manual [this user guide].

—Vitor Peres in ruby-talk

[this user guide is] a insanely complete and nice looking bit of documentation [... Gerbil] looks like a great project

—Ara T. Howard in ruby-talk

Very nice work indeed!

—Martin DeMello in ruby-talk

Chapter 2
Setup

2.1 Requirements

Your system needs the following software to run Gerbil.

Software	Notes
Ruby	Version 1.8.x is required.
RedCloth	Required by the default HTML format.
CodeRay	Required by the default HTML format.

If your system has RubyGems, then you can install RedCloth and CodeRay by running the following command:

gem install RedCloth coderay

2.2 Installation

If your system has RubyGems, then you can install Gerbil by running the following commands:

gem install gerbil
gerbil -v

Otherwise, follow these instructions:

Download the newest release package from the download area.
Extract the release package anywhere you want on your system.
Go inside the extracted directory and run the following command:

ruby bin/gerbil -v

If the installation was successful, then you will see output like this:

Gerbil 3.1.0 (2008-06-22) http://gerbil.rubyforge.org /home/sun/src/gerbil

Otherwise, you can contact the author for help.

2.3 Manifest

Now that Gerbil is installed on your system, let us examine its installation directory.

If you installed Gerbil manually, then you already know the location of its installation directory.
If you installed Gerbil using RubyGems, then run
```
gerbil -v
```
and select the right-most item in the output—that is the path of Gerbil’s installation directory.

Inside Gerbil’s installation directory, you will see (among other things) the following items:

bin/ – contains executable programs.
- gerbil – the main source code of Gerbil.
fmt/ – contains the predefined set of format specification files (see Section 3.2. Format specification file). If you ever need to install your custom format specification file globally, put it inside this directory.
- latex.yaml – high-quality typesetting
- html.yaml – web page for the Internet
- man.yaml – manual page for UNIX
- text.yaml – plain text, nothing fancy
lib/ – Gerbil automatically adds this directory to Ruby’s load path.
- gerbil.rb – project version information.
- gerbil/
  - html.rb – provides the String#to_html method.
  - rdoc.rb – provides RDoc parse trees to Ruby code.
doc/ – contains the user guide and other documentation.
- gerbil.svg – the source file of the Gerbil logo.
- guide.erb – the source file of this user guide.
- api/ – contains API reference documentation for the provided Ruby code.
LICENSE – the project license and copyright notice.

2.4 Version numbering system

Gerbil uses the RubyGems rational versioning policy to number its releases. This major.minor.patch numbering policy is summarized as follows.

Version number components:	Major	Minor	Patch
Backwards compatible?	no	yes	yes
New features?	yes	yes	no
Bug fixes?	yes	yes	yes

Chapter 3
Theory of operation

When you run Gerbil, it operates in the following order:

loads the format specification file
creates an input document by:
- reading the input (the content of either the input file or the standard input stream) into memory
- evaluating include directives in the input
transforms the input document into a processed document by:
- building a “document tree” data-structure from nodes present in the input document
- replacing every node in the input document with the result of its node output template
transforms the processed document into an output document according to the document output template
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). This distinction helps us talk about the document in a particular state because the content of the document changes radically with every transformation—thus it would be ambiguous to say “the input document” all the time.

3.1 Nodes

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, ... %>

Technically, what you see above is really a method invocation made up of the following components:

Component	Description
node_type	name of the method being invoked
node_argument1, node_argument2, ...	arguments for the method invocation
node_content	a block argument being passed to the method invocation
node_object	a `Node` object (see Section 3.1.1. The `Node` class) representing this method invocation

A format specification file defines what types of nodes an input document may use.

3.1.1 The `Node` class

When Gerbil builds a document tree from nodes present in an input document, it stores information about these nodes into Node objects. A Node object has the following properties (methods):

Property	Type	Description
type	String	Name of the type of this node.
args	Array	Arguments passed to this node.
content	String	The block of text passed to this node.
output	String	Result of the node output template for the content of this node.
digest	String	A unique identifier for the content of this node.
trace	Array	A stack trace describing the location of this node in the input document.
index	String	A LaTeX-style section number for this node. This property is only present if the “index” parameter is enabled in the definition of this type of node.
number	Integer	An order-of-occurrence number for this node. This property is only present if the “number” parameter is enabled in the definition of this type of node.
depth	Integer	Distance from the root of the document tree to this node.
parent	`Node`	The `Node` object which contains this node. The value of this property will be `nil` if this node is a root of the document tree.
children	Array of `Node`	List of child nodes from the document tree.

Furthermore, the Node class is derived from Ruby’s OpenStruct class, so you can define new properties for Node objects dynamically.

3.2 Format specification file

A format specification file is a plain-text file marked up in YAML syntax. 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 Gerbil executable, so any file-system or path-dependent portions of this source code should take appropriate precautions.
nodes	Hash	A listing of node definitions.
output	String	An eRuby template for the final output document. See Section 3.2.2. Document output template.

3.2.1 Node definition

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 Section 3.2.1.1. Node output template.

You may define additional parameters in a node definition if you want.

3.2.1.1 Node output template

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, Gerbil 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	`Node`	the node for which this template is being evaluated
@roots	Array of `Node`	All root nodes in the document tree.
@nodes	Array of `Node`	All nodes in the document tree.
@types	Hash	Mapping from node type (String) to array of `Node` objects having that type.
@spec	Hash	Data from the format specification file.

Gerbil 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.

3.2.2 Document output template

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.
@roots	Array of `Node`	All root nodes in the document tree.
@nodes	Array of `Node`	All nodes in the document tree.
@types	Hash	Mapping from node type (String) to array of `Node` objects having that type.
@spec	Hash	Data from the format specification file.

Gerbil 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.

3.2.3 Creating your own custom format

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 Example 1. HelloWorld format specification file and make use of it in the Example 2. Input document for HelloWorld format. This shows how to provide format-specific functionality to an input document.
We define a $style variable in Example 2. Input document for HelloWorld format and make use of it in Example 1. HelloWorld format specification file. This shows how to make your format accept parameters from an input document.

To run this example, perform the following steps:

Save the code shown in Example 1. HelloWorld format specification file to a file named HelloWorld.spec
Save the text shown in Example 2. Input document for HelloWorld format to a file named HelloWorld.input

Run this command:

gerbil HelloWorld.spec HelloWorld.input > HelloWorld.output

Examine the HelloWorld.output file until you are satisfied!

Example 1. HelloWorld format specification file

desc: An example format.

code: |
  # Returns a random, yet pronounceable, name.
  def generate_name
    letters = ('a'..'z').to_a - %w[ c q w x ] # redundant sounds
    vowels = %w[a e i o u]
    consonants = letters - vowels
    sets = [consonants, vowels]

    length = 3 + rand(5)

    name = (0...length).map do |i|
      # alternate between consonants and vowels
      set = sets[i % sets.length]

      # choose a random letter from the set
      set[rand(set.length)]
    end.join

    name
  end

  class Node
    def name
      # dynamically compute (and store)
      # the name of this node on demand
      @name ||= generate_name
    end
  end

nodes:
  hello:
    index: true
    number: true
    silent: false
    output: |
      <h3><%= @node.type %> #<%= @node.index %>: <%= @node.name.inspect %></h3>

      My name is <%= @node.name.inspect %> and these are my properties:

      <dl style="<%= $style %>">
        <dt>args</dt>
        <dd><code><%= @node.args.inspect %></code></dd>

        <dt>index</dt>
        <dd><code><%= @node.index.inspect %></code></dd>

        <dt>number</dt>
        <dd><code><%= @node.number.inspect %></code></dd>

        <dt>trace</td>
        <dd><pre><%= @node.trace.join("\n") %></pre></dd>

        <dt>content</dt>
        <dd><%= @node.content %></dd>
      </dl>

output: |
  Welcome to the "<%= @spec[:name] %>" format.
  <%= @content %>
  That's all folks!

Example 2. Input document for HelloWorld format

<% $style = "border-left: thick dotted LightGrey; padding-left: 1em;" %>
<% hello "Pretentious", 1, 2, 3 do %>
  <big>I'm</big> the very first node, oh _yes_ I am! *sneer*

  <% hello "Bashful", 4, 5, 6 do %>
    Hi, I... *hide*

    <% hello "Hopeful", rand do %>
      *sigh*

      <% hello "Confused", (rand * rand) do %>
        Huh?
      <% end %>
    <% end %>

    <% hello "Raving", __FILE__ do %>
      Oh it's *on* now! You're going *down*!
    <% end %>
  <% end %>

  <% hello "Sleepy", Time.now do %>
    *yawn* Just five more minutes...

    <% hello "Peaceful", Dir.pwd do %>
      So _be_ happy my friend, *happy*!

      <%= hello "Lonely (as you can see, I have no block)" %>
    <% end %>
  <% end %>
<% end %>

<% hello "Snappy" do %>
  Zip! Zap! Wake up, you sap!
  _Whoo I'm wild!_ ;-)
<% end %>

<%= hello "Independent (no block, no parents, I am _free_!)" %>

Example 3. Output of HelloWorld format

Welcome to the “HelloWorld” format.

hello #1: “fosi”

My name is “fosi” and these are my properties:

args

["Pretentious", 1, 2, 3]

index

"1"

number

1

trace

INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

I’m the very first node, oh yes I am! sneer

hello #1.1: “ropup”

My name is “ropup” and these are my properties:

args

["Bashful", 4, 5, 6]

index

"1.1"

number

2

trace

INPUT:3
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

Hi, I… hide

hello #1.1.1: “vuzat”

My name is “vuzat” and these are my properties:

args

["Hopeful", 0.204484086900208]

index

"1.1.1"

number

3

trace

INPUT:5
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:3
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

sigh

hello #1.1.1.1: “siji”

My name is “siji” and these are my properties:

args

["Confused", 0.213170376406466]

index

"1.1.1.1"

number

4

trace

INPUT:7
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:5
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:3
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

Huh?

hello #1.1.2: “dot”

My name is “dot” and these are my properties:

args

["Raving", "INPUT"]

index

"1.1.2"

number

5

trace

INPUT:9
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:3
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

Oh it’s on now! You’re going down!

hello #1.2: “mufo”

My name is “mufo” and these are my properties:

args

["Sleepy", Sun Jun 22 17:21:51 -0700 2008]

index

"1.2"

number

6

trace

INPUT:11
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

yawn Just five more minutes…

hello #1.2.1: “bikofab”

My name is “bikofab” and these are my properties:

args

["Peaceful", "/home/sun/src/gerbil"]

index

"1.2.1"

number

7

trace

INPUT:13
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:11
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

So be happy my friend, happy!

hello #1.2.1.1: “nebo”

My name is “nebo” and these are my properties:

args

["Lonely (as you can see, I have no block)"]

index

"1.2.1.1"

number

8

trace

INPUT:15
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:13
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:11
bin/gerbil:79:in `content_from_block'
bin/gerbil:249:in `hello'
INPUT:1
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

hello #2: “hazeh”

My name is “hazeh” and these are my properties:

args

["Snappy"]

index

"2"

number

9

trace

INPUT:17
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

Zip! Zap! Wake up, you sap! Whoo I’m wild! ;-)

hello #3: “jipater”

My name is “jipater” and these are my properties:

args

["Independent (no block, no parents, I am _free_!)"]

index

"3"

number

10

trace

INPUT:20
bin/gerbil:268
bin/gerbil:268:in `instance_eval'
bin/gerbil:268

content

That’s all folks!

Chapter 4
Usage

Gerbil is an extensible document generator based on eRuby.

STDIN will be read if no input files are specified.

If an error occurs, the input document will be printed to STDOUT so you can investigate line numbers in the error’s stack trace. Otherwise, the final output document will be printed to STDOUT.

Usage: gerbil [Option…] Format|SpecFile [InputFile…]

Option:

`-h`, `--help`	show usage information
`-v`, `--version`	show version information
`-u`, `--unindent`	unindent node content

Format:

latex	high-quality typesetting
html	web page for the Internet
man	manual page for UNIX
text	plain text, nothing fancy

Gerbil requires its first command-line argument to be either (1) the name of a predefined format or (2) the path to a format specification file. Predefined formats are simply short-hand names of format specification files located in the fmt/ subdirectory of the Gerbil installation directory (see Section 2.3. Manifest).

4.1 The include directive

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 path #>

Here, path 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.

Part 5
Formats

This section describes the default formats provided along with Gerbil. The format specification files (see Section 3.2. Format specification file) for these formats can be found in the fmt/ directory of the Gerbil installation directory (see Section 2.3. 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 contact the author.

Chapter 5.1
HTML

This format generates a monolithic HTML (technically, it’s XHTML 1.0 transitional, but who’s counting?) document. A monolithic HTML document allows users to easily search for a particular topic using nothing more than their web browser’s built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.

In the HTML document, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate the HTML document, especially for users of text-only web browsers.

Furthermore, the HTML document comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the Mozilla and Opera family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the “print preview” function of a graphical web browser to see how the HTML document will appear when printed.

5.1.1 Text to HTML conversion

Inside the fmt/ subdirectory of the Gerbil installation directory (see Section 2.3. Manifest), you will see a html.rb file. This file defines a String.to_html method which is used to transform text in an input document into HTML.

The default implementation of the String.to_html method is based on the Textile markup system. If you do not like Textile or wish to use a different markup system for text in your documents, then simply edit the html.rb file and adjust the source code of the default String.to_html method accordingly.

For example, if you replace the entire html.rb file with the following code, then the output of all nodes will appear within red boxes in the final output document.

class String
  def to_html
    '<p style="border: thin solid red">' + self + '</p>'
  end
end

In addition to supporting Textile markup, the default implementation has some additional features which are described in the following subsections.

5.1.1.1 Syntax coloring for source code

Syntax coloring is automatically added to source code found inside the <code> and </code> HTML tags. Note that in Textile, any text enclosed within a pair of at-signs (@ and @) is also considered to be source code.

The following programming languages are currently supported by CodeRay:

Ruby
C
Delphi
HTML
RHTML (Rails)
Nitro-XHTML

5.1.1.1.1 Specifying the programming language

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.

For example, here is some source code without the lang attribute:

# 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>

And here is the same source code with a lang="c" attribute:

# 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>

And here is the same source code with a lang="html" attribute:

# 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>

5.1.1.2 Smart sizing of source code

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 of code:

life = true or false

And here is a paragraph of code:

life =
true or false

5.1.1.3 Protecting verbatim text

Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process . In such cases, you can wrap the text you want to proctect within <noformat> and </noformat> tags.

5.1.2 Parameters

The HTML format accepts the following document parameters.

Parameter	Type	Default value	Description
`$title`	String	`"$title"`	Title of the document.
`$authors`	Hash	`{"$authors" => nil}`	A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided `String#to_html_entities` method like this: `{ "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_html_entities }`
`$date`	String	`Time.now.strftime("%d %B %Y")`	Date when the document was written.
`$logo`	String	`nil`	Arbitrary content that goes above the document title in the default header.
`$feeds`	Hash	`nil`	A mapping of feed URL to feed format. Here is an example: `$feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" }`
`$use_icons`	Boolean	`true`	Use Tango icons in admonitions (see Section 5.1.4.3. Admonitions)?

5.1.3 Methods

The HTML 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.

Method declaration	Description
`Node#title()`	Returns the user-defined title for this node‘s content.
`Node#id()`	Returns the user-defined indentifer for this node.
`Node#url()`	Returns a unique URI fragment for this node.
`Node#list_url()`	Returns the URI fragment for the location in the table of contents / list of figures that points this node.
`Icon#css_class()`	Returns the CSS class for this icon.
`Hash#to_html_atts()`	Transforms this hash into a string of HTML attribute key=value pairs.
`String#to_html_entities()`	Transforms this UTF-8 string into HTML entities.
`String#to_uri_fragment()`	Transforms this string into a valid URI fragment. See www.nmt.edu/tcc/help/pubs/xhtml/id-type.html
`String#to_html()`	Transforms this string into HTML.
`String#thru_redcloth()`	Returns the result of running this string through RedCloth.
`String#thru_coderay()`	Adds syntax coloring to <code> elements in the given text. If the <code> tag has an attribute lang="…", then that is considered the programming language for which appropriate syntax coloring should be applied. Otherwise, the programming language is assumed to be ruby.

Chapter 5.1.4
Nodes

Unless otherwise noted, all nodes defined by the HTML format accept two arguments, in this order:

a required title for the node
an optional unique identifier for the node

The second argument is used by the cross-referencing nodes (see Section 5.1.4.1.4. xref and Section 5.1.4.5.2. cite), which allow you to refer to another node in the document by its unique identifier.

Furthermore, node definitions in the HTML 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)?

5.1.4.1 Structure

The nodes described in this section form the overall structure of the output document.

5.1.4.1.1 header

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.

5.1.4.1.2 footer

This node overrides (1) the date when this document was generated and (2) the hyperlink to the Gerbil website, shown at the bottom of the document. The hyperlink is there as a way of saying thanks for Gerbil, the wonderful little utility you have grown so fond of! ;-)

5.1.4.1.3 abstract

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! :-(

5.1.4.1.4 xref

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: Section 3.2. Format specification file.

As another example, this node in the input document:

<%= xref "SpecFile", "custom link text" %>

appears in the output document like this: custom link text.

5.1.4.2 Organization

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).

5.1.4.2.1 part

A collection of chapters.

Part 5.1.4.2.1.1
An example

This is how a part node appears.

5.1.4.2.2 chapter

A collection of sections.

Chapter 5.1.4.2.2.1
An example

This is how a chapter node appears.

5.1.4.2.3 section

A collection of paragraphs about a particular topic.

5.1.4.2.3.1 An example

This is how a section node appears.

5.1.4.2.4 paragraph

A collection of sentences about a particular idea.

An example

This is how a paragraph node appears. Notice that there is no LaTeX-style index number in the heading of this paragraph node.

5.1.4.3 Admonitions

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^[1] when determining which admonition to use in my documents.

5.1.4.3.1 warning

Use a warning node when “data loss could occur if you follow the procedure being described.” ^[1]

Warning 1. An example

This is how a warning node appears.

5.1.4.3.2 caution

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. ^[1]

Caution 1. An example

This is how a caution node appears.

5.1.4.3.3 important

Use an important node when:

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.) ^[1]

Important 1. An example

This is how a important node appears.

5.1.4.3.4 note

Use a note node to convey:

Information the user should be aware of, but is peripheral to the actual task being described. ^[1]

Note 2. An example

This is how a note node appears.

5.1.4.3.5 tip

Use a tip node when:

When you’re giving a hint to make things easier or more productive for the reader. ^[1]

Tip 1. An example

This is how a tip node appears.

5.1.4.4 Auxilary materials

5.1.4.4.1 figure

A diagram, sketch, image, or illustration; something that visually depicts an idea or thought.

Figure 1. An example

This is how a figure node appears.

5.1.4.4.2 table

Information (typically measurement data) represented in tabular form for easy reading, comparison, and analysis.

Table 1. An example

This is how a table node appears.

5.1.4.4.3 example

A sample application of an idea or thought.

Example 4. An example

This is how a example node appears.

5.1.4.4.4 equation

A mathematical equation or formula.

Equation 1. An example

This is how a equation node appears.

5.1.4.4.5 procedure

An outline; a series of steps outlining some kind of process.

Procedure 1. An example

This is how a procedure node appears.

5.1.4.5 Bibliography

The nodes in this section deal with attribution of ideas—an important weapon against plagiarism.

5.1.4.5.1 reference

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 Section 5.1.4.5.2. cite) to perform the citation.

An example

See Reference 2 for an example of how a reference node appears.

5.1.4.5.2 cite

A citation to a reference node (see Section 5.1.4.5.1. reference) in the document’s bibliography.

The first argument of this node is the unique identifier of the reference node you wish to cite. You can specify additional arguments to give more detail about the citation.

For example, this node in the input document:

<%= cite "html.nodes.reference.example" %>

appears in the output document like this: ^[2]

As another example, this node in the input document:

<%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>

appears in the output document like this: ^{[2, chapter 10, page 53, ...]}

Chapter 5.2
Plain text

This format is not yet implemented.

http://en.wikipedia.org/wiki/Plain_text

Chapter 5.3
LaTeX

This format is not yet implemented.

http://www.latex-project.org

Chapter 5.4
UNIX man page

This format is not yet implemented.

http://en.wikipedia.org/wiki/Man_page

22 June 2008

Chapter 1 Introduction

Chapter 2 Setup

Chapter 3 Theory of operation

hello #1: “fosi”

hello #1.1: “ropup”

hello #1.1.1: “vuzat”

hello #1.1.1.1: “siji”

hello #1.1.2: “dot”

hello #1.2: “mufo”

hello #1.2.1: “bikofab”

hello #1.2.1.1: “nebo”

hello #2: “hazeh”

hello #3: “jipater”

Chapter 4 Usage

Part 5 Formats

Chapter 5.1 HTML

Chapter 5.1.4 Nodes

Part 5.1.4.2.1.1 An example

Chapter 5.1.4.2.2.1 An example

Chapter 5.2 Plain text

Chapter 5.3 LaTeX

Chapter 5.4 UNIX man page

Chapter 1
Introduction

Chapter 2
Setup

Chapter 3
Theory of operation

Chapter 4
Usage

Part 5
Formats

Chapter 5.1
HTML

Chapter 5.1.4
Nodes

Part 5.1.4.2.1.1
An example

Chapter 5.1.4.2.2.1
An example

Chapter 5.2
Plain text

Chapter 5.3
LaTeX

Chapter 5.4
UNIX man page