[Mapserver-dev] SWIG MapScript docs

[Norman Vine]

Daniel Morissette writes:
> >  
> > What about XML instead of a text file?  We could render it into HTML in 
> > a way
> > that emulated the Doxygen docs.  There must be a DTD we can use.
> > 
> 
> Sure... as long as the XML structure is simple enough to be picked up 
> quickly by the developers.  We could probably explore the DocBook route 
> since that's what is used for the rest of the MapServer docs.

Please do not do the Docs in an XML or HTML file

IMHO They should be either in the code itself and extracted out with  
an automated tool of some sort < doxygen perhaps ? > or a plain
text file that a human can read *easily* in their programming editor.

There are lots of tools that can reformat structured text of one kind or
another into various 'rendered' versions for those that like a sophisticated
viewer progrram, but many coders and they are who the documentation
is for are very often working in a text editor enviroment and whatever we 
do should take this into account.

here is one such format http://docutils.sourceforge.net/docs/rst/quickref.html

Cheers

Norman