]> ERBook 7.0.0




Contents

Cautions

  1. An example

Equations

  1. An example

Examples

  1. HelloWorld format specification file
  2. Input document for HelloWorld format
  3. Output of HelloWorld format
  4. An example

Figures

  1. An example

Importants

  1. Save XHTML output as .xhtml
  2. An example

Notes

  1. An example

Procedures

  1. An example

Tables

  1. An example

Tips

  1. An example

Warnings

  1. An example


Chapter 1
Introduction

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

A working XHTML (web page) format is provided, while LaTeX (PDF), UNIX manual page, and plain text formats are planned… patches are welcome!

ERBook is exciting because:

These features distinguish ERBook from the competition, which offers neither scriptable documents nor definable document formats:

1.1  Logistics

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

Version numbers

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

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

1.1  License

(the ISC license)

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.

1.2  Credits

ERBook logo

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:

1.3  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

2.1  Requirements

Your system needs the following software to run ERBook.

SoftwareDescriptionNotes
RubyRuby language interpreterVersion 1.8.7 or newer is required.
RubyGemsRuby packaging systemVersion 1.0.0 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 -v

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

project: ERBook
version: 7.0.0
release: 2009-05-03
website: http://snk.tuxfamily.org/lib/erbook/
install: /home/sun/src/erbook

Otherwise, you can contact the author for help.

2.3  Manifest

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/

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

Chapter 3
Theory of operation

When you run ERBook, it does the following:

  1. Loads the format specification file.

  2. Creates an input document by:

    • Reading the input (the content of either the input file or the standard input stream) into memory.

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

  4. Transforms the processed document into an output document according to the document output template.

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

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:

ComponentDescription
node_typename of the method being invoked
node_argument1, node_argument2, ...arguments for the method invocation
node_contenta block argument being passed to the method invocation
node_objecta 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.

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

PropertyTypeDescription
typeStringName of the type of this node.
argsArrayArguments passed to this node.
contentStringThe block of text passed to this node.
outputStringResult of the node output template for the content of this node.
digestStringA unique identifier for the content of this node.
traceArrayA stack trace describing the location of this node in the input document.
indexStringA 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.
numberIntegerAn 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.
depthIntegerDistance from the root of the document tree to this node.
parentERBook::Document::NodeThe 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.
childrenArray of ERBook::Document::NodeList of child nodes from the document tree.

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

ParameterTypeDescription
descStringA short description of the output format.
codeStringRuby 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.
nodesHashA listing of node definitions.
outputStringAn eRuby template for the final output document. See Document output template.

3.2.1  Node definition

A node definition is a mapping from a name (the “node type”) to the following set of parameters:

ParameterTypeDescription
indexBooleanAssign a LaTeX-style section number to this node?
numberBooleanAssign an order-of-occurrence number to this node?
silentBooleanSuppress the output of this node?
outputStringAn eRuby template for the content of this node. See Node output template.
inlineBooleanIs node’s output an in-line string of text that can be embedded anywhere in the document?
bypassBooleanIs node simply a wrapper (of negligible depth) for content?

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

3.2.1.1  Node output template

A node output template (the output parameter in a node definition) is an eRuby template that transforms a node’s content into output. During the processing stage, 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:

VariableTypeDescription
@nodeERBook::Document::NodeThe node for which this template is being evaluated.
@rootsArray of ERBook::Document::NodeAll root nodes in the document tree.
@nodesArray of ERBook::Document::NodeAll nodes in the document tree.
@nodes_by_typeHashMapping from node type (String) to array of ERBook::Document::Node objects having that type.
@formatHashData from the format specification file.

ERBook also provides the following mappings inside the @format variable:

ExpressionTypeDescription
@format[:name]StringShort-hand name of the current format.
@format[:file]StringPath 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:

VariableTypeDescription
@contentStringContent of the processed document.
@rootsArray of ERBook::Document::NodeAll root nodes in the document tree.
@nodesArray of ERBook::Document::NodeAll nodes in the document tree.
@nodes_by_typeHashMapping from node type (String) to array of ERBook::Document::Node objects having that type.
@formatHashData from the format specification file.

ERBook also provides the following mappings inside the @format variable:

ExpressionTypeDescription
@format[:name]StringShort-hand name of the current format.
@format[:file]StringPath 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:

To run this example:

  1. Save the code shown in HelloWorld format specification file to a file named HelloWorld.spec

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

  3. Run this command:

    erbook HelloWorld.spec HelloWorld.input > HelloWorld.output

  4. 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:
    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!

Example 2.  Input document for HelloWorld format

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

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

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

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

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

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

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

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

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

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

Example 3.  Output of HelloWorld format

Welcome to the “HelloWorld” format.

