[Setools] About writing the Gjallar manual

[goran at krampe.se]

Hi folks!

I have been thinking a bit about how to write the manual for Gjallar.
Texinfo is the default multi output toolset in the GNU community, quite
interesting. But Gjallar also has the current idea of integrated context
help in a Swiki format. And I don't want to maintain the same
information twice. For printed output LaTeX is good - but I used Lout a
few years back and liked it much more.

So we already have the Swiki markup and I want to write a user guide,
reference manual etc which looks nice, has different output formats but
only uses the "simple" techniques:

- Auto generated TOC
- Headings, paragraphs, lists
- Embedded images
- Index
- Foot notes
- Handles URLs

The code I have for Swiki parsing (using a superset of the syntax in the
standard Swiki implementation) is easy to hack and to add/tweak in
different directions. So using a Swiki style as the original source
seems like a smart move. I also have added some macro processing
mechanisms to the Swiki syntax for more advanced things.

Then I want to produce HTML and PDF mainly. HTML is already half there -
since we are talking about a Swiki implementation after all! :) It
doesn't do TOC, index, footnotes but these things can be added later.

The PDF could be easily produced through "cross compiling" to Lout or
Texinfo. Lout is IMHO much simpler to use than LaTeX, has outstanding
features and produces great output.

An alternative - or additional route - would be to generate Texinfo thus
gaining other backends too. The Texinfo manual looks nice and must
surely be made using Texinfo itself. :) I skimmed it and Texinfo seems
kinda easy to use and has a good manual.

Since Swiki is hypertext and Lout/Texinfo are sequential we would
somehow need to indicate how it should be flattened when rendered to
those formats, but that seems like a simple problem. Having a special
Swiki page acting like a TOC seems like a simple way - and then some
mechanism to find "orphan" pages that are not linked from there.

How does it sound? Other ideas? Interest in helping out?

regards, Göran