Peter Seibel writes: > 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. >
I like this idea. While I've used docbook a bit, the true reality of its promised flexibility has not really been realised, primarily due to the lack of easy to use, reliable and consistent utilities for processing docbook XML. When I first started to look at XML and docbook, I was quite surprised with how much time, trial and error it took to select the appropriate utilities for generating outputs in various formats. Once you moved away from docbook to HTML, things get vary fuzzy. There are various utilities, some in Java, some C programs and some which require translation into yet a second format prior to the final format and all of them seem to have limitations or well known bugs. The maintenance work required to keep everything in a stable state seems out of proportion when compared to the desired outcomes. A reliable CL based processor which takes a docbook file as input and which can generate output in various formats, HTML, PDF, TexInfo, Latex, RTF etc, would be really useful and something which even the non-lisp community might find beneficial over the collection of unrelated utilities currently used. Tim _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
