Structured Text (Re: [Mapserver-dev] SWIG MapScript docs)

[Sean Gillies]

On Feb 17, 2004, at 12:43 PM, Norman Vine wrote:

> 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

Thanks for the reminder about Structured Text, Norman!  I think this 
would
do the job.  Structured Text is readable in its raw form and can also be
parsed and rendered into HTML or XML.

Here's my favorite flavor of Structured Text:
http://www.zope.org/Documentation/Articles/STX

Sean

--
Sean Gillies
sgillies at frii dot com
http://users.frii.com/sgillies