Chapter 1
Introduction

ERBook is an extensible document processor that emits any document you can imagine from eRuby templates, which allow scripting and dynamic content generation.

What’s new? — history of project releases.
Source code — obtain via Git or browse online.
API reference — documentation for source code.
Project home — the ERBook project home page.

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

Features
License
Credits
Reviews
Related works

1.1 Features

ERBook is exciting because:

Its documents are scriptable eRuby templates.
It lets you define your own document formats.
It emits beautiful XHTML (web page) documents.
It consists of a mere 445 lines of code.

Note 1. More document formats are planned

LaTeX (PDF), UNIX manual page, and plain text document formats are planned for future releases… patches are welcome!

1.2 License

(the ISC license)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

1.3 Credits

The “erbook.png” image and its “erbook.svg” source utilize the “cartoon owl sitting on a book” graphic, which was created and released into the public domain by Jens Vierbuchen on July 7, 2008.

ERBook is made possible by contributions from users like you:

Jens Vierbuchen
Maunika Gosike
Zhang Chiyuan

1.4 Reviews

Tom Cloyd in ruby-talk:

This documentation is simply gorgeous!

Vitor Peres in ruby-talk:

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

Ara T. Howard in ruby-talk:

[This manual is] a insanely complete and nice looking bit of documentation [… ERBook] looks like a great project

Martin DeMello in ruby-talk:

Very nice work indeed!

Chapter 2
Setup

Requirements
Installation
Package contents
Version numbers

2.1 Requirements

Your system needs the following software to run ERBook.

Software	Description	Notes
Ruby	Ruby language interpreter	Version 1.8.7 and 1.9.1 have been tested successfully.
RubyGems	Ruby packaging system	Version 1.3.5 or newer is required.

2.2 Installation

You can install ERBook by running this command:

gem install erbook

To check whether the installation was sucessful, run this command:

erbook --version

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

project: ERBook
version: 9.2.0
release: 2009-11-06
website: http://snk.tuxfamily.org/lib/erbook/
install: /home/sun/src/erbook

If you do not see such output, you may ask the author(s) for help.

2.3 Package contents

You will see the following items inside ERBook’s installation directory, whose path you can determine by running this command:

erbook --version

bin/
- erbook — the main ERBook executable.
fmt/ — contains the predefined set of format specification files. If you ever need to install your custom format specification file globally, then put it inside this directory.
- latex.yaml — high-quality typesetting
- man.yaml — manual page for UNIX
- xhtml.yaml — web page for the Internet
- text.yaml — plain text, nothing fancy
lib/
- erbook.rb — the main ERBook library.
- erbook/
  - to_xhtml.rb — implements Text to XHTML conversion methods for the XHTML (web page) format.
  - rdoc.rb — provides RDoc parse trees to Ruby code.
doc/
- api/ — API reference documentation.
- erbook.svg — source file of the ERBook logo.
- index.erb — source file of this manual.
LICENSE — copyright notice and legal conditions.
CREDITS — attribution of project contributors.

2.4 Version numbers

ERBook releases are numbered in major.minor.patch form according to the RubyGems rational versioning policy, which can be summarized as follows:

What increased in the version number?	Is backward compatible?	Has new features?	Has bug fixes?
What increased in the version number?	The increase indicates that the release:
major	No	Yes	Yes
minor	Yes	Yes	Yes
patch	Yes	No	Yes

Chapter 3
Theory

When you run ERBook, it does the following:

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.
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; because the content of the document changes radically with every transformation.

Nodes
Format specification file

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

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 The `ERBook::Document::Node` class) representing this method invocation.

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

The ERBook::Document::Node class

3.1.1 The `ERBook::Document::Node` class

When ERBook 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.
definition	`Hash`	The definition of this type of node, taken directly from the format specification file.
arguments	`Array`	Arguments passed to this node.
backtrace	`Array`	A stack trace describing the location of this node in the input document.
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.
depth	`Integer`	Distance from the root of the document tree to this node.
section_number	`String`	A LaTeX-style section number for this node. This property is only present if enabled in the number parameter in the definition of this type of node.
ordinal_number	`Integer`	An order-of-occurrence number for this node. This property is only present if enabled in the number parameter in the definition of this type of 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.

Furthermore, the ERBook::Document::Node class is derived from Ruby’s OpenStruct class, so you can define additional properties for ERBook::Document::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 ERBook 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 Document output template.

Node definition
Document output template
Creating your own document format

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
params	`String` or `Array` thereof	List of parameters that are expected to be specified during an instantiation of node. Any additional arguments passed during instantiation are stored in the `arguments` attribute of the resulting `ERBook::Document::Node` object.
number	`String` or `Array` thereof	When “ordinal”, assign an order of occurrence number to this node. When “section”, assign a LaTeX-style section number to this node. Both choices can be specified simultaneously.
inline	Boolean	Is node’s output an in-line string of text that can be embedded anywhere in the document?
silent	Boolean	Suppress the output of this node at the location it is instantiated?
output	`String`	An eRuby template for the content of this node. See Node output template.

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

Node output template

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, ERBook replaces all nodes in the input document with the result of this template unless the silent parameter is enabled in this node’s definition.

The following variables are available for use in this template:

