[MetaCRS] CS-Map documentation

[Howard Butler]

Norm,

I saw you committed a preliminary version of the CS-Map  
documentation.  In your commit message, you lamented 20 years of  
different people using different tools to maintain the document.   
MapServer doesn't have 20 years of lineage, but it does have numerous  
folks editing the documentation all the time, and it has iterated a  
number of solutions to multi-user documentation efforts.

I thought I would point out the documentation tool that in my opinion  
has been a highly successful documentation boon to the MapServer  
project -- Sphinx.  Sphinx allows us to drive our website's  
documentation using hierarchical sub-documents that are managed in  
subversion.  This is similar to the Doxygen approach, but the  
documents primarily exist *outside* the source code, and the editing  
of the documentation is done in a plain text-like markup called  
reStructured Text.  Doxygen or even Docbook's markup, while providing  
easy diffs and plain text access, makes it quite hard to casually edit  
things.  I think casual editing is also what most frequently happens  
when docs go into maintenance mode, and making it very easy to do  
helps keep the docs actively maintained.

Additionally, Sphinx supports output formats other than HTML,  
including PDF and Windows Compiled Help.  MapServer currently only  
provides HTML and PDF for its website.

MapServer docs subversion tree -- http://svn.osgeo.org/mapserver/trunk/docs/
MapServer rendered html docs - http://mapserver.org/docs
MapServer rendered pdf docs - http://mapserver.org/MapServer.pdf

http://sphinx.pocoo.org/

Howard