Tutorial PDF

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 :wink:

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


can you post the docbook source file as well?


George M. 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 a block of text. note:: 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. end-note:: ?>

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 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 :wink:

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!


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.

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