Variable	Type	Description
`@node`	`ERBook::Document::Node`	The node for which this template is being evaluated.
`@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.

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

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

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

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

To run this example:

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

Run this command:

erbook HelloWorld.spec HelloWorld.input > HelloWorld.output

Examine the HelloWorld.output file to your satisfaction!

Example 1. HelloWorld format specification file

desc: An example format.

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

    private

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

nodes:
  hello:
    number: [section, ordinal]
    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>arguments</dt>
        <dd><code><%= @node.arguments.inspect %></code></dd>

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

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

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

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

output: |
  Welcome to the "<%= @format[:name] %>" format.

  <%= @content %>

  That's all folks!

Example 2. Input document for HelloWorld format

Note that this input document uses the shorthand eRuby directive syntax and the implicit <% end %> inference features of the Ember eRuby template processor.

% $style = "border-left: thick dotted #D3D3D3; padding-left: 1em;"

%|hello "Pretentious", 1, 2, 3
  <big>I'm</big> the very first node, oh _yes_ I am! *sneer*

  %|hello "Bashful", 4, 5, 6
    Hi, I... *hide*

    %|hello "Hopeful", rand
      *sigh*

      %|hello "Confused", (rand * rand)
        Huh?

    %|hello "Raving", __FILE__
      Oh it's *on* now! You're going *down*!

  %|hello "Sleepy", Time.now
    *yawn* Just five more minutes...

    %|hello "Peaceful", Dir.pwd
      So _be_ happy my friend, *happy*!

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

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

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

Example 3. Output of HelloWorld format

Welcome to the “HelloWorld” format.

hello #: "dunam"

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

arguments

["Pretentious", 1, 2, 3]

section_number

"1"

ordinal_number

1

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

I'm the very first node, oh _yes_ I am! *sneer*

hello #: "sevoho"

My name is "sevoho" and these are my properties:

arguments

["Bashful", 4, 5, 6]

section_number

"1.1"

ordinal_number

2

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:6:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

Hi, I... *hide*

hello #: "fun"

My name is "fun" and these are my properties:

arguments

["Hopeful", 0.114673811645093]

section_number

"1.1.1"

ordinal_number

3

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:9:in `block (2 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:6:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

*sigh*

hello #: "kiyu"

My name is "kiyu" and these are my properties:

arguments

["Confused", 0.000711486163954973]

section_number

"1.1.1.1"

ordinal_number

4

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:12:in `block (3 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:9:in `block (2 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:6:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

Huh?

hello #: "jusijoj"

My name is "jusijoj" and these are my properties:

arguments

["Raving", "doc/HelloWorld.input"]

section_number

"1.1.2"

ordinal_number

5

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:15:in `block (2 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:6:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

Oh it's *on* now! You're going *down*!

hello #: "bubusa"

My name is "bubusa" and these are my properties:

arguments

["Sleepy", 2009-11-07 00:02:01 -0800]

section_number

"1.2"

ordinal_number

6

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:18:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

*yawn* Just five more minutes...

hello #: "zuyolan"

My name is "zuyolan" and these are my properties:

arguments

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

section_number

"1.2.1"

ordinal_number

7

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:21:in `block (2 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:18:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

So _be_ happy my friend, *happy*!

hello #: "filebul"

My name is "filebul" and these are my properties:

arguments

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

section_number

"1.2.1.1"

ordinal_number

8

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:24:in `block (3 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:21:in `block (2 levels) in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:18:in `block in render'
/home/sun/src/erbook/lib/erbook/template.rb:107:in `__block_content__'
/home/sun/src/erbook/lib/erbook/document.rb:140:in `__node_handler__'
/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:3:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

hello #: "jihe"

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

arguments

["Snappy"]

section_number

"2"

ordinal_number

9

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:26:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

Zip! Zap! Wake up, you sap! _Whoo I'm wild!_ ;-)

hello #: "salugo"

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

arguments

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

section_number

"3"

ordinal_number

10

backtrace

/home/sun/src/erbook/lib/erbook/document.rb:156:in `hello'
doc/HelloWorld.input:30:in `render'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `eval'
/usr/lib/ruby/gems/1.9.1/gems/ember-0.0.1/lib/ember/template.rb:88:in `render'
/home/sun/src/erbook/lib/erbook/template.rb:58:in `render'
/home/sun/src/erbook/lib/erbook/document.rb:162:in `initialize'
bin/erbook:52:in `new'
bin/erbook:52:in `<main>'

content

That’s all folks!

Chapter 4
Usage

Command-line interface

4.1 Command-line interface

When you run this command:

erbook --help

You will see this output:

ERBook - Write books, manuals, and documents in eRuby

* The standard input stream will be read if an input file is not specified.

* The final output document will be written to the standard output stream.

* If an error occurs, the input document will be written to the standard
  output stream, so that you can investigate line numbers in the error.

Usage:

  erbook [Options] FormatName [InputFile]
  erbook [Options] FormatFile [InputFile]

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

Options:
    --unindent, -u:   Unindent node content hierarchically
      --manual, -m:   Show the user manual
  --locale, -l <s>:   Set preferred language
     --version, -v:   Print version and exit
        --help, -h:   Show this message

The first command-line argument to ERBook is either the name of a predefined format (FormatName) or the path to a format specification file (FormatFile).

Predefined formats are simply short-hand names of format specification files located in the fmt/ subdirectory of the ERBook installation directory (see Package contents).

Saving the output to a file
Unindenting nodes hierarchically

4.1.1 Saving the output to a file

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 1. Serve XHTML as HTML for Microsoft web browsers

If you do not care whether people can read your XHTML documents using Microsoft web browsers, please disregard this message. Otherwise, please heed the following instructions.

When you use the XHTML format, ensure that either (1) your saved output document is served to web browsers under the text/html mime type, or (2) the file extension of your saved output document is either .html or .htm.

Otherwise, Microsoft web browsers will not display your XHTML document and will instead prompt the reader to save your XHTML document as a file on their computer. See this detailed explanation for details.

4.1.2 Unindenting nodes hierarchically

When writing ERBook documents, I prefer to indent the content of nodes according to their depth because my text editor of choice automatically folds blocks of text based on indentation.

If you also prefer to write documents in this way, be sure to pass the --unindent option to ERBook so that the indentation will not affect the resulting output.

Part 5
Formats

This part describes the default formats provided along with ERBook. The format specification files for these formats can be found in the fmt/ directory of the ERBook installation directory (see Package contents).

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.

XHTML (web page)
Plain text
LaTeX (PDF)
UNIX manual page

Chapter 5.1
XHTML (web page)

This format generates a monolithic XHTML document that allows users to easily search for a particular topic using nothing more than their web browser’s built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.

When viewing an XHTML document in a graphical web browser, you will notice navigation menus to the left of chapters, sections, figures, admonitions, and so on. These menus contain hyperlinks that make it easy to navigate the XHTML document, especially for users of text-only web browsers.

Furthermore, the XHTML document comes equipped with a stylesheet suitable for printing. In particular, users of web browsers that support CSS3 selectors will notice that all hyperlinks have been expanded to include their target URL next to them. Try the “print preview” function of your web browser to see how the XHTML document would appear when printed.

Text to XHTML conversion
Parameters
Methods
Nodes

5.1.1 Text to XHTML conversion

The lib/erbook/to_xhtml.rb file inside ERBook’s installation directory (see Package contents) defines the following methods:

String#to_xhtml - Transforms this string into XHTML.

The default implementation of the String#to_xhtml method employs the Markdown markup system. If you do not like Markdown or wish to use a different markup system for text in your documents, then simply edit the to_xhtml.rb file and adjust the source code of the default String#to_xhtml method accordingly.

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

class String
  # Transforms this string into XHTML.
  def to_xhtml
    '<p style="border: thin solid red">' + self + '</p>'
  end
end

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

Syntax coloring for source code
Smart sizing of source code
Protecting verbatim text

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. The syntax coloring library, CodeRay, currently supports the following programming languages:

Ruby
C
Delphi
HTML
RHTML (Rails)
Nitro-XHTML

Specifying the programming language

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 life = true or false of code. And here is a paragraph

life =
  true or
false

of code.

5.1.1.3 Protecting verbatim text

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

5.1.2 Parameters

The XHTML format accepts the following document parameters. To disable the default value for a particular parameter, simply set that parameter to nil. For example, to disable the $authors parameter, you would write $authors = nil in your input document.

Parameter	Type	Default value	Description
`$title`	`String`	`"$title"`	Primary title of the document.
`$subtitle`	`String`	`"$subtitle"`	Secondary title of the document.
`$authors`	`Hash`	`{"$authors" => nil}`	A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided `String#to_xml_entities` method like this: `{ "A. U. Thor" => "mailto:a@u.thor".to_xml_entities }`
`$date`	`String`	`Time.now.strftime("%d %B %Y")`	Date when the document was written.
`$logo`	`String`	`nil`	Arbitrary content that goes above the document title in the default header.
`$feeds`	`Hash`	`nil`	A mapping of feed URL to feed format. Here is an example: $feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" }

5.1.3 Methods

The XHTML format provides the following methods. In the method declarations shown below,

a pound sign (#) indicates that the method is an instance method, meaning that it can only be invoked on instances of a class, not on the classes themselves.
a double colon sign (::) indicates that the method is a class method, meaning that it can only be invoked on a class.

String
Hash
ERBook::Template::Sandbox
ERBook::Document::Node

5.1.3.1 `String`

to_xml_entities

String#to_xml_entities()

Transforms this UTF-8 string into XML entities.

to_uri_fragment

String#to_uri_fragment()

Transforms this string into a valid URI fragment. See www.w3.org/TR/REC-html40/types.html#type-name

thru_ember

String#thru_ember(binding, options = {})

Evaluates this string as an Ember template (created with the given options) inside the given binding.

to_xhtml

String#to_xhtml()

Transforms this string into XHTML.

with_protected_tags

String#with_protected_tags(input, tag_defs, verbatim) {|input| ... }

Protects the given tags in the given input, passes that protected input to the given block, restores the given tags in the result of the block and returns it.

verbatim: If true, the content of the elments having the given tags will not be temporarily altered so that process nested elements can be processed.

calc_digest

String#calc_digest(input)

Returns a digest of the given string that will not be altered by String#to_xhtml.

5.1.3.2 `Hash`

to_xml_atts

Hash#to_xml_atts()

Transforms this hash into a string of XML attribute key=“value” pairs.

5.1.3.3 `ERBook::Template::Sandbox`

verbatim

ERBook::Template::Sandbox#verbatim(content)

Protects the given content from the text-to-XHTML conversion process.

hyperlink

ERBook::Template::Sandbox#hyperlink(url, label = url, title = nil)

Returns XHTML for a hyperlink to the given URL of the given label and mouse-hover title.

embed_image_file

ERBook::Template::Sandbox#embed_image_file(path, format = path[/\w+/], atts = {})

Returns an image tag that embeds the given image file.

path: path to the image file
format: format of the image file (e.g. PNG, JPEG, GIF, etc.)
atts: additional attributes for the image tag

embed_image_data

ERBook::Template::Sandbox#embed_image_data(data, format, atts = {})

Returns an image tag that embeds the given raw image data.

data: raw image data
format: format of the image file (e.g. PNG, JPEG, GIF, etc.)
atts: additional attributes for the image tag

method_missing

ERBook::Template::Sandbox#method_missing(name, *args, &block)

Allows float nodes to be instantiated implicitly by name.

5.1.3.4 `ERBook::Document::Node`

index?

ERBook::Document::Node#index?()

index_toc?

ERBook::Document::Node#index_toc?()

index_lof?

ERBook::Document::Node#index_lof?()

title_xhtml

ERBook::Document::Node#title_xhtml()

Returns the title of this node as XHTML.

content_xhtml

ERBook::Document::Node#content_xhtml()

Returns the content of this node as XHTML.

wrap_content_xhtml

ERBook::Document::Node#wrap_content_xhtml(tag, atts = {})

Returns the result of wrapping this node’s content in the given tag and converting it into XHTML.

title_link

ERBook::Document::Node#title_link(title = nil)

Returns a hyperlink to this node containing its title.

section_number_link

ERBook::Document::Node#section_number_link()

Returns a hyperlink to this node containing its section number.

ordinal_number_link

ERBook::Document::Node#ordinal_number_link()

Returns a hyperlink to this node containing its ordinal number.

toc_children

ERBook::Document::Node#toc_children()

Returns all children of this node which are configured to appear in the table of contents.

xref_link

ERBook::Document::Node#xref_link(label = nil)

Returns a hyperlink to this node.

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.

Chapter 5.1.4
Nodes

Unless otherwise noted, all nodes defined by the XHTML 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 xref and cite), which allow you to refer to another node in the document by its unique identifier.

Furthermore, node definitions in the XHTML format have two additional parameters:

Parameter	Type	Description
index	`String` or `Array` thereof	When “tree”, include this node in the Table of Contents (TOC). When “list”, include this node in the List of Figures (LOF). Both choices can be specified simultaneously.
chain	Boolean	Include this node in the previous/next navigation chain?

Structural nodes
Organizational nodes
Float nodes
Admonition nodes
Table nodes
Bibliographic nodes

5.1.4.1 Structural nodes

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

header
footer
abstract
xref

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.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: 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 Organizational nodes

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

node
part
chapter
section
paragraph

5.1.4.2.1 node

A placeholder that simply passes its content to the output.

This node has no real use in the writing of a document. It mainly helps programmers define “virtual” nodes that simply wrap some user-provided content. Programmers can then manipluate the content of those virtual nodes when processing the document.

This is how a node node appears.

5.1.4.2.2 part

A collection of chapters.

An example

Part 5.1.4.2.2.1
An example

This is how a part node appears.

5.1.4.2.3 chapter

A collection of sections.

An example

Chapter 5.1.4.2.3.1
An example

This is how a chapter node appears.

5.1.4.2.4 section

A collection of paragraphs about a particular topic.

An example

5.1.4.2.4.1 An example

This is how a section node appears.

5.1.4.2.5 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 Float nodes

A float (also known as an “aside” or “sidebar”) is an imaginary box that is set off from the main flow of content. It typically contains auxiliary materials—such as figures, tables, equations, admonitions, an so on—to which the main body of text can refer.

Float 1. An example

This is how a float node appears.

Arbitrary floats

5.1.4.3.1 Arbitrary floats

Arbitrary float nodes can be instantiated anywhere in the document simply by adding an exclamation mark to the name of the arbitrary node.

Example 4. An example

To create an arbitrary float named “foobar”, we would write:

<% foobar! "Foo, bar, and friends" do %>
  **You there!**  Behold this highly *foobar* node!
<% end %>

and the result would be this:

Foobar 1. Foo, bar, and friends

You there! Behold this highly foobar node!

command!

5.1.4.3.1.1 command!

A command that is to be run at a command-line.

Command 1. echo -n 'This is an example! '; date

This is an example! Sat Nov  7 00:02:04 PST 2009

5.1.4.4 Admonition nodes

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.

warning!
caution!
important!
note!
tip!

5.1.4.4.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.4.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.4.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 2. An example

This is how a important! node appears.

5.1.4.4.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.4.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.5 Table nodes

Tables can be built using the following nodes (just like in XHTML):

table: A table. Contains any combination of header, body, footer, and row.
thead: Table header. Contains rows of headings cells.
tbody: Table body. Contains rows of cells.
tfoot: Table footer. Contains rows of heading cells.
tr: Row of cells.
th: Heading cell.
td: Content cell.

These nodes take an optional Hash parameter which specfies the attributes to be injected into their corresponding XHTML elements.

Example 5. An example

A table built from this source document:

%|table
  %|thead
    %|tr
      %|th "colspan" => 2
        Hello World
  %|tfoot
    %|tr
      %|th
        Good
      %|th
        Bye!
  %|tbody
    %|tr
      %|td
        Foo
      %|td "rowspan" => 2, "style" => "color: red"
        Bar
    %|tr
      %|td "style" => "color: blue"
        Qux

Would appear like this in a web browser:

Hello World
Good	Bye!
Foo	Bar
Qux	Bar

5.1.4.6 Bibliographic nodes

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

reference
cite

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

An example

See xhtml.nodes.reference.example for an example of how a reference node appears.

5.1.4.6.2 cite

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

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

For example, this node in the input document:

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

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

As another example, this node in the input document:

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

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

Chapter 5.2
Plain text

This format is not yet implemented. Patches are welcome! :-)

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

Chapter 5.3
LaTeX (PDF)

This format is not yet implemented. Patches are welcome! :-)

http://www.latex-project.org

Chapter 5.4
UNIX manual page

This format is not yet implemented. Patches are welcome! :-)

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

