[OSGeo-Discuss] Help authoring tools

[Paul Ramsey]

PostGIS is docbook, a decision from Way Back.

Docbook has served us well, and in particular has provided some
unexpected benefits, in that the detailed markup have allowed
documentation-driven test frameworks to be built (we can actually
automatically test every documented function).

That said, if I were making the decision again today I'd use RST and
Sphinx, for the attractiveness of output and the human-readability of
the documentation source. It's easier to update the documentation at
source when you can easily visually scan it. I found I couldn't write
large chunks of docbook without using a WYSIWYG editor like (now
defunct) XMetaL.

P.

On Tue, Jun 1, 2010 at 2:15 PM, Howard Butler <hobu.inc at gmail.com> wrote:
>
> On Jun 1, 2010, at 12:34 PM, Stefan Steiniger wrote:
>>> On 06/01/2010 10:00 AM, Daniel Ames wrote:
>>>> Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan
>
>  Daniel,
>
> MapServer, GeoTools, OpenLayers, GeoServer, Shapely, libLAS, and GeoDjango all use Sphinx <http://sphinx.pocoo.org/>.  In my opinion, Sphinx's great advantages in order of importance are:
>
> - text-like markup (docbook is too much burden on documentation writers).  Restructured text is not too difficult to learn, but I wish the world would agree on a text-like markup (markdown, restructured text, wikitext, etc)
> - variety of output.   Besides html, you can do ePub, PDF (multiple ways -- via latex or stand alone), windows compiled help, qthelp, man
> - pretty output
> - simple installation and management
>
> I know there are some sphinx skeptics from the MapServer project on this list who might chime up one way or another about its level of success within the MapServer project, but I think its implementation has help our project immensely.
>
> GDAL is still using Doxygen for its documentation generation.
>
> Howard_______________________________________________
> Discuss mailing list
> Discuss at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/discuss
>