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

[Jean-Francois.Doyon at CCRS.NRCan.gc.ca]

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.

-----Original Message-----
From: mapserver-dev-admin at lists.gis.umn.edu
[mailto:mapserver-dev-admin at lists.gis.umn.edu]On Behalf Of Sean Gillies
Sent: Wednesday, February 18, 2004 9:42 AM
To: nhv at cape.com
Cc: mapserver-dev
Subject: Structured Text (Re: [Mapserver-dev] SWIG MapScript docs)


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

_______________________________________________
Mapserver-dev mailing list
Mapserver-dev at lists.gis.umn.edu
http://lists.gis.umn.edu/mailman/listinfo/mapserver-dev