I am fi­nal­ly pub­lish­ing my Lati­noWare 2008 tu­to­ri­al, in re­vised and ex­pand­ed for­m. It will prob­a­bly be a 10-­part se­ries, and here is ses­sion 2.

See al­so ses­sion 1.

Wh­y? It's ba­si­ca­lly un­do­cu­men­te­d, it looks ugly and it does­n't su­pport tem­pla­te inhe­ri­tan­ce, whi­ch in this ca­se is ve­ry use­fu­l, be­cau­se I am ac­tua­lly doing two ve­ry si­mi­lar pla­ne­ts: 1 2.

So, sin­ce I saw a plu­gin to use Ve­llum tem­pla­tes, I thou­gh­t, why not use my fa­vou­ri­te tem­pla­ting li­bra­ry (Mako) ins­tea­d?

It turns out to be ve­ry ea­sy to do!

Just put this in your plu­gins fol­der and start using Mako tem­pla­tes (ye­s, the pla­ne­t's con­fig and stu­ff is in gi­thub. Why no­t?).

# -*- coding: utf-8 -*-
import rawdoglib.plugins

from mako.template import Template
from mako.lookup import TemplateLookup
from mako import exceptions

class MakoPlugin:
    def __init__(self):
        self.lookup = TemplateLookup(directories=['.'],\
                              output_encoding='utf-8',\
                              encoding_errors='replace')

    def fill_template(self,template, bits, result):
        self.lookup.put_string('actual',template)
        t=self.lookup.get_template('actual')
        try:
            r=t.render_unicode(**bits)
        except:
            r=exceptions.html_error_template().render()
        result.value=r
        return False

p = MakoPlugin()
rawdoglib.plugins.attach_hook("fill_template",\
                              p.fill_template)

Yu­p, 20 li­nes of co­de!

To­day I woke up at 6AM. I had noth­ing to do un­til 9, but I woke up and could­n't sleep again.

So, what can I do? I hacked rst2qhc a bit more :-D

Since this is a small pro­jec­t, it is quick­ly ap­proach­ing fea­ture com­plete sta­tus (there is re­al­ly on­ly so much this thing can do).

So, what's new?

• Pass­ing op­­tions to rst2ht­m­l, so you can do things like set stylesheet­s.

• Sup­­port for a man­i­fest file, so you can list what files should be em­bed­d­ed in the help­­file.

• Fixed project sup­­port. Now you can op­­tion­al­­ly ask rst2qhc to cre­ate a qhcp file that will build your doc­u­­men­t.

• Bet­ter, more com­­plete ex­am­­ple that dis­­­plays most fea­­tures.

I have on­ly one thing left in my TODO, which is call­ing the HTML writ­er via API in­stead of via sys­tem() be­cause that way there is no need to de­fine the key­word role in the doc­u­men­t, and I can add syn­tax high­light­ing via pyg­ments.

Since I now do have work to do, I will just re­lease 0.2 now ;-)

You can get it from the usu­al place: http://rst2qhc.­google­code.­com

And here's a sam­ple of the in­put/out­put:

I de­cid­ed to add a man­u­al for uRSSus. Since it's a Qt ap­p, I checked how to do one of those neat help files, like the ones that come with Qt app­s.

It turns out it's not so sim­ple to cre­ate one of those.

You need to cre­ate your help in one or more HTML files, then cre­ate a XML file that de­scribes what each file is, ref­er­ences for each sec­tion, and ref­er­ences for each key­word you want in the in­dex.

For any re­al-life-­size doc­u­men­t, that's go­ing to be in­cred­i­bly an­noy­ing.

So, I took my usu­al es­cape route when I don't want to do grunt work on doc­s: Do­cu­tils.

Specif­i­cal­ly, I wrote rst2qhc which takes one (or more) re­struc­tured text files, and cre­ates a nice and clean Qt Help Project file from them, in­clud­ing sec­tion ti­tles, ref­er­ences and key­word­s, which you mark on the text us­ing the 'key­word' role.

What does this mean? Let me be graph­i­cal:

The one on the right is nice to read. The one on the left is nice to write. The ar­row in the mid­dle is rst2qhc :-)

And here's how the gen­er­at­ed qhp file looks for a triv­ial out­line of a man­u­al (and the rea­son why I don't want to do this man­u­al­ly ;-):

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>urssus</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="Unknown">
        <filterAttribute></filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute></filterAttribute>
        <toc>
            <section title="The uRSSus Handbook" ref="manual.html">
                <section title="Introduction" ref="manual.html#introduction"/>
                <section title="Quick Start" ref="manual.html#quick-start"/>
                <section title="Configuration" ref="manual.html#configuration"/>
                <section title="Credits and License" ref="manual.html#credits-and-license"/>
            </section>
        </toc>
        <keywords>
                <keyword name="what can you" ref="manual.html#what-can-you-do-using-urssus"/>
                <keyword name="quick" ref="manual.html#quick-start"/>
                <keyword name="main window" ref="manual.html#the-main-window"/>
        </keywords>
        <files>
                <file>manual.html</file>
        </files>
    </filterSection>
</QtHelpProject>

Al­so, as a bonus, you can cre­ate PDF, La­TeX, HTML and ODT files from the same source (heck, you can cre­ate freak­ing man pages).