hello #1: "nepaju"

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

args
["Pretentious", 1, 2, 3]
index
"1"
number
1
trace
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
I'm the very first node, oh _yes_ I am! *sneer*

hello #1.1: "tayizu"

My name is "tayizu" and these are my properties:
args
["Bashful", 4, 5, 6]
index
"1.1"
number
2
trace
doc/HelloWorld.input:5:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
Hi, I... *hide*

hello #1.1.1: "sif"

My name is "sif" and these are my properties:
args
["Hopeful", 0.897243283515023]
index
"1.1.1"
number
3
trace
doc/HelloWorld.input:8:in `render'
doc/HelloWorld.input:5:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
*sigh*

hello #1.1.1.1: "nonavo"

My name is "nonavo" and these are my properties:
args
["Confused", 0.257684159694857]
index
"1.1.1.1"
number
4
trace
doc/HelloWorld.input:11:in `render'
doc/HelloWorld.input:8:in `render'
doc/HelloWorld.input:5:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
Huh?

hello #1.1.2: "yizafi"

My name is "yizafi" and these are my properties:
args
["Raving", "doc/HelloWorld.input"]
index
"1.1.2"
number
5
trace
doc/HelloWorld.input:16:in `render'
doc/HelloWorld.input:5:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
Oh it's *on* now! You're going *down*!

hello #1.2: "jeta"

My name is "jeta" and these are my properties:
args
["Sleepy", Mon May 04 01:18:23 -0700 2009]
index
"1.2"
number
6
trace
doc/HelloWorld.input:21:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
*yawn* Just five more minutes...

hello #1.2.1: "lati"

My name is "lati" and these are my properties:
args
["Peaceful", "/home/sun/src/erbook"]
index
"1.2.1"
number
7
trace
doc/HelloWorld.input:24:in `render'
doc/HelloWorld.input:21:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content
So _be_ happy my friend, *happy*!

hello #1.2.1.1: "bub"

My name is "bub" and these are my properties:
args
["Lonely (as you can see, I have no block)"]
index
"1.2.1.1"
number
8
trace
doc/HelloWorld.input:27:in `render'
doc/HelloWorld.input:24:in `render'
doc/HelloWorld.input:21:in `render'
doc/HelloWorld.input:2:in `render'
(eval):1:in `render'
content

hello #2: "tivirom"

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

args
["Snappy"]
index
"2"
number
9
trace
doc/HelloWorld.input:32:in `render'
(eval):1:in `render'
content
Zip! Zap! Wake up, you sap! _Whoo I'm wild!_ ;-)

hello #3: "neho"

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

args
["Independent (no block, no parents, I am _free_!)"]
index
"3"
number
10
trace
doc/HelloWorld.input:37:in `render'
(eval):1:in `render'
content

That’s all folks!

Chapter 4
Usage

4.1  Command-line interface 

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

important

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.

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

These formats are meant to serve as working examples. If you require more functionality from one of these formats, simply make a copy of the corresponding format specification file and edit the copy to suit your needs. If you would like to contribute or discuss your enhancements to these default formats, you can contact the author.

Chapter 5.1
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 that makes it 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.

∗ ↑ ↓ ≡

5.1.1  Text to XHTML conversion

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

  • String#to_xhtml - Transforms this string into XHTML while ensuring that the result contains one or more block-level elements at the root.

  • String.to_inline_xhtml - Transforms this string into an inline XHTML string (one that does not contain any block-level XHTML elements at the root).

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 and String.to_inline_xhtml methods 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 while ensuring that the
  # result contains one or more block-level elements at the root.
  def to_xhtml
    '<p style="border: thin solid red">' + self + '</p>'
  end

  # Transforms this string into an *inline* XHTML string (one that
  # does not contain any block-level XHTML elements at the root).
  def to_inline_xhtml
    self
  end
end

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

5.1.1.1  Syntax coloring for source code

Syntax coloring is automatically added to source code found inside the <code> and </code> HTML tags. The syntax coloring library, CodeRay, currently supports the following programming languages:

  • Ruby
  • C
  • Delphi
  • HTML
  • RHTML (Rails)
  • Nitro-XHTML
5.1.1.1.1  Specifying the programming language

Because different programming languages have different syntax coloring schemes, you can specify the language of your source code using the lang attribute to ensure that only the appropriate coloring scheme is used. Note that unless the lang attribute is specified, Ruby is assumed to be the programming language of all source code by default.

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

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

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

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

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

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

5.1.1.2  Smart sizing of source code

Source code is automatically sized to be displayed as either a line or paragraph of text, depending on whether it contains line breaks.

For example, here is a single line 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.