Chapter 6
History

Version 9.2.0 (2009-11-06)
Version 9.1.0 (2009-11-03)
Version 9.0.0 (2009-10-18)
Version 8.0.0 (2009-10-10)
Version 7.3.0 (2009-10-09)
Version 7.2.0 (2009-10-07)
Version 7.1.1 (2009-09-06)
Version 7.1.0 (2009-08-30)
Version 7.0.0 (2009-05-03)
Version 6.1.0 (2009-02-14)
Version 6.0.1 (2009-01-19)
Version 6.0.0 (2009-01-19)
Version 5.0.0 (2008-11-22)
Version 4.0.0 (2008-11-15)
Version 3.1.0 (2008-06-22)
Version 3.0.2 (2008-06-08)
Version 3.0.1 (2008-06-03)
Version 3.0.0 (2008-06-01)
Version 2.1.0 (2008-05-29)
Version 2.0.0 (2008-02-03)
Version 1.1.0 (2008-01-22)
Version 1.0.0 (2008-01-12)
Version 0.0.1 (2007-12-13)
Version 0.0.0 (2007-12-09)

6.1 Version 9.2.0 (2009-11-06)

This release improves the usability of the JavaScript-based search functionality in the XHTML format and fixes a bug in the footer node.

New features

Put search box on the main tab navigation bar.
Hide search results tab until search is performed.
Show default text in search box and mention regexps.
Add jQuery UI progress bar to show search status.
Add search mutex – only one search at a time.
Detect & report invalid regexp in search query.
Add start & stop buttons to search form.
Update all language translations accordingly.

