[ANN] Gerbil 0.0.0 - a document generator

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!

      http://gerbil.rubyforge.org/guide.html

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

The release notes are shown at the bottom of this message.

Cheers!

What is Gerbil?

Gerbil is an extensible document generator based on eRuby
that outputs to any format you want: plain text, HTML,
LaTeX, UNIX man page, your own custom format, and so on.

Gerbil is lighter and more flexible than DocBook, Deplate,
and SiSU because it is small, fast, and lets you define
your own custom format. Furthermore, Gerbil is scriptable
unlike raw text generators such as AsciiDoc, txt2tags, and
Grutatxt because it lets you inject Ruby code directly into
your documents for advanced data processing and dynamic
document manipulation.

Gerbil is open-source software (see Section 1.2: License)
so feel free to contribute your improvements and discuss
your ideas in the project mailing list.

1.1 Features

• Composed of less than 200 lines of code!
• Lets you define your own document format.
• Supports any text-based output format.
• Generates a table of contents automatically.

1.2 License

Copyright 2006 Suraj N. Kurapati

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated
documentation files (the “Software”), to deal in the
Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:

• All copies and substantial portions of the Software
(the “Derivatives”) and their corresponding
machine-readable source code (the “Code”) must include
the above copyright notice and this permission notice.

• Upon distribution, the Derivatives must be accompanied
either by the Code or—provided that the Code is
obtainable for no more than the cost of distribution
plus a nominal fee—by information on how to obtain the
Code.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version 0.0.0

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 0.9.5 that prevents me from creating generating 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 regular
tarball/zip packages instead.

On Dec 9, 2007, at 11:48 PM, Suraj K. wrote:

About 70% of the development time
was consumed by documentation alone!

just guessing - but maybe that’s because it’s a insanely complete and
nice looking bit of documentation? :wink:

looks like a great project. thanks.

a @ http://codeforpeople.com/

On Dec 10, 2007 5:31 PM, ara.t.howard [email protected] wrote:

a @ http://codeforpeople.com/

I second that, it looks so nice! I actually felt like printing it,
because
it’s just so well-thought typographically.
Kudos for the project. Even if it weren’t great by itself, I’d feel good
just looking at the manual.

On Dec 11, 10:28 am, Vitor P. [email protected] wrote:

just looking at the manual.


Vitor P. (dodecaphonic)
------------------------------------http://twitter.com/dodecaphonic

Please do not use version 0.0.0 since gem searches for a gem version
greater than 0.

On Dec 10, 2007 12:18 PM, Suraj K. [email protected] wrote:

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!

      http://gerbil.rubyforge.org/guide.html

Very nice work indeed!

martin

Vitor P. wrote:

I second that, it looks so nice! I actually felt like
printing it, because it’s just so well-thought typographically.

That visual design (whitespace is key!) is actually the result of two
years of evolution: Having used LaTeX for research papers in college, I
grew fond of the stylized headings and careful use of whitespace. I
began to mimic these ideas in the HTML/CSS world through my projects
(user manuals and blogs mainly) and, fast forward to now, this is what
we get.

Nothing compares the brilliant typography of Knuth’s TeX, though.

Kudos for the project. Even if it weren’t great by itself,
I’d feel good just looking at the manual.

Wow, that just made my day! :slight_smile:
Thank you for the kind words.

On 13 Dec 2007, at 12:50, Suraj K. wrote:

we get.

Nothing compares the brilliant typography of Knuth’s TeX, though.

Any eta for the LaTeX format specification? This looks really cool and
I want to try writing a paper using it!

Alex G.

Bioinformatics Center
Kyoto University

Alex G. wrote:

Any eta for the LaTeX format specification? This looks really cool and
I want to try writing a paper using it!

My current priority is to iron out the bugs & nuances in the HTML
format. I’ll start on the LaTeX format next week, but really It’s not
that difficult. I’d be surprised if it took more than 1-2 afternoons to
implement. Refinement, on the other hand, can take longer.

What I mean is, the mapping of most LaTeX environments to Gerbil nodes
should be very straightforward. But deciding what kind of markup to use
for mapping bold, underline, emphasis, tables, image-embedding, etc. is
a more controversial matter. I’ll probably stick to a Textile-like
markup, or maybe just give up and throw the problem at the user and have
them insert these things manually.

On the other hand, Gerbil is an open-source project, so feel free to
start working on the LaTeX format spec file. We can talk more about
this on the project mailing list [1], if you would like.

Cheers!

[1] http://rubyforge.org/mailman/listinfo/gerbil-talk

Bernard K. wrote:

Please do not use version 0.0.0 since gem searches for a gem version
greater than 0.

I tried creating a gem with version ‘0.0.1’ and the same problem[1]
occurred. This is indeed a real bug in RubyGems 0.9.5, but thankfully
Eric H. just fixed it today.

[1]
http://rubyforge.org/tracker/?func=detail&atid=575&aid=16202&group_id=126

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs