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

[Sean Gillies]

On Feb 18, 2004, at 7:56 AM, Jean-Francois.Doyon at ccrs.nrcan.gc.ca wrote:

>> 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
>
> Just a friendly reminder that the MapServer documentation project is 
> already
> standardized on DocBook :)
>
> This can be transformed to HTML, but probably also to plain text or 
> man page
> format as well anyways, satisfying everyone ?
>
> J.F.
>

J.F.,

I took the liberty of putting your post at the bottom since we were all
bottom posting.

Since you know DocBook ... would there be any need or benefit to 
defining
new elements for classes, functions, function arguments?  Or would this
just be free form?

Sean

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