Am 13.11.2009 um 12:56 schrieb Nigel Metheringham:
On 12 Nov 2009, at 22:31, Mike Cardwell wrote:It's much simpler to just use the Apache mod_xslt module:This will require all sites that mirror the documentation to have the same config. They may not be running apache.I would be very wary about making changes that require more intelligence from the web server than shovelling data straight off disk.Nigel.
I followed the discussion and thought I'd write up my suggestion.Use the sphinx document generator (http://sphinx.pocoo.org/). It is well suitable for technical documentation, much simpler than docbook et al., but not oversimplified (as in wikis). It can generate HTML, PDF, plain text and other formats, all of which can be delivered by web servers (and mirrors) statically. Or shipped for offline reading.
I implemented this for a project of mine (http://mirrorbrain.org/ docs/), and I couldn't be happier with it. The main objective for me was to invite people to contribution and don't place obstacles in their way (like learning complicated techniques). http://mirrorbrain.org/docs/intro/#how-to-improve-this-documentation describes how one would go and edit the documentation. The source code of the very same page is straightforward: http://svn.mirrorbrain.org/svn/mirrorbrain/trunk/docs/intro.rst The format is called reStructuredText and it is (IMO) a good compromise of power and ease of use.
For me, one of the most interesting things was to create a post-commit hook that automatically regenerates the documentation whenever I change it in the source code repository. (I love short release cycles.) That could easily be implemented. Otherwise, don't look too much at my project page because it more or less is a one man show... A better site to look at is the Django Project (http://www.djangoproject.com/ ) who use Sphinx for all documentation. And they have extensive docs -- among the best I ever encountered in an Open Source project.
Their docs are "versioned". The top of the page often contains a hint that links to other versions:
http://docs.djangoproject.com/en/dev/"This document is for Django's SVN release, which can be significantly different from previous releases. Get old docs here: Django 1.0"
http://docs.djangoproject.com/en/1.0/topics/db/"This document describes Django version 1.0. For development documentation, go here."
That's highly useful IMO, and it solves the initial problem presented in this thread - that users end up in the wrong documentation for their exim version, without noticing it and without link to the other versions.
The different documentation branches shown on the web site correspond to the different branches in the source code repository, for instance:
trunk: http://docs.djangoproject.com/en/dev/topics/db/queries/ http://code.djangoproject.com/browser/django/trunk/docs/topics/db/queries.txt 1.0 release: http://docs.djangoproject.com/en/1.0/topics/db/queries/ http://code.djangoproject.com/browser/django/tags/releases/1.0/docs/topics/db/queries.txtThat's all possible with the Sphinx framework. It should be quite possible to copy the smart things from the Django project. For me, this fulfills all needs that a documentation framework should offer:
* it's easy to work with as a developer* it has a low barrier for contributors (developers and non-developers alike)
* it's easy to get going but still very customizable* it can be served statically and doesn't need special software and scales well
Peter
smime.p7s
Description: S/MIME cryptographic signature
-- ## List details at http://lists.exim.org/mailman/listinfo/exim-users ## Exim details at http://www.exim.org/ ## Please use the Wiki with this list - http://wiki.exim.org/
