I wrote a while ago a RSS pro­gram called uRSSus. I ex­pect I am the on­ly us­er of it be­cause it has some prob­lems (all of them my fault ;-) but I re­al­ly like it.

For a while now I have want­ed it to have pod­cast sup­port. The thing is... that al­ways seemed like a lot of work. Sure, us­ing phonon I can cre­ate an au­dio play­er and ev­ery­thing, but...

I am us­ing a HTML wid­get to dis­play the post­s, so I would have to find a way to add the au­dio play­er to the UI and ... too much work.

So, to­day I woke up and thought... wait a minute... Qt's HTML wid­get is based on We­bkit. And We­bkit sup­ports HTM­L5. And HTM­L5 has an "au­dio" tag.

So, if I fixed uRSSus to fetch the en­clo­sure links, and added them in the database, and then added this to the post tem­plate:

<?py for enclosure in  post.enclosures: ?>
  <audio autobuffer="Yes" controls="controls" src=#{enclosure.href}></audio><br>
<?py #end ?>

Would­n't that ac­tu­al­ly work? Well, yeah!

So there you have it, I was right not to im­ple­ment it, be­cause the eas­i­est way is to let Qt do it ;-)

The uRSSus doc is slow­ly grow­ing, so I hooked as­sis­tant to the UI. Not dif­fi­cult, but I have not seen it else­where.

Here's how:

As­sume the "Hand­book ac­tion" is called ac­tion_Hand­book. Set win­dow.as­sis­tant to None in __init__.

def on_action_Handbook_triggered(self, i=None):
    if i==None: return

    if not self.assistant or \
       not self.assistant.poll()==None:

        helpcoll=os.path.join(os.path.abspath(os.path.dirname(__file__)),\
                              'help',\
                              'out',\
                              'collection.qhc')
        cmd="assistant -enableRemoteControl -collectionFile %s"%helpcoll
        self.assistant=subprocess.Popen(cmd,
                                        shell=True,
                                        stdin=subprocess.PIPE)
    self.assistant.stdin.write("SetSource qthelp://urssus/doc/handbook.html\n")

And that's it. Now I ned to fig­ure out con­text help.

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

So all the lat­est re­leas­es of uRSSus have a hor­ri­ble bug: if you had nev­er used it, it would not work at al­l.

Good way to get new user­s, mo­ron!

Thanks to a bug re­port on the Arch pack­age, this is fixed in to­day's 0.2.13 re­lease.

Yay!

An­nounc­ing re­lease 0.2.12 or uRSSus a RSS/Atom ag­gre­ga­tor.

This re­lease fix­es the big crashy up­dater bug in 0.2.11, and makes some mi­nor im­prove­ments, like nicer date dis­play, and a xdg re­source in­stall­er.