[Exim-dev] Documentation

Top Page
Delete this message
Reply to this message
Author: Tony Finch
Date:  
To: exim-dev
Subject: [Exim-dev] Documentation
I've had a brief exchange with Nik Clayton who is the FreeBSD
Documentation Project leader, to ask him about how close their tools are
to the functionality that Exim needs. His reply follows.

I'm planning to use FreeBSD for the dev box because of its improved
version of CVS; it's useful that it helps with the documentation
infrastructure.

Do we have any people on the list who know DocBook, XML, and XSL?

> Assuming you were building the docs on FreeBSD, the FreeBSD doc build
> .mk infrastructure plus the dependencies on the docproj/ port should
> "just work". You can also take a lot of the info from the Doc. Project
> Primer and it will be directly applicable.
>
> About the only thing I would suggest if you go this route is to take the
> time to switch from the DSSSL stylesheets to the XSLT stylesheets --
> essentially, using 'xsltproc' instead of 'jade', and 'passivetex'
> instead of 'jadetex'. The DSSSL stylesheets aren't really developed any
> more, as the world and his dog have jumped on the XML bandwagon.
>
> A diagram of the two approaches is here:
>
>     http://people.freebsd.org/~nik/sgmlxml.gif

>
> There's rudimentary support for this in the FDP build infrastructure
> already, keyed off a STYLESHEET_TYPE variable (defaults to "dsssl",
> "xsl" is the alternative), however the XSL stylesheets haven't been
> customised nearly as much as the DSSSL stylesheets have.
>
> If you go the XML/XSL route I'd be really interested in seeing any
> changes you had to make fed back in to FreeBSD. I don't know if the
> FreeBSD doc repo is copied in Perforce yet, but if not, it might be a
> good idea to take a copy there and branch it for your use.
>
> I *think* changebars are possible with the XSL stylesheets. Certainly,
> the stylesheets for HTML output have a 'changebars.xsl' stylesheet that
> seems to use CSS to do the right thing. Looking through the code, I
> don't see an equivalent for print output though.


--
Tony Finch <dot@???> http://dotat.at/