Bug fixes

The footer node was not being converted into XHTML correctly.
Implement an even simpler solution to the multi-row tab alignment problem for jQuery UI tabs.
Add gap between checkbox & “printer friendly” label.

Housekeeping

Show “0 results” instead of “Not found” after a search.
Remove “Help” link for regexp syntax reference in search from. That reference was English-only anyway.

6.2 Version 9.1.0 (2009-11-03)

This release adds JavaScript-based search functionality, improves usability, and fixes some bugs—all in the XHTML format.

New features

Add JavaScript-based search functionality to XHTML format.
Make paragraph nodes flow with the body (don’t put tabs around them).
Make external hyperlinks open in a separate window.
Make “Printer friendly” label clickable like the checkbox.

Bug fixes

The first character of a URI fragment can be an underscore, according to the W3C XHTML 1.0 Strict validator!.
Scroll to nearest visible element if scroll target is naturally hidden (e.g. because of a CSS rule).
Prevent scroll animation callback from being called twice.
Do not show “Loading… failed” message in text-only web browsers.
Fix empty “lang” attributes in the output of the syntax coloring library.

Housekeeping

Rename the IDs of core XHTML structures to be self-documenting.
Shorten mini navigation link labels for text-only web browsers.
Refactor JavaScript according to JSLint suggestions.
Project license was not being emitted into JavaScript code.

