Forum: Nitro Tutorial PDF

Announcement (2017-05-07): is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see and for other Rails- und Ruby-related community platforms.
Bd10252dc68b39171cc9bf5f74bcb9f1?d=identicon&s=25 Arne Brasseur (Guest)
on 2007-11-30 08:08
(Received via mailing list)
Attachment: nitro_todolist_20071130.pdf (20 KB)
Hi Nitro lovers,

This is the tutorial I wrote a while ago, only this time in PDF format.
There's probably stuff that is already obsolete, but since we're posting
PDF's for the "geekend" anyway ;)

The difference is that this one is generated from docbook that is
generated from a bunch of text files with some minimal markup. Docbook
is great and flexible and all of that, but hand editing is still
tedious. I tried it for about an hour and it started to get really on my

The proposal is to use such a hybrid approach for the official Nitro
docs. Targeting docbook we can get high quality docs in several output
formats, while editing in a format with the least amount of mental
overhead. It's still possible to fall back to "raw" docbook should it be

7a4e995e378ef66de0ceaea5e1381ee1?d=identicon&s=25 George Moschovitis (Guest)
on 2007-11-30 09:09
(Received via mailing list)
can you post the docbook source file as well?

Bd10252dc68b39171cc9bf5f74bcb9f1?d=identicon&s=25 Arne Brasseur (Guest)
on 2007-11-30 10:00
(Received via mailing list)
Attachment: marky-0.1.2.gem (7 KB)
Attachment: marky-0.1.2.tgz (3 KB)
Attachment: nitro-article-fo.xsl (324 Bytes)
Attachment: nitro-article-html-chunks.xsl (396 Bytes)
George Moschovitis schreef:
> can you post the docbook source file as well?

No problem, here it is.

I was gonna keep the custom markup stuff for myself until it's a little
more polished but here it is in true release early style. I'll be out of
town till somewhere next week so whoever wants can have a look at it in
the meanwhile. Think of it as a proof of concept.

Installing the marky gem should give you the marky command which takes
an xml file as arguments which can contain processing instructions like

  <?marky-include href="01_intro.mky" root="sect1" ?>

  <?marky-parse root="sect1"
title:: Example marky text

A block of text is converted to <para>a block of text</para>.

Open and closing tags look like this. If there's just a single line
inside put it after the opening tag and omit the closing tag. Tags can
be nested.


The basic idea is to convert blocks of text following and followed by a
double new-line to paragraphs. Text inside paragraphs will be scanned
for certain "wingnuts" (e.g. _underscores_ or ^these thingies^) which
are shorthands for certain tags. This is not implemented yet.

The current implementation uses Rexml to build the structure and then
dump to xml which has the effect that any XML in the document gets
converted to entities. This obviously has to change because we want to
be able to simply use XML inline. So either text needs to explicitly be
parsed by rexml or we just do our conversions without rexml leaving
intact what is there. The downside is that either way ampersands and
less-than signs need to be written as entities.

Also in that case a handy shortcut for <programlisting><![CDATA[ ...
]]></programlisting> would be... euh, handy.

Ok that's a bit of a dump of my current thought processes and I could
have had a little more sleep but anyway, as always, enjoy!

Oh yeah to use it, make sure you have xsltproc, put the xml, mky, xsl
and css files in a directory and try this

   marky tutorial.xml | xsltproc nitro-article-html-chunks.xsl -

If that went well you should have a bunch of html files, so try "firefox
-new-tab index.html" and marvel at the beauty ;)

If you want the pdf you should get apache-fop. Similar procedure

  marky tutorial.xml | xsltproc nitro-article-fo.xsl - > fop.xml

and then

  fop fop.xml tutorial.pdf

The xsl files import stylesheets from docbook-xsl, and the html one sets
a parameter to use the supplied css file. The idea is to build on these
to create a customized look for the nitro docs.

The nitro_todolist.xml is the docbook as is generated by marky.

As I said, Enjoy!

5f65ee21e577b094753cd7d854dc39e4?d=identicon&s=25 Matthew B Gardner (Guest)
on 2007-12-09 07:10
(Received via mailing list)
Using the darcs install, here are the current issues for this tutorial:

Need to install RedCloth and xml-simple.
app.adapter=:mongrel at line 6 in debug.rb causes:

INFO: Starting Mongrel server in debug mode, listening at
`const_get': uninitialized constant Raw::MongrelAdapter (NameError)

I'm not sure if it's just my system, but creating my own version of
or using your todolist1, I get the "You have successfully installed
index page. Was able to get that after I commented out the mongrel line.

The FormHelper mixin works fine now, by the way (at least in your
todolist1) -- was that updated today?

Hopefully this helps some.
Bd10252dc68b39171cc9bf5f74bcb9f1?d=identicon&s=25 Arne Brasseur (Guest)
on 2007-12-09 09:20
(Received via mailing list)
Matthew B Gardner schreef:
> Using the darcs install, here are the current issues for this tutorial:
> Need to install RedCloth and xml-simple.
RedCloth is supposed to be optional, according to raw/README.
raw/util/markup uses it by default, but this can be overridden.

The only problem is that at the top of the file is a require "redcloth",
so you won't get far without it. The gemspec also references redcloth as
a dependency. On the other hand, there is a check in the method
expand_redcloth to see if it's installed or not. For this to make sense
the require and the dependency have to go off course.

So, optional or not?

This topic is locked and can not be replied to.