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

Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>

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.

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

Your system needs the following software to run Gerbil.

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

gem install RedCloth coderay

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

gem install gerbil
gerbil -v

1. Download the newest release package from the download area.
2. Extract the release package anywhere you want on your system.
3. 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.0.2 (2008-06-08) http://gerbil.rubyforge.org /home/sun/src/gerbil

Otherwise, you can contact the author for help.

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

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

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:

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

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.

desc: A illustrative format.

code: |
  # Returns a random, but 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 = ''
    length.times do |i|
      set = sets[i % sets.length]
      name << set[rand(set.length)]
    end

    name
  end

  class Node
    def name
      @name ||= generate_name
    end
  end

nodes:
  hello:
    index: true
    number: true
    silent: false
    output: |
      <h1><%= @node.type %> #<%= @node.index %>: <%= @node.name.inspect %></h1>
      My name is <%= @node.name.inspect %> and these are my properties:
      <table>
        <tr>
          <th>Property</th>
          <th>Value</th>
        </tr>
        <tr>
          <td>args</td>
          <td><%= @node.args.inspect %></td>
        </tr>
        <tr>
          <td>index</td>
          <td><%= @node.index.inspect %></td>
        </tr>
        <tr>
          <td>number</td>
          <td><%= @node.number.inspect %></td>
        </tr>
        <tr>
          <td>trace</td>
          <td><ul><%= @node.trace.map {|s| "<li>#{s}</li>"} %></ul></td>
        </tr>
        <tr>
          <td>content</td>
          <td><%= @node.content %></td>
        </tr>
      </table>

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

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

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

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

      <% hello "Confused" do %>
        Huh?
      <% end %>
    <% end %>

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

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

    <% hello "Peaceful" 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_!)" %>

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.