6.3 Version 9.0.0 (2009-10-18)

This release adds new nodes to the XHTML format, reduces the size of generated XHTML documents and also improves their usability and validity.

Incompatible changes

The String#to_inline_xhtml method has been removed. Use the String#to_xhtml method, which now returns inline XHTML, instead.

New features

Add “text” and “code” nodes for <pre> and <code>.
Add “chain” parameter to XHTML node definitions.
Add command! floats for listing shell commands and their output.
Reduce XHTML output size by activating image data URIs at runtime using JavaScript. Previously, data URIs were emitted into XHTML at compile time.
Upgrade from XHTML 1.0 Transitional to Strict.

Bug fixes

Add support for multiple tab rows in jQuery UI tab bars.
Auto-detected mime types were inserted incorrectly in base64 embeds.
Prevent block-level children of <ins> from appearing underlined on screen (Opera browsers) and in print (Microsoft browsers).
<blockquote/> icon did not appear in print style.
Prevent mini navigation menus from colliding.

Housekeeping

Remove the need for highlighting scroll target by setting body height so that any element can be brought to the top of the screen via scrolling.
Place mini navigation menus on jQuery UI tab bars when possible.
Show logo image in full and centered above document header.
Completely remove <p> around block-level child (added by Markdown).
Fix XHTML validation errors on <table>, <tfoot>, <img> in RDoc strings, and output of syntax coloring library.
DRY up XHTML node definitions using YAML hash merging operator.

6.4 Version 8.0.0 (2009-10-10)

This release simplifies node definitions, adds Table nodes for building tables the HTML way, and introduces Arbitrary floats to combat the explosion of special-purpose document nodes.

Incompatible changes

Reduce and rename node definitions attributes:
- toc: true → index: tree
- lof: true → index: list
- index: true → number: section
- number: true → number: ordinal
- depth: true → (removed)
- bypass: true → (removed)
Rename The ERBook::Document::Node class properties to be more self-documenting:
- args → arguments
- defn → definition
- trace → backtrace
- index → section_number
- number → ordinal_number
Replace formal blocks (figure, table, example, equation, procedure) with Arbitrary floats.
Append an exclamation mark (!) to the names of Admonition nodes, thereby making them a special case of Arbitrary floats.

New features

Add “params” attribute to node definitions.
Add Table nodes for building tables the HTML way.

Housekeeping

Use YAML hash merging to DRY node definitions in XHTML format.
Use Table nodes instead of PHP Markdown Extra table syntax in the user manual.
Remove the “digest” Node definition attribute from the user manual. Its use was discontinued a few major versions ago.

6.5 Version 7.3.0 (2009-10-09)

This release improves the printer friendliness of the XHTML format.

New features

Do not omit ERBook internals from node stack traces.
Hide “printer friendly” toggle checkbox when printing (but not when viewing the “printer friendly” mode on the computer screen).
Hide the “About” section in “printer friendly” mode.

Bug fixes

Page scrolled to wrong location when links in the table of contents in the “printer friendly” mode were clicked.
Print style was not used when printing from “printer friendly” mode.
Sans-serif font was not used in headings in print style.

Housekeeping

Use Ember syntax in Input document for HelloWorld format example.

6.6 Version 7.2.0 (2009-10-07)

This release improves support for Ruby 1.9 and Webkit-based web browsers, reduces gem dependencies, and fixes some bugs.

New features

Add String#thru_ember method for direct template rendering.

Bug fixes

XHTML

Fix “printer friendly” toggle checkbox for Webkit browsers.
Disable interactive TOC tree location coloring in print style.
Use normal line height for preformatted text in print style.
Use serif for normal and sans-serif for emphasis in print style.

Ruby 1.9

Array#to_s is same as Array#inspect in Ruby 1.9.
RDoc 2.4.3 no longer provides RDoc::Generators::MarkUp.

Markdown

Allow “code spans” annotated with Maruku’s IAL (Inline Attribute List) Markdown extension to be syntax colored.

Housekeeping

Remove CSS and JavaScript minification in favor of manual gzip compression and fewer gem dependencies.
Fix forgotten Textile ‘bq.’ to Markdown ’>’ conversion.
Omit navigation menu from Abstract; it is standalone.
Mark all code spans with {:lang=ruby} instead of HTML <code/> tags

6.7 Version 7.1.1 (2009-09-06)

This release improves support for Microsoft, Opera, and Webkit web browsers in the XHTML format, revises the code and documentation, and fixes some bugs.

Bug fixes

Restore support for Microsoft web browsers by removing the optimization of storing image data URIs in XML entities. See Serve XHTML as HTML for Microsoft web browsers for the consequences of this change.
The screen did not scroll during reveal_hash() in Webkit browsers.
The prevent_jump option of set_hash() did not work for Opera and Microsoft browsers.
Use text descriptions instead of graphical symbols in the ALT fields of navigation menu images.
The Abstract was not in the prev/next navigation chain.

Housekeeping

Open source is for fun, so be nice: speak of “related works” instead of “competitors”.
Fix warning about $logo and $feeds being used when not defined.
Include project website URL in “generator” HTML meta field.
Emit project license above JavaScript code in XHTML output.
Lots of other clean up in the documentation and the XHTML format.

6.8 Version 7.1.0 (2009-08-30)

This release improves the appearance and usability of XHTML (web page) documents through jQuery UI, and fixes some bugs.

New features

jQuery UI tabs now organize the content of XHTML (web page) documents in a breadth-first manner for easier skimming and browsing. Note that the print stylesheet still continues to organize content in the traditional depth-first manner.
Add checkbox for toggling printer friendly stylesheet. This makes it more obvious to readers that a specially-designed print stylesheet exists for their convenience.
Show both $title and $subtitle in XHTML document’s title.

Bug fixes