ParameterTypeDefault valueDescription
$titleString"$title"Title of the document.
$subtitleString"$subtitle"Secondary title of the document.
$authorsHash{"$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: { "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_xml_entities }
$dateStringTime.now.strftime("%d %B %Y")Date when the document was written.
$logoStringnilArbitrary content that goes above the document title in the default header.
$feedsHashnilA 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.

ERBook::Document::Node#title()

Returns the user-defined title for this node‘s content.

ERBook::Document::Node#id()

Returns the user-defined indentifer for this node.

ERBook::Document::Node#title_xhtml()

Returns the title of this node as XHTML.

∗ ↑ ↓ ≡

ERBook::Document::Node#content_xhtml()

Returns the content of this node as XHTML.

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

Returns a hyperlink to this node containing its title.

ERBook::Document::Node#index_link()

Returns a hyperlink to this node containing its LaTeX-style index number.

ERBook::Document::Node#number_link()

Returns a hyperlink to this node containing its occurrence number.

ERBook::Document::Node#navigation()

Returns a navigation menu relative to this node.

ERBook::Document::Node::navigation(here_frag, list_frag, prev_frag, next_frag)

Calculates a local navigation menu containing links to the given URI fragments (which can be nil).

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.

∗ ↑ ↓ ≡

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

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

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.

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

Returns an <img/> 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 <img> tag

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

Returns an <img/> 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 <img> tag

Hash#to_xml_atts()

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

String#to_xml_entities()

Transforms this UTF-8 string into XML 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_inline_xhtml()

Transforms this string into an inline XHTML string (one that does not contain any block-level XHTML elements at the root).

String#to_xhtml(inline = false)

Transforms this string into XHTML while ensuring that the result contains one or more block-level elements at the root.

inline
If true, the resulting XHTML will not contain a block-level element at the root.

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.

String#calc_digest(input)

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

Chapter 5.1.4
Nodes

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

  1. a required title for the node
  2. 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:

ParameterTypeDescription
tocBooleanInclude this node in the Table of Contents (TOC)?
lofBooleanInclude this node in the List of Figures (LOF)?

5.1.4.1  Structural nodes

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

5.1.4.1.1  header

This node overrides the logo, title, list of authors, and date when the document was written, all of which are shown at the top of the document.

5.1.4.1.2  footer

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

5.1.4.1.3  abstract

A summary of the entire document. This is what most readers will skim through, if you are lucky. Alas, nobody reads entire documents these days! :-(

5.1.4.1.4  xref

A cross-reference; a hyperlink that takes you to any node in the document.

The first argument of this node is either the unique identifier or the user-defined title of the node you wish to cross-reference. If no nodes in the document have the given identifier or user-defined title, then an error will be raised.

The second argument of this node overrides the default link text of the cross-reference.

For example, this node in the input document:

<%= xref "SpecFile" %>

appears in the output document like this: 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).

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.

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.

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.

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

5.1.4.3.1  warning

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

Warning 1.  An example

warning

This is how a warning node appears.

5.1.4.3.2  caution

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

caution

This is how a caution node appears.

5.1.4.3.3  important

Use an important node when:

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

important

This is how a important node appears.

5.1.4.3.4  note

Use a note node to convey:

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

Note 1.  An example

note

This is how a note node appears.

5.1.4.3.5  tip

Use a tip node when:

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

Tip 1.  An example

tip

This is how a tip node appears.

5.1.4.4  Auxilary materials

5.1.4.4.1  figure

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

Figure 1.  An example

This is how a figure node appears.

5.1.4.4.2  table

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

Table 1.  An example

This is how a table node appears.

5.1.4.4.3  example

A sample application of an idea or thought.

Example 4.  An example

This is how a example node appears.

5.1.4.4.4  equation

A mathematical equation or formula.

Equation 1.  An example

This is how a equation node appears.

5.1.4.4.5  procedure

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

Procedure 1.  An example

This is how a procedure node appears.

5.1.4.5  Bibliographical nodes

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

5.1.4.5.1  reference

This node stores bibliography information about an information source that is relevant to your document.

If you wish to cite a certain source in several places in your document, start by creating a reference node first and then use a cite node (see cite) to perform the citation.

An example

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

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

6.1  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.2  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.3  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.4  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.5  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.6  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:

    ERBook 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.7  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.8  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.9  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.10  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.11  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.12  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

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.13  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.14  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.15  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.16  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.

References

  1. L. Watts, “Admonitions: Tips, hints, and Warnings”, in The KDE DocBook Authors guide, Chapter 13, [Online document], 22 September 2004 (Revision 1.00.00), [cited 8 December 2007], Available at http://l10n.kde.org/docs/markup/tips-hints-etc.html

  2. This is how a reference node appears.