[ANN] erbook 5.0.0

ruby-talk
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 http://snk.tuxfamily.org/lib/erbook/ 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!
    ;-)

  • 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.
--
Posted via http://www.ruby-forum.com/.

2

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

···

On Sun, Nov 23, 2008 at 1:17 AM, Suraj Kurapati <snk@gna.org> 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.

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 http://snk.tuxfamily.org/lib/erbook/ 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!
   ;-)

• 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.
--
Posted via http://www.ruby-forum.com/\.

--
Dean Wampler
http://www.objectmentor.com
http://www.polyglotprogramming.com
http://www.aspectprogramming.com
http://aquarium.rubyforge.org
http://www.contract4j.org

3

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

···

On 23 Nov, 07:17, Suraj Kurapati <s...@gna.org> 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.

4

Diego Virasoro 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 versions[1].

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 works[2] and providing examples
of how to create a custom format[3] 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.

[1]: ERBook 9.2.1 — Write books, manuals, and documents in eRuby
[2]: ERBook 9.2.1 — Write books, manuals, and documents in eRuby
[3]: ERBook 9.2.1 — Write books, manuals, and documents in eRuby

···

On 23 Nov, 07:17, Suraj Kurapati <s...@gna.org> wrote:

--
Posted via http://www.ruby-forum.com/\.

5

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

···

On Sun, Nov 23, 2008 at 11:47 AM, Dean Wampler <deanwampler@gmail.com> wrote:

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

--
Technical Blaag at: http://blog.majesticseacreature.com | Non-tech
stuff at: http://metametta.blogspot.com

6

Suraj Kurapati wrote:

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

···

--
Posted via http://www.ruby-forum.com/\.

7

Gregory Brown 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 shortcuts[1].

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

I've looked at AsciiDoc before, revisited[1] 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
Markdown[2] (which is quite smart and preserves readability) as the
default content formatting system, but any other formatting system can
be easily substituted[3] 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.

[1]: AsciiDoc cheatsheet
[2]: Daring Fireball: Markdown
[3]: ERBook 9.2.1 — Write books, manuals, and documents in eRuby

···

On Sun, Nov 23, 2008 at 11:47 AM, Dean Wampler <deanwampler@gmail.com> > wrote:

--
Posted via http://www.ruby-forum.com/\.

8

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

James Edward Gray II

···

On Nov 24, 2008, at 11:18 AM, Suraj Kurapati 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.

9

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

···

On Mon, Nov 24, 2008 at 12:18 PM, Suraj Kurapati <snk@gna.org> wrote:

That's already possible:

% cat your_file.erb | erb | asciidoc

--
Technical Blaag at: http://blog.majesticseacreature.com | Non-tech
stuff at: http://metametta.blogspot.com

10

James Gray wrote:

···

On Nov 24, 2008, at 11:18 AM, Suraj Kurapati 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:

--
Posted via http://www.ruby-forum.com/\.