Reference nodes were included in next/prev navigation chain.

Housekeeping

Convert CSS into SASS.

Use simpler Copyright reminder at the top of every file:

Copyright protects this work.
See LICENSE file for details.

Remove localScroll and scrollTo jQuery plugins; we do our own logic (based on their source code) for smoothly scrolling to elements.
Rename XHTML resource directories into subdirectories.
“Logistics” section was under project description and was therefore put into the release announcement. Ack!

6.9 Version 7.0.0 (2009-05-03)

This release improves the appearance, usability, and validity of XHTML (web page) output, upgrades to a new eRuby templating system, adds new processing options to node definitions, and fixes some bugs.

Incompatible changes

If you add methods to the ERBook::Template class, in order to provide them to eRuby templates, you must now add those methods to the ERBook::Template::Sandbox class instead.
The Ember template processor is now used to render eRuby templates instead of the ERB library that is shipped with Ruby.
- The file inclusion directive has been removed:
```
<%# include YOUR_FILE #%>
```
  Ember provides equivalent functionality:
```
%< "YOUR_FILE"
```
The erbook/to_xhtml library now annotates <code> elements with a “line” or “para” class indicating whether they span a single or mulitple lines respectively.

The “pre.code” CSS class is no longer emitted.
The erbook/rdoc library has been updated to work with RDoc 2.4.3. It no longer supports the old RDoc that is shipped with Ruby 1.8.
Just a reminder from the Version 5.0.0 (2008-11-22) release notes:

Internet Explorer 6 and 7 do not support the application/xhtml+xml mime type, so the output generated by the XHTML (web page) format cannot be viewed in those browsers.

New features

Replace dark background theme with a “wide open spaces” theme.
- Use icons instead of unicode glyphs for mini navigation menus.
- Put mini navigation menus on right-hand side of headings
- Use scrolling animation when local links (URI fragments) are visited, instead of instantly teleporting to the destination. This gives a sense of spatial existence to the web page, making it feel almost tangible!
XHTML output is now valid XHTML 1.0 Transitional! And the embedded CSS it contains is now valid CSS 3!
- Minify CSS in XHTML output using the Rainpress library.
- Add CSS style for HTML definition lists.
Omit target type and index (“Section X.Y.Z”) in output of xref() nodes in the screen-version (CSS stylesheet) of the generated output document.

This information is still present in the print-version (CSS stylesheet) of the generated output document, where it is truly helpful to the reader.
Add “bypass” option to node definitions to properly support the generic “node” node. Invalid XHTML was being generated because the ‘node’ node was marked as simply “inline”, so it was not pulled out of the <p> tag created by Maruku.

Bug fixes

The “silent” property in node definitions was not being honored.
Fix error when inserting reference nodes (they are not inline!).
Add workaround for Maruku treating first line of input as parameter definition, and thereby omitting it from the output!
Array#to_s is equivalent to Array#inspect in Ruby 1.9.
HelloWorld format specification file added methods to the nonexistent ERBook::Node class instead of adding them to the ERBook::Document::Node class.

Housekeeping

Simplify language phrases used in mini navigation menus.
Remove CSS hacks for supporting IE6; it cannot render XHTML anyway.
Render italics and boldface equally in serif font. Bold is truly bold now and italic is distinctive.
Adjust spacing between document title, author, and date headings.
Add copyright notice at the top of every file.

6.10 Version 6.1.0 (2009-02-14)

New features

Added translations for English phrases used in the XHTML format (see the lang/ directory).

You can choose which language to translate into by setting your LANG environment variable or by supplying the --locale option to the erbook executable.
Reduced brightness of links in local navigation menus; it was distracting from the main text of the document.
Draw the HTML <hr/> element as a dashed black line, instead of a glaring red line.

Bug fixes

LaTeX-style index numbers were calculated incorrectly for descendants of the “node” node.

Housekeeping

Add release notes for past releases… two years have already passed since I started this project! Where did the time go?
List all contributors in the Credits section and make project logo a hyperlink to that section so interested people can quickly learn the source of the logo.
Mention that project license is ISC for reader’s convenience.

6.11 Version 6.0.1 (2009-01-19)

This release reattempts to fix the circular dependency problem that occurred when installing either Inochi or ERBook.

6.12 Version 6.0.0 (2009-01-19)

This release improves the appearance & usability of the XHTML format, refactors the core logic into reusable libraries, fixes some bugs and improves variable names.

Incompatible changes

Renamed @types to @nodes_by_type and @spec to @format in XHTML format.
Moved the core logic of the erbook executable into the ERBook::Document and ERBook::Document::Template classes.

New features

Addded navigation menus beside every segment in the user manual. These menus allow you to jump to the next/previous segment, whereas previously you always had to go back to the table of contents and select a new segment.
A star is drawn beside a reverse jump target in the table of contents, so the user can continue where they left off.
Added “inline” node definition parameter (see Node definition).
Added $subtitle parameter to XHTML format.
Document parameters for the XHTML format, such as $title, can now be disabled by setting them to nil.
Relative file paths can now be specified in <%#include#%> directives.
Added a “node” node (see node), which serves as a pass-through container, in the XHTML format.
Allow user to type <pre> blocks on single lines without affecting the display of their content.
Initial newline in the body of <code> is now stripped. This allows users to write their code blocks normally:

<code>
foo
bar
</code>

Instead of abnormally to avoid an extra leading newline:

<code>foo
bar
</code>
Paragraph nodes are now included in the table of contents.

Bug fixes

Input to unindentation algorithm was being partially unindented beforehand by the logic that silences code-only eRuby directives. This corrupted the unindentation algorithm’s output in some cases.
<pre> blocks now expand to fit their content in the XHTML format. No more scrollbars!
<a/> without href was treated as external hyperlink.

Housekeeping

Revised the project logo to emphasize the owl mascot.
Replaced dull MediaWiki hyperlink colors with more lively colors in XHTML format.
Wrote more API documentation and use Inochi to simplify project maintenance.

6.13 Version 5.0.0 (2008-11-22)

This release renames the “html” format to “xhtml”, moves previously global stuff into the ERBook namespace, improves error reporting and usability, reduces the file size of XHTML output, and fixes some bugs.

