[Mapserver-dev] Proposal for mapscript documentation using Restructured text

[Sean Gillies]

On Feb 18, 2004, at 4:37 PM, Daniel Morissette wrote:

> Sean Gillies wrote:
>> Here is an even better example of what we can do with Restructured 
>> text:
>> http://users.frii.com/sgillies/examples/mapscript.html
>> RST is wiki-like (better than wiki!) and the source is still quite 
>> readable
>> for those who want a plain text file.  There is a link at the bottom 
>> of the
>> HTML page which will show the plain text RST file.
>> I have committed the source to the CVS head under mapscript/doc.  If 
>> folks
>> like what they see and feel that the Restructured text syntax isn't 
>> too
>> cumbersome, I would be willing to take care of converting the 
>> mapscript.txt
>> file to HTML for each release.
>> This approach to the documentation, IMO, satisfies the major beefs 
>> that
>> developers have.  It's easy to edit and maintain, has readable source,
>> and can generate docs with hyperlinks.  I'm certain that with a 
>> little effort
>> we can come up with a DocBook writer that will satisfy MDP.
>
> Looks like this would do the trick.  Let's see what others think.
>
> Do you have a pointer to the tool to convert to HTML?  Is it easy to 
> install? I think it would be good for developers to be able to test 
> that the file looks ok before they commit a new version to CVS.
>
> If we move ahead with this then we could start from the 
> mapscript/php3/README file to produce the first version of the docs 
> since we have all the classes and methods documented in it.  Unless 
> someone has a better source to start from?
>
> Daniel

Daniel,

Are you talking about merging the SWIG and PHP mapscript documentation? 
  It might
be premature since the modules aren't truly merged yet.  There are 
exclusive
functions in each and differently named functions and classes ... much 
yet to do.

I do think that new SWIG mapscript documentation will borrow heavily 
from
the PHP readme but should be documentation of the module as it 
currently stands.

Sean

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