[ANN] erbook 5.0.0

Ruby
1

erbook : write books and documents in eRuby

erbook is an extensible document processor that emits XHTML
(web page), LaTeX (PDF), man (UNIX manual page), plain text,
and any document format you can imagine from eRuby templates
that allow scripting and dynamic content generation.

erbook is a light (210 source lines of code), extensible
(create your own document formats), and flexible (your content
is scriptable) alternative to DocBook, Deplate, and SiSU.

Visit ERBook 9.2.1 — Write books, manuals, and documents in eRuby for more information.

            * * * RELEASE NOTES * * *

erbook 5.0.0

Contents

• 1 Caution
• 2 Improvements
• 3 Repairs

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.

1 Caution

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

• Removed the $use_icons parameter from the XHTML format.
Now, icons are always used, whether you like it or not!
:wink:

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

2 Improvements

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

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

3 Repairs

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

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

2

Interesting. I’ve been using AsciiDoc for DocBook creation. It’s good
to have a family of alternatives.

3

On 23 Nov, 07:17, Suraj K. [email protected] wrote:

erbook : write books and documents in eRuby

erbook is an extensible document processor that emits XHTML
(web page), LaTeX (PDF), man (UNIX manual page), plain text,
and any document format you can imagine from eRuby templates
that allow scripting and dynamic content generation.

I am sorry, I don’t want to sound argumentative but when are you going
to be able to emit LaTeX? It’s version 5.0 already, and since the
beginning LaTeX support was supposed to be there. In fact you even
advertise it here. However from your website I gather you haven’t even
started on LaTeX support.

Dunno, but it sounds a bit misleading…

(to be honest I’ve been quite interested in this project, but so far
every version falls short of what I need)

Diego

4

Suraj K. wrote:

Diego V. wrote:

(to be honest I’ve been quite interested in this project, but so far
every version falls short of what I need)

erbook is an open source project after all… please don’t forget that
I’m doing this in my free time, for the benefit of humankind. :slight_smile:

Err, my response above seems to imply that because erbook is an open
source project, it falls short of what you need every time. That is not
true.

What I meant to say is that, if you have an urgent need (or better yet:
a developer’s itch) for LaTeX support in erbook, then patches are
welcome. :slight_smile:

Thanks for your consideration.

5

Diego V. wrote:

On 23 Nov, 07:17, Suraj K. [email protected] wrote:

erbook : write books and documents in eRuby

erbook is an extensible document processor that emits XHTML
(web page), LaTeX (PDF), man (UNIX manual page), plain text,
and any document format you can imagine from eRuby templates
that allow scripting and dynamic content generation.

I am sorry, I don’t want to sound argumentative but
when are you going to be able to emit LaTeX?

It depends really, as I have other open source projects to tend to and
ups-and-downs in motivation to deal with. :wink:

It’s version 5.0 already,

The version numbers do not indicate the completeness of the project, but
rather the magnitude of change between versions1.

and since the beginning LaTeX support was supposed
to be there. In fact you even advertise it here.

Good point. When I started this project, my intention was to describe
what the completed project would be like in the description.

I will update the project description to clarify what functionality is
present now, and what is planned for the future.

However from your website I gather you haven’t even started on LaTeX support.

True. I just haven’t had the developer’s itch to be motivated enough to
work on the LaTeX format yet.

I hoped that, by explaining how erbook works2 and providing examples
of how to create a custom format3 in the user manual, someone who had
the developer’s itch would begin the LaTeX format and contribute
patches.

(to be honest I’ve been quite interested in this project, but so far
every version falls short of what I need)

erbook is an open source project after all… please don’t forget that
I’m doing this in my free time, for the benefit of humankind. :slight_smile:

Thanks for your consideration.

6

On Sun, Nov 23, 2008 at 11:47 AM, Dean W. [email protected]
wrote:

Interesting. I’ve been using AsciiDoc for DocBook creation. It’s good
to have a family of alternatives.

Though erbook sounds like a very cool project to watch, AsciiDoc just
made my life a lot easier. Thanks for mentioning this tool, it just
saved me a ton of time typesetting my book.

Suraj, you may want to look into how AsciiDoc works, as the kind of
smarts it offers for inferring the structure of your document combined
with the power of ERB could be quite exciting.

-greg

7

On Nov 24, 2008, at 11:18 AM, Suraj K. wrote:

Indentation also facilitates trivially simple code-folding in your
text
editor, which isn’t possible for these formatting systems unless you
set
up regexps to define which lines define the begin/end and depth (the
hardest part!) of structural elements.

That totally depends on the text editor. For example, indentation
based code folding is one thing TextMate does not do well.

James Edward G. II

8

Gregory B. wrote:

On Sun, Nov 23, 2008 at 11:47 AM, Dean W. [email protected]
wrote:

Interesting. I’ve been using AsciiDoc for DocBook creation. It’s good
to have a family of alternatives.

Though erbook sounds like a very cool project to watch, AsciiDoc just
made my life a lot easier. Thanks for mentioning this tool, it just
saved me a ton of time typesetting my book.

Yes, AsciiDoc seems to provide a lot of nice time-saving shortcuts1.

Suraj, you may want to look into how AsciiDoc works,

I’ve looked at AsciiDoc before, revisited1 it again now, and realized
that…

as the kind of smarts it offers for inferring the structure of

… this is exactly what I do not want to do.

erbook focuses only on the explicit structure (as defined by method
calls) of your document, and lets you organize your document using
indentation (just like source code) as opposed to adding syntactical
divisions between adjacent structural elements, which I find as the weak
point in all plain-text-to-whatever formatting systems I’ve seen so far.
Indentation also facilitates trivially simple code-folding in your text
editor, which isn’t possible for these formatting systems unless you set
up regexps to define which lines define the begin/end and depth (the
hardest part!) of structural elements.

I leave the smarts to the plain-text-to-whatever formatting system the
user wants to use to markup their content. So far I’ve provided
Markdown2 (which is quite smart and preserves readability) as the
default content formatting system, but any other formatting system can
be easily substituted3 in its place.

One can even use AsciiDoc as the content formatting system for erbook.
:slight_smile:

your document combined with the power of ERB could be quite exciting.

That’s already possible:

% cat your_file.erb | erb | asciidoc

Thanks for your suggestion.

9

James G. wrote:

On Nov 24, 2008, at 11:18 AM, Suraj K. wrote:

Indentation also facilitates trivially simple code-folding in your
text editor, which isn’t possible for these formatting systems unless you
set up regexps to define which lines define the begin/end and depth (the
hardest part!) of structural elements.

That totally depends on the text editor. For example, indentation
based code folding is one thing TextMate does not do well.

I’ve happily used indentation-based code folding in Vim and jEdit, so I
assumed that it would at least be a basic feature of other
popular/modern text editors:

10

On Mon, Nov 24, 2008 at 12:18 PM, Suraj K. [email protected] wrote:

That’s already possible:

% cat your_file.erb | erb | asciidoc

Well of course, but I was suggesting something a little more polished
and domain specific than that :slight_smile:
It’s just a though though, because right now I don’t even have a need
for that.

-greg