Incompatible changes

Renamed the “html” format to “xhtml” (and all similarly named methods and files) in order to support custom DTD extensions which reduce the overall file size of the output. See this note in the user manual for the consequences of this change.
- Internet Explorer 6 and 7 do not support the application/xhtml+xml mime type, so the output generated by the XHTML (web page) format cannot be viewed in those browsers.
Removed the $use_icons parameter from the XHTML format. Now, icons are always used, whether you like it or not! ;-)
Replaced the implicit ERB::Util#h method with a verbatim() method in the XHTML format.
The Trollop library (used for command-line options parsing) is now required to run erbook. See the “Setup” section in the user manual for details.

New features

Added support for single-line eRuby directives (lines which begin with ”%”), both in general and in the --unindent option. See this section of the user manual for examples.
Enhanced stack traces with information about the input file and also <%#include#%>-ed files. This was done at the cost of increasing the number of source lines of code to more than 200 (it is 207 right now). Oh well, tradeoffs. ;-)
Omitted erbook internals from stack traces (unless in $DEBUG mode). This helps users concentrate on problems in their input document.
Used colors for hyperlinks and suffix icon for external hyperlinks from the MediaWiki software, which powers the famous Wikipedia.

Bug fixes

Could not jump to examples and admonitions from the list of figures.
Reorganized icons for the XHTML format to better reflect their origin (the directory layout of the source code of the open-source projects they came from) so that others can easily find them in their original sources.

Housekeeping

Added API documentation for all methods listed in the user manual, while also omitting many irrelevant methods from the list.

6.14 Version 4.0.0 (2008-11-15)

This release renames the project, changes the project license, the source repository, and the default text-to-HTML formatting system, refactors the HTML format, and revises the documentation.

Contributor kudos

Jens Vierbuchen contributed the the cartoon owl sitting on a book drawing that is used in the new project logo:
Maunika Gosike provided usability feedback to help improve the HTML format.

Incompatible changes

The “Gerbil” project has been renamed to “erbook” to better reflect its purpose: it allows you to write books and documents using eRuby.
The project license has been changed from a custom MIT/copyleft license to the more permissive ISC license to make the world a better place! :-)
The project source code repository is now hosted on GitHub (and therefore we now use Git instead of Darcs) to ease collaboration.
Markdown is now the default text-to-HTML formatting system for the HTML format.

New features

Added admonition icon for HTML <blockquote> element.
A visual marker is shown on outgoing (external) hyperlinks.
Tooltips are shown upon mouse hover for section index and title links which instruct new users how to navigate the web page more efficiently.

Housekeeping

Renamed Node#url to Node#here_frag. Also, speak of “frags” rather than “anchors” or “urls” from now on.
Refactored common logic from node output templates into Node class.

6.15 Version 3.1.0 (2008-06-22)

This release improves the HTML format by reducing the output file size, improving on-line usability and document printability (please try the “print preview” function in your browser; the output is simply beautiful!), and repairing some defects.

New features

The file size of the HTML format’s output has been significantly reduced by reusing the data for embedded admonition icons through CSS. So use admonitions generously; they will not bloat the output file size!

Usability

All headings are now hyperlinks to themselves. This allows readers to obtain a “permanent link” to any section in your HTML document.
A meta navigation menu is now emitted at the top of the HTML document. This menu contains hyperlinks to the various structural elements of a document, such as the abstract, table of contents, list of figures, and references.
The color of visited hyperlinks has been darkened to improve readability.
The style of blockquote now provides better focus on its content.
Cross-reference (xref) hyperlinks now have a mouse-hover title when you override the default link text.

Printing

Page breaks are now inserted before major sections in the document. This allows for easier printing (you can print a subset of pages without fear of discontinuity) and improves readability through better organization.
In browsers that support CSS3 pseudo-class selectors, cross-reference hyperlinks now show the name and index of their destination node.
Internal hyperlinks (which point to internal URI fragments) that are not cross-references are now shown as normal text to reduce distraction.

Bug fixes

Cross-reference (xref) hyperlinks to paragraphs were broken due to a missing id attribute.

Housekeeping

Removed useless CSS styles and fixed some XHTML validation issues.

6.16 Version 3.0.2 (2008-06-08)

This release implements a shorter, faster, better unindentation algorithm which:

Allows block beginnings <% do %> and endings <% end %> to span multiple lines.
Ignores blank lines (which may contain whitespace) after block beginnings.
Processes multiple lines per iteration, instead of one line at a time.

6.17 Version 3.0.1 (2008-06-03)

This release repairs the unindent feature (it did not consider block beginnings that had block parameters) and adds an error message when block beginnings and endings are unbalanced.

6.18 Version 3.0.0 (2008-06-01)

This release improves the unindent feature and changes the include directive’s syntax. In related news, the project mailing list has been dismantled in favor of simply contacting the author directly (see e-mail address in LICENSE) to get help or provide feedback.

Incompatible changes

The $unindent parameter has been replaced by the --unindent command-line option, which automatically unindents each line of input by the inner margin of its containing node.
The include directive now has a symmetric # at the closing end:
```
<%# include ... #%>
```

Bug fixes

The CSS for the horizontal rule (hr) element should now be consistent in all browsers.
In the HTML format, whitespace has been added (in CSS) around the following nodes to make them conform more easily with the style of the rest of the document:
- header_outside_above - above the entire header block
- header_inside_above - above the default header content
- header_inside_below - below the default header content
- header_outside_below - below the entire header block
- footer_outside_above - above the entire footer block
- footer_inside_above - above the default footer content
- footer_inside_below - below the default footer content
- footer_outside_below - below the entire footer block

6.19 Version 2.1.0 (2008-05-29)

This release adds image embedding methods for the HTML format and no longer appends (through CSS) an asterisk on outgoing hyperlinks.

6.20 Version 2.0.0 (2008-02-03)

This release fixes some bugs, improves the RDoc library, and adds nodes for customization of the default header and footer.

Incompatible changes

The lib/gerbil/rdoc.rb library has changed! Read it for details.

New features

