[Setools] About writing the Gjallar manual

[Stéphane Ducasse]

my suggestions are:
	- write as much as possible in the class comments
	- use the latex generator lukas or damien wrote to extract comments
	- glue that with images. or even past images as methods
this way everyhitng is in the code.

Stef

On 4 août 06, at 14:53, goran at krampe.se wrote:

> 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
> _______________________________________________
> Setools mailing list
> Setools at lists.squeakfoundation.org
> http://lists.squeakfoundation.org/mailman/listinfo/setools