[ANN] erbook 4.0.0 (was previously named Gerbil)

[Suraj Kurapati]

erbook : write books and documents in eRuby
===========================================

erbook is an extensible document processor that emits HTML
(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 (200 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 4.0.0

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.

1 Caution

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

2 Thanks

the new project logo

• Jens Vierbuchen contributed the the cartoon owl sitting
on a book drawing that is used in the new project logo.

• Maunika Gosike provided usability feedback to help
improve the HTML format.

3 Improvements

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

• Added admonition icon for HTML <blockquote> element.

• Revised the user manual and added new content.

3.1 Usability

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

 

[Saji N. Hameed]

Hi Suraj,

erbook : write books and documents in eRuby
===========================================

erbook is an extensible document processor that emits HTML
(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.

Nice software - hope to see the LaTex formatter coming out soon.
I was wondering if the markup could be made simpler. Is the eruby
template the best for this - For example, there are so many extra
things to type in the following

<% chapter "Introduction" do %>
<% end %>

compared to say \chapter{Introduction} in TeX, for example

saji
---

erbook is a light (200 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 4.0.0

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.

1 Caution

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

2 Thanks

the new project logo

??? Jens Vierbuchen contributed the the cartoon owl sitting
on a book drawing that is used in the new project logo.

??? Maunika Gosike provided usability feedback to help
improve the HTML format.

3 Improvements

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

??? Added admonition icon for HTML <blockquote> element.

??? Revised the user manual and added new content.

3.1 Usability

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

--
Saji N. Hameed

APEC Climate Center +82 51 668 7470
National Pension Corporation Busan Building 12F
Yeonsan 2-dong, Yeonje-gu, BUSAN 611705 (e-mail address removed)
KOREA

 

[Suraj Kurapati]

Hi,

Nice software - hope to see the LaTex formatter coming out soon.

Thanks. I'm planning to use Maruku's Markdown-to-LaTeX conversion
ability to achieve this. This was one of the reasons I switched from
RedCloth (Textile) to Maruku (Markdown).

I was wondering if the markup could be made simpler. Is the eruby
template the best for this - For example, there are so many extra
things to type in the following

<% chapter "Introduction" do %>
<% end %>

compared to say \chapter{Introduction} in TeX, for example

Good suggestion, the TeX equivalent is indeed shorter. Unfortunately,
the <% eRuby syntax %> is what it is and I don't wish to reinvent eRuby.
:-(

You could try turning the document inside-out:

<%
chapter "Introduction" do
"some content here" +

section "Something" do
"and in here"
end +

"more content here"
end
%>

This kind of usage is currently supported by erbook.

I also suggest using the abbreviation and auto-complete features of your
text editor to reduce most of the typing. In my case, I just type
[p][r][TAB] to get <% this %> and my cursor is placed inside. And
[p][r][c][TAB] gives me:

<% chapter "CURSOR_1" do %>
CURSOR_2
<% end %>

where CURSOR_1 denotes the inital cursor position and CURSOR_2 is where
the cursor goes when I press TAB from CURSOR_1.

Cheers.

 

[Saji N. Hameed]

You could try turning the document inside-out:

<%
chapter "Introduction" do
"some content here" +

section "Something" do
"and in here"
end +

"more content here"
end
%>

hmmm...i have to use double quotes to delimit the text - not very convenient.

According to eruby entry in Wikipedia http://en.wikipedia.org/wiki/ERuby ,
the following are equivalent, however the output from erbook is different
for each.

<% chapter "Introduction" do %>
This is a chapter
<% end %>

% chapter "Introduction" do
This is a chapter
% end


Compilation is ok, in case of the second way - however output is something
like

<div id="content">% chapter "Introduction" do
This is a chapter
% end

</div>

For the first one, the correct html is returned as below:

<div class="chapter">
<h1 class="title" id="Introduction">
Chapter&nbsp;<a class="list" title="Return to table of contents" href="#rev:Introduction">1</a>
<br/>
<big><a class="here" title="Permanent link to this section" href="#Introduction">Introduction</a></big>
</h1>
<div class="content"><pre>This is a chapter</pre></div>
</div>
</div>

saji

 

[Suraj Kurapati]

Hi,

hmmm...i have to use double quotes to delimit the text - not very
convenient.

Well, you could also use Ruby's %Q{} or %q{} or <<EOS syntax for writing
multi-line strings. But I agree, it is ugly.

According to eruby entry in Wikipedia http://en.wikipedia.org/wiki/ERuby
the following are equivalent, however the output from erbook is
different for each.

Excellent find! I completely forgot about that eRuby capability. It is
definitely more readable with a single % at the beginning of a line.

<% chapter "Introduction" do %>
This is a chapter
<% end %>

% chapter "Introduction" do
This is a chapter
% end

They were treated differently because the latter was not enabled in
erbook's usage of eRuby. If you apply the following patch, then the
latter will work:

diff --git a/bin/erbook b/bin/erbook
index c5bf5bd..568c7d8 100755
--- a/bin/erbook
+++ b/bin/erbook
@@ -47,6 +47,9 @@ class Template < ERB
# silence the code-only <% ... %> directive, just like PHP does
args[0].gsub!( /^[ \t]*(<%[^%=]((?!<%).)*?[^%]%>)[ \t]*\r?\n/m ) {
$1 }

+ # enable Ruby code processing for lines beginning with %
+ (args[2] ||= '') << '%'
+
# use @buffer to store the result of the ERB template
args[3] = buffer
super(*args)


I'm currently refactoring the code to be more object-oriented, and I
will include the above patch in the next release.

Thanks for your help!

 

[Suraj Kurapati]

They were treated differently because the latter
was not enabled in erbook's usage of eRuby.

This has been fixed in erbook 5.0.0.
Indented usage is also supported now:

% chapter "Introduction" do
This is a chapter

% section "Hello" do
This is a section
% end

The time is:
%= Time.now

% end

Cheers.