Improving framework for SWIG mapscript development documentation

[tbonfort]

Reporter: sgillies@frii.com Date: 2004/02/19 - 18:50

Here is an 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.

cheers,
Sean

[tbonfort]

Author: woodbri@swoodbridge.com Date: 2004/02/19 - 19:29

One requirement to whatever you decide on is that the resulting documentation 
output MUST fit and be printable on standard letter size or A4 paper. 

The current documentation often does not print without chopping off the right 
side of the page and everyone know that all the important stuff is crowded on 
that side of the page and must be view in a browser by scrolling right/left 
over the pages context. 

Th only exception to this should be some (very few) pages that can not be 
broken down into letter size pages using a different presentation of data and 
those should probably be delivered as PDF documents so they can be easily 
scaled to fit on a single printer page.

[tbonfort]

Author: sgillies@frii.com Date: 2004/02/19 - 19:45

Stephen,

Please, bug 576 concerns the _development_ documentation only.

Any concerns about the paper size (and I completely agree with
you on the A4) apply only to the issue of the MDP's user
documentation and should be reserved for a completely different
Bugzilla issue.

[tbonfort]

Author: dmorissette Date: 2004/02/24 - 19:14

Sean, I see that you have used the terminology mutable/immutable instead of
read-only/read-write in the current version of the docs at:
http://users.frii.com/sgillies/examples/mapscript.html.

I agree that we should stick to SWIG (or neutral) terminology as much as
possible, but in this case it seems to me that read-only/read-write or something
similar would be more intuitive for people not familiar with SWIG.  I also find
that the spelling of mutable and immutable is so close that it's hard to
distinguish the two in a quick browse of the docs.  Perhaps we could only mark
the immutable property and document the fact that properties are mutable unless
explicitly marked as immutable?

What do you think?

[tbonfort]

Author: sgillies@frii.com Date: 2004/02/24 - 19:42

Steve,

Good idea.  All attributes are now read-write unless we explicitly 
write 'immutable'.

[tbonfort]

Author: sgillies@frii.com Date: 2004/05/29 - 01:06

mapscript.txt is established, documentation of new methods is being
written.  Closing this issue down.