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


_______________________________________________
MetaCRS mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/metacrs

[Justin Deoliveira]

Just to add to Howards voice here I have found Sphinx to be a great tool
and GeoServer has also decided to move to it for project documentation.

http://gridlock.openplans.org/geoserver/1.7.x/doc/user/

-Justin

Howard Butler wrote:

> 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
>
>
> _______________________________________________
> MetaCRS mailing list
> [hidden email]
> http://lists.osgeo.org/mailman/listinfo/metacrs

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.
_______________________________________________
MetaCRS mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/metacrs

[Norm Olsen]

Thanks you Howard . . .

for the tip on Sphinx.  We've been looking for a tool like this; we'll definitely check it out.  Sounds like just what the doctor ordered.

Norm

-----Original Message-----
From: [hidden email] [mailto:[hidden email]] On Behalf Of Howard Butler
Sent: Monday, March 23, 2009 9:11 AM
To: [hidden email]
Subject: [MetaCRS] CS-Map documentation

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


_______________________________________________
MetaCRS mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/metacrs
_______________________________________________
MetaCRS mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/metacrs