• Release notes — history of project releases.
• Source code — obtain via Git or browse online.
• API reference — documentation for source code.

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

Copyright 2006 Suraj N. Kurapati sunaku@gmail.com

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.

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.

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!

Your system needs the following software to run ERBook.

You can install ERBook by running this command:

gem install erbook

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

erbook -v

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

project: ERBook
version: 6.0.0
release: 2009-01-19
website: http://snk.tuxfamily.org/lib/erbook/
install: /home/sun/src/erbook

Otherwise, you can contact the author for help.

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

erbook -v

• 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 — provides methods (see Section 5.1.1. Text to XHTML conversion) for the Chapter 5.1. XHTML (web page) format.

    • rdoc.rb — provides RDoc parse trees to Ruby code.

• doc/ — contains this manual and other documentation.

  • erbook.svg — source file of the ERBook logo.

  • index.erb — source file of this manual.

  • api/ — API reference documentation.

• LICENSE — 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, ... %>

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:

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: An example format.

code: |
  class ERBook::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:
    index: true
    number: true
    silent: false
    output: |
      <h3><%= @node.type %> #<%= @node.index %>: <%= @node.name.inspect %></h3>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ERBook - Extensible document processor based on 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 [Option...] FormatName [InputFile]
  erbook [Option...] FormatFile [InputFile]

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

Option:
  --unindent, -u:   Unindent node content hierarchically
    --manual, -m:   Show the user manual
   --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 Section 2.3. Manifest).

≡△▽◎

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.  Save XHTML output as .xhtml

When you use the XHTML format, ensure that the file extension of your saved output document is either .xhtml or .xml. Alternatively, ensure that your saved output document is served to web browsers under the application/xhtml+xml mime type.

Otherwise, most web browsers will not display the icons and graphics embedded in the saved XHTML output document because they will treat it as HTML instead of as XML. See this QuirksMode.org bug report for details.

The include directive allows you to insert the content of an arbitrary file at a certain place in the input document. It is written like this:

<%# include YOUR_PATH_HERE #%>

In the above example, YOUR_PATH_HERE is the path of the file whose content you wish to insert into the input document.

You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the include directive.

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.

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