Forum: Ruby [ANN] erbook 5.0.0

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Suraj K. (Guest)
on 2008-11-23 09:21
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. ;-)

  • 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.
Dean W. (Guest)
on 2008-11-23 18:51
(Received via mailing list)
Interesting. I've been using AsciiDoc for DocBook creation. It's good
to have a family of alternatives.
Diego V. (Guest)
on 2008-11-23 20:40
(Received via mailing list)
On 23 Nov, 07:17, Suraj K. <removed_email_address@domain.invalid> 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
Suraj K. (Guest)
on 2008-11-23 22:02
Diego V. wrote:
> On 23 Nov, 07:17, Suraj K. <removed_email_address@domain.invalid> 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. ;-)

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

Thanks for your consideration.

[1]: http://snk.tuxfamily.org/lib/erbook/#Version-numbers
[2]: http://snk.tuxfamily.org/lib/erbook/#Theory-of-operation
[3]: http://snk.tuxfamily.org/lib/erbook/#HelloWorld
Suraj K. (Guest)
on 2008-11-23 22:40
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.  :-)

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

Thanks for your consideration.
Gregory B. (Guest)
on 2008-11-24 07:04
(Received via mailing list)
On Sun, Nov 23, 2008 at 11:47 AM, Dean W. <removed_email_address@domain.invalid>
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
Suraj K. (Guest)
on 2008-11-24 19:22
Gregory B. wrote:
> On Sun, Nov 23, 2008 at 11:47 AM, Dean W. <removed_email_address@domain.invalid>
> 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.
:-)

> 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]: http://powerman.name/doc/asciidoc
[2]: http://daringfireball.net/projects/markdown/
[3]: http://snk.tuxfamily.org/lib/erbook/#Text-to-XHTML...
James G. (Guest)
on 2008-11-24 19:39
(Received via mailing list)
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
Suraj K. (Guest)
on 2008-11-24 19:56
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:

http://en.wikipedia.org/wiki/Code_folding#Software...
Gregory B. (Guest)
on 2008-11-24 20:16
(Received via mailing list)
On Mon, Nov 24, 2008 at 12:18 PM, Suraj K. 
<removed_email_address@domain.invalid> 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 :)
It's just a though though, because right now I don't even have a need
for that.

-greg
This topic is locked and can not be replied to.