Gerbil 2.0.0 user guide

03 February 2008 · License

darcs get http://gerbil.rubyforge.org/src gerbil
gem install RedCloth coderay
gem install gerbil
gerbil -v
ruby bin/gerbil -v
Gerbil 2.0.0 (2008-02-03) http://gerbil.rubyforge.org /home/sun/src/gerbil

gerbil -v
bin/
gerbil
fmt/
latex.yaml
html.yaml
man.yaml
text.yaml
lib/
gerbil.rb
gerbil/
html.rb
rdoc.rb
doc/
gerbil.svg
guide.erb
api/
LICENSE
<% node_type node_argument1, node_argument2, ... do |node_object| %>
  node_content
<% end %>
<% node_type node_argument1, node_argument2, ... do %>
  node_content
<% end %>
<%= node_type node_argument1, node_argument2, ... %>
HelloWorld.spec
HelloWorld.input
gerbil HelloWorld.spec HelloWorld.input > HelloWorld.output
HelloWorld.output
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_!)" %>

Gerbil is an extensible document generator based on eRuby.

* STDIN will be read if an input file is not 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

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

format/
<%# include path %>
<% $unindent = "\t  " %>
format/
format/
html.rb
html.rb
html.rb
class String
  def to_html
    '<p style="border: thin solid red">' + self + '</p>'
  end
end

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

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

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

life =
true or false
<%= xref "SpecFile" %>
<%= xref "SpecFile", "custom link text" %>
<%= cite "html.nodes.reference.example" %>
<%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>

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

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

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.

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.

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.

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

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.

Expression	Type	Description
`@spec[:name]`	String	Short-hand name of the current format.
`@spec[:file]`	String	Path of the current format specification file.

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.

Property	Value
args	[“Snappy”]
index	“2”
number	9
trace	INPUT:17 bin/gerbil:238 bin/gerbil:238:in `instance_eval’ bin/gerbil:238
content	Zip! Zap! Wake up, you sap! Whoo I’m wild! ;-)

Property	Value
args	[“Independent (no block, no parents, I am free!)”]
index	“3”
number	10
trace	INPUT:20 bin/gerbil:238 bin/gerbil:238:in `instance_eval’ bin/gerbil:238
content

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

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#to_html(aAttributes = {})`	Returns a HTML image tag containing embedded image data. The given attributes (name => value) are applied to the HTML tag declaration.
`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.

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

Gerbil 2.0.0 user guide

Suraj N. Kurapati

03 February 2008

Contents

Cautions

Equations

Examples

Figures

Importants

Notes

Procedures

Tables

Tips

Warnings

Chapter 1 Introduction

1.1 Features

1.2 License

1.3 Resources

1.4 Testimonials

Chapter 2 Setup

2.1 Requirements

2.2 Installation

2.3 Manifest

2.4 Version numbering system

Chapter 3 Theory of operation

3.1 Nodes

3.1.1 The Node class

3.2 Format specification file

3.2.1 Node definition

3.2.1.1 Node output template

3.2.2 Document output template

3.2.3 Creating your own custom format

hello #1: “nok”

hello #1.1: “dibisom”

hello #1.1.1: “loti”

hello #1.1.1.1: “bukeyam”

hello #1.1.2: “vukuy”

hello #1.2: “numose”

hello #1.2.1: “dazan”

hello #1.2.1.1: “yed”

hello #2: “zehun”

hello #3: “gijoju”

Chapter 4 Usage

4.1 The include directive

4.2 The $unindent variable

Part 5 Formats

Chapter 5.1 HTML

5.1.1 Text to HTML conversion

5.1.1.1 Syntax coloring for source code

5.1.1.1.1 Specifying the programming language

5.1.1.2 Smart sizing of source code

5.1.1.3 Protecting verbatim text

5.1.2 Parameters

5.1.3 Methods

Chapter 5.1.4 Nodes

5.1.4.1 Structure

5.1.4.1.1 header

5.1.4.1.2 footer

5.1.4.1.3 abstract

5.1.4.1.4 xref

5.1.4.2 Organization

5.1.4.2.1 part

Part 5.1.4.2.1.1 An example

5.1.4.2.2 chapter

Chapter 5.1.4.2.2.1 An example

5.1.4.2.3 section

5.1.4.2.3.1 An example

5.1.4.2.4 paragraph

5.1.4.3 Admonitions

5.1.4.3.1 warning

5.1.4.3.2 caution

5.1.4.3.3 important

5.1.4.3.4 note

5.1.4.3.5 tip

5.1.4.4 Auxilary materials

5.1.4.4.1 figure

5.1.4.4.2 table

5.1.4.4.3 example

5.1.4.4.4 equation

5.1.4.4.5 procedure

Chapter 1
Introduction

Chapter 2
Setup

Chapter 3
Theory of operation

3.1.1 The `Node` class

Chapter 4
Usage

4.2 The `$unindent` variable

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