On Jan 9, 2006, at 2:19 PM, David Trudgett wrote: > On Friday 2006-01-06 at 15:50:34 +0900, JC Helary wrote: >> >> On 2006/01/06, at 14:40, Tim Cross wrote: >>> In reality, it would be good if documentation was in an even more >>> 'generic' form, like docbook or sgml so that there is more >>> flexibility in final format choices. However, decent authoring >>> environments for working with such formats as docbook are >>> expensive or, in the case of free and open source, still quite >>> limited/slow to work with. >>> >>> I guess the main thing is that the format used is less important >>> than consistency - though there is the open question regarding >>> whether the use of texinfo as the 'official' documentation for a >>> project actually results in less useful documentation than would >>> occur with a more widely known markup language. >> >> It would be nice if the source format was an easily translatable >> format: are there xliff convertors for it ? for example. >> >> .po based conversion are ok, but localisation standards have greatly >> evolved in the last few years and opensource tools are following >> very close. >> >> Docbook-xml would seem like a good choice. > > I tend to use docbook-xml myself (though I haven't used it for > software documentation) and would have thought it an obvious > choice. I've never used TeXinfo, but if it's anything like LateX, then > docbook would be at a higher abstraction level, better separating > content from presentation. Adequate free tools seem to be available to > work with it, but it can be painful to get set up initially. Texinfo > could be easier in that regard, perhaps. > > Anyway, that's just my 2c worth, because I was surprised docbook-xml > wasn't mentioned earlier.
Just to throw another hat in the ring, it might be interesting to try using Lisp itself. Between the ease of generating HTML from s- expressions and generating nice PDF output using Marc Battyani's cl- typesetting library, it might be a useful exercise to generate a native, Lisp-programmable documentation generation system. A starting point might be my own Markup library: <http://www.gigamonkeys.com/lisp/markup/> I am by no way suggesting that this is as mature as something like texinfo or docbook-xml but it has the advantage that using it, and adapting it to our actual needs will force us to eat our own dogfood and will result in the automatic gardening of the libraries we use. In fact, an excellent gardener's project (one suggested to me when we were first starting by Edi Weitz) would be to write a user manual for cl-typesetting and cl-pdf. They are, I can attest, excellent libraries, but have almost no documentation. And of course the documentation for those libraries, if no others, should be generated using the libraries themselves. So if someone wants to spend some time coming to grips with a sophisticated Lisp library well enough to be able to explain it to others, I'd recommend that as not-to-huge project. -Peter -- Peter Seibel * [EMAIL PROTECTED] Gigamonkeys Consulting * http://www.gigamonkeys.com/ Practical Common Lisp * http://www.gigamonkeys.com/book/ _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
