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

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

Sean,

Well I've never documented API's using it, but reading the docs suggests
there are elements for functions, method, function parameters, and so on ...

You can see the list of elements available from the online book:

http://www.docbook.org/tdg/en/html/docbook.html

The trickier question is whether the transformation tools render things in
the way you expect/would like.  Just because you use the proper xml elements
doesn't mean the transformation will do something with them, or doesn't mean
that whatever it does with them you will like.  There are standard XSL/DSSSL
transformers out there that presumably do a decent enough job since they're
quite popular.  The big advantage of using these is that, unless you're
being REALLY anal about the appearance, you have an out of the box solution
with a standard "appearance" that many people will probably be used to.

Also, it's just common sense to stick to MDP standards ... I'm sure Kari
would have something to say about this :)

Somewhat related, I'm going to need to document some Python/Zope API's I've
developped (Much simpler than the MapScript one, like my WFS Adapter and
API), and I was thinking of using DocBook as well.  If I happen to do this
in time, I'll be sure to remember to post my findings here.  Heck maybe this
will motivate me to speed up the process :)

My .02$
J.F.

-----Original Message-----
From: Sean Gillies [mailto:sgillies at frii.com]
Sent: Wednesday, February 18, 2004 10:05 AM
To: Jean-Francois.Doyon at ccrs.nrcan.gc.ca
Cc: mapserver-dev at lists.gis.umn.edu; nhv at cape.com
Subject: Re: Structured Text (Re: [Mapserver-dev] SWIG MapScript docs)


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