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....@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@lists.osgeo.org > http://lists.osgeo.org/mailman/listinfo/discuss > _______________________________________________ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
