08 June 2008

KDelicious documentation now online

I've just uploaded "the KDelicious Handbook", that is the documentation for all old (and new) KDelicious features.

This was the first time I used docbook to generate this sort of files, but I thought that it would have been nice to follow KDE guidelines, after all it's a KDE add-on!

Advantages of docbook: you write the docs once, then you can have as many stylesheets you want and get consistent output for different media. Using the KDE xsl files, it's really a snap.

Disadvantages: you have to write lots of markup, which can be painful; Emacs' SGML mode can help a bit there. Translation processes must be terrible, you have to re-write pretty much everything as there's no easy gettext-like method to keep style and content separated.

I've also written a small shell script to repeat the process, as I know tomorrow I'll forget everything I've learnt about meinproc and where the xsl templates are (/usr/share/apps/ksgmltools2/customization). The script also appends the Sourceforge logo to all pages meant for the web, as it's required by the SF policy (thanks to the wonders of sed). And of course it's all been put under version control. Am I "Pragmatic" or what?

2 comments:

Giulio Piancastelli said...

SGML mode? Ahem. What about nxml?

And... haven't the world (well, at least my world) settled out on jEdit + XML Plugin for the best Open Source XML-oriented editor available?

GiacomoL said...

uh, I completely forgot about nxml, I'll give it a go... anyway, I'm trying to learn emacs as much as I can, that's why I didn't go for jEdit (which, by the way, supports several emacs shortcuts, I found).
The main feature of the jEdit XML plugin for me, anyway, is tag auto-closing, which emacs does (Ctrl-C + /). I also liked the XML Indenter plugin, but I cannot find in recent versions... so might as well give emacs a chance ;)