Opened 20 years ago
Closed 20 years ago
#576 closed defect (fixed)
Improving framework for SWIG mapscript development documentation
Reported by: | Owned by: | ||
---|---|---|---|
Priority: | high | Milestone: | |
Component: | Documentation - MapServer | Version: | 4.1 |
Severity: | normal | Keywords: | |
Cc: |
Description
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
Change History (6)
comment:1 by , 20 years ago
Cc: | added |
---|
comment:3 by , 20 years ago
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.
comment:4 by , 20 years ago
Cc: | added |
---|
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?
comment:5 by , 20 years ago
Status: | new → assigned |
---|
Steve, Good idea. All attributes are now read-write unless we explicitly write 'immutable'.
comment:6 by , 20 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
mapscript.txt is established, documentation of new methods is being written. Closing this issue down.
Note:
See TracTickets
for help on using tickets.