[ANN] Gerbil 0.0.0 - a document generator

ruby-talk
1

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 <SNK at GNA dot ORG>

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

2

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 9, 2007, at 11:48 PM, Suraj Kurapati wrote:

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

--
we can deny everything, except that we have the possibility of being better. simply reflect on that.
h.h. the 14th dalai lama

3

Very nice work indeed!

martin

···

On Dec 10, 2007 12:18 PM, Suraj Kurapati <snk@gna.org> 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

4

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 10, 2007 5:31 PM, ara.t.howard <ara.t.howard@gmail.com> wrote:

On Dec 9, 2007, at 11:48 PM, Suraj Kurapati 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/

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

5

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

···

On Dec 11, 10:28 am, Vitor Peres <dodecapho...@gmail.com> wrote:

Note: parts of this message were removed by the gateway to make it a legal Usenet post.

On Dec 10, 2007 5:31 PM, ara.t.howard <ara.t.how...@gmail.com> wrote:

> On Dec 9, 2007, at 11:48 PM, Suraj Kurapati 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/

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.

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

6

Vitor Peres 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.

···

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

7

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

Alex Gutteridge

Bioinformatics Center
Kyoto University

···

On 13 Dec 2007, at 12:50, Suraj Kurapati wrote:

Vitor Peres 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.

8

Bernard Kenik 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 Hodel just fixed it today.

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

···

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

9

Alex Gutteridge 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

···

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