[OSGeo-Discuss] Help authoring tools

[Cameron Shorter]

For docbook WYSIWYG editing, I highly recommend the free version of 
XmlEditor from http://www.xmlmind.com/xmleditor/
It makes docbook almost as easy to edit as a word document, with the 
advantage of having structured docbook as a result. However, much as I 
love docbook as a format, it has limited market share and hence authors 
are less likely to want to write documents using it. Consequently I 
would advise against using docbook.

On 02/06/10 05:28, Paul Ramsey wrote:
> 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
>>
>>      
> _______________________________________________
> Discuss mailing list
> Discuss at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/discuss
>    


-- 
Cameron Shorter
Geospatial Director
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

Think Globally, Fix Locally
Geospatial Solutions enhanced with Open Standards and Open Source
http://www.lisasoft.com