Re: [exim-dev] Standardizing the Exim documentation

Pàgina inicial
Delete this message
Reply to this message
Autor: Christoph Kliemt
Data:  
A: Philip Hazel
CC: exim-dev
Assumpte: Re: [exim-dev] Standardizing the Exim documentation
Hi!

sorry for sending a reply twice... i sent the first mail a bit to
early.. ;-)

Philip Hazel <ph10@???> writes:

> I have spent a lot of time recently investigating what might be done to
> convert the Exim documentation sources (main manual and filter document)
> to some kind of standard text format. The executive summary is that I
> think it is not unreasonable to consider moving to XML DocBook format.


I played round with XML DocBook a few times. My personal impression:
Overkill for documentation[1], stylsheets sometimes do not work or need
a speclial xslt-processor.

[...]

> The document is 6 pages long (in the PDF version). Please send me your
> comments, views, and corrections to anything that I might have got
> wrong.


Ok.. here it comes.

2. What documentation standard should we use?

Since XML docbook is a moving target i am afraid that there has to be
done a lot of superfluous work just to keep up with current versions.

Workaround: Steal a simple dtd and extend it if needed. I have done so
with cocoons documnet dtd. Its easy and easy to extend.

3. Maintaining the master source

Edit the xml-source with a "validating" xml-Editor. I use an sgml-mode
in xemacs.

4. Generating output from Docbook

Cocoon is worth to have a look at. http://cocoon.apache.org/ Ok, its a
web development framework, but is has everything needed, including
"serializers" to pdf,ps and svg2jpeg, svg2png, svg2tiff etc.

5. What is still outstanding?

figures: what about svg?

Texinfo: If there is a xml-masterfile i do not see why there cant be
stylesheets that do that transformation. I did not have a closer look at
this, but google delivered 940 hits for "xslt stylesheet texinfo".

regards

christoph

Footnotes:
[1] for the needs of exim documentation.

--
Christoph Kliemt
entici GmbH, Goldenbergstr.1
D 50354 Hürth
Phone + 49 (0) 22 33 92 82 44