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

[Daniel Morissette]

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 Morissette               dmorissette at dmsolutions.ca
  DM Solutions Group              http://www.dmsolutions.ca/
------------------------------------------------------------