In the html format, added the following nodes which allow you customize the default header and footer whilst preserving the default content:
- header_outside_above - above the entire header block
- header_inside_above - above the default header content
- header_inside_below - below the default header content
- header_outside_below - below the entire header block
- footer_outside_above - above the entire footer block
- footer_inside_above - above the default footer content
- footer_inside_below - below the default footer content
- footer_outside_below - below the entire footer block

Bug fixes

Regexp substitution placeholders were being interpreted in node content. In particular, any occurrences of “\0” in a node’s content was replaced by a strange SHA1 digest! (Zhang Chiyuan)
The lib/gerbil/rdoc.rb library did not extract method information recursively.

Housekeeping

In the html format, added a CSS margin above HTML tables because they were visually colliding with other elements above them.
Fixed some Ruby code warnings in the html format.

6.21 Version 1.1.0 (2008-01-22)

This release improves usability and fixes some bugs.

New features

External links are now marked with a ∗ symbol to help the user distinguish between internal and external links. This is helpful because a user may not wish to follow a link that takes them outside a document, say, when they are reading the document offline, without an Internet connection.

Bug fixes

Forgot to update some code when I renamed the RDoc.gen_parse_tree method in format/rdoc.rb during the last release.
Module methods were omitted by the RDoc.gen_method_infos method in format/rdoc.rb.

6.22 Version 1.0.0 (2008-01-12)

This release makes Gerbil available as a RubyGem, fixes some bugs, and updates the user guide.

Incompatible changes

The gerbil file has been moved to bin/gerbil.
The format/ directory has been renamed to fmt.
The format/html.rb file has been moved to lib/gerbil/html.rb.
The format/rdoc.rb file has been moved to lib/gerbil/rdoc.rb.
In format/rdoc.rb, the name of the RDoc.gen_parse_tree method has been pluralized (tree → trees) because it really returns an array of trees rather than a single tree.
The CHANGES.yaml file has been removed, in favor of this RSS feed.
The GENERATOR object has been renamed to Gerbil.

Bug fixes

User guide now says “gem install RedCloth” instead of “gem install redcloth”. I don’t see why RubyGems requires the correct capitalization, so I filed a bug report about it.
In the HTML format, images inside descendant nodes of a figure node were not properly centered.
In the HTML format, the $title parameter was not converted into HTML.

6.23 Version 0.0.1 (2007-12-13)

Fixed the generation of unique node URI fragments in the HTML format.
Added a $feeds parameter to the HTML format.
Added the format/rdoc.rb library for accessing RDoc’s parse tree.
Updated the user guide:
- added documentation for methods provided by the HTML format
- added RSS feed for project release announcements
- improved the ghastly HelloWorld example
Added a simple change-log (CHANGES.yaml) for the project.

6.24 Version 0.0.0 (2007-12-09)

Dear developers, technical writers, and documentation gurus,

I am proud to announce a new project of mine named “Gerbil” which is beautifully short (176 lines of code) and powerful!

Personally, I am baffled at the amount of documentation I wrote (and felt was necessary) to explain the plethora of things this tiny little utility does. About 70% of the development time was consumed by documentation alone! I’m glad that’s over. :-)

The release notes are shown at the bottom of this message.

Cheers!

This is the first release of the Gerbil project Happy birthday!

Please note that although the user guide says you can install Gerbil via RubyGems, currently there is a bug in RubyGems version 0.9.5 that prevents me from creating an installable gem without strictly adhering to RubyGems convention of putting executable programs inside a bin/ directory.

Until this issue is resolved, please download the tarball/zip packages instead.

Resource	Origin	License
	Tango Icon Theme © 2005 Tango Desktop Project	Creative Commons Attribution-ShareAlike 2.5 License Agreement
	MediaWiki Monobook Skin © 2007 MediaWiki contributors	GNU General Public License, version 2

ERBook 9.2.0

Write books, manuals, and documents in eRuby

Suraj N. Kurapati

07 November 2009

Contents

Cautions

Commands

Examples

Floats

Foobars

Importants

Notes

Tips

Warnings

Document

Chapter 1 Introduction

1.1 Features

1.2 License

1.3 Credits

1.4 Reviews

1.5 Related works

Chapter 2 Setup

2.1 Requirements

2.2 Installation

2.3 Package contents

2.4 Version numbers

Chapter 3 Theory

3.1 Nodes

3.1.1 The ERBook::Document::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 document format

hello #: "dunam"

hello #: "sevoho"

hello #: "fun"

hello #: "kiyu"

hello #: "jusijoj"

hello #: "bubusa"

hello #: "zuyolan"

hello #: "filebul"

hello #: "jihe"

hello #: "salugo"

Chapter 4 Usage

4.1 Command-line interface

4.1.1 Saving the output to a file

4.1.2 Unindenting nodes hierarchically

Part 5 Formats

Chapter 5.1 XHTML (web page)

5.1.1 Text to XHTML 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

5.1.3.1 String

5.1.3.2 Hash

5.1.3.3 ERBook::Template::Sandbox

5.1.3.4 ERBook::Document::Node

Chapter 5.1.4 Nodes

5.1.4.1 Structural nodes

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 Organizational nodes

5.1.4.2.1 node

5.1.4.2.2 part

Part 5.1.4.2.2.1 An example

5.1.4.2.3 chapter

Chapter 5.1.4.2.3.1 An example

5.1.4.2.4 section

5.1.4.2.4.1 An example

5.1.4.2.5 paragraph

5.1.4.3 Float nodes

5.1.4.3.1 Arbitrary floats

5.1.4.3.1.1 command!

5.1.4.4 Admonition nodes

Chapter 1
Introduction

Chapter 2
Setup

Chapter 3
Theory

3.1.1 The `ERBook::Document::Node` class

Chapter 4
Usage

Part 5
Formats

Chapter 5.1
XHTML (web page)

5.1.3.1 `String`

5.1.3.2 `Hash`

5.1.3.3 `ERBook::Template::Sandbox`

5.1.3.4 `ERBook::Document::Node`

Chapter 5.1.4
Nodes

Part 5.1.4.2.2.1
An example

Chapter 5.1.4.2.3.1
An example

Chapter 5.2
Plain text

Chapter 5.3
LaTeX (PDF)

Chapter 5.4
UNIX manual page

Chapter 6
History