MapScript Documentation (Re: [Mapserver-users] Re: problem getting bounds of poly shape)

[pkishor_98]

Sean,

In response to your suggestions below, I am all for simplifying things. The "things" 
should either be intuitive or be well documented. Since documentation is always the 
last thing on everyone's mind (except the user), making the language intuitive and 
consistent will be fantastic.

I would contribute, but I probably can't develop squat if given a chance. So I applaud 
(and appeal) for developers' patience and humor as we users submit unnecessary 
knots that need to be untangled.

To the extent it will help, in the interim I will write stuff on the wiki so others may 
benefit.

Many thanks.

--- In mapserver-users at yahoogroups.com, Sean Gillies <sgillies at f...> wrote:
> On Monday, September 22, 2003, at 09:11  AM, Puneet Kishor wrote:
> 
> > Hi Sean,
> >
> > I am not sure if there is something like pydoc... generally if the 
> > docs are provided in pod format then the various pod converters are 
> > available.
> >
> > However, raw docs are not the only answer here. There are so many 
> > other intricacies -- for example... why is that creating a mapObj 
> > automatically allows access to its rect, while creating a shapeObj 
> > does not... why does one have to _call_ setBounds before asking for 
> > the bounds?
> >
> > Why does a queryByShape require a shape and a map object, but not a 
> > layer(s) object(s)?
> >
> > Can I set the boundaries of a map anytime before I draw() it or does 
> > it have to be done at a particular time?
> >
> > When I draw a shape I need a map, the shape, and an image object... is 
> > the a new image object, or the one I create automatically when I 
> > mapObj->draw?
> >
> > etc. etc.
> >
> > In addition, use strict pragma has its own way of throwing a curve. I 
> > never program without use strict.
> >
> > So... at least two kinds of docs are needed -- one, a reference doc 
> > that tells the exact syntax and its examples including all the 
> > pre-reqs for each command; and two, a user's guide which shows the 
> > different parts and how to put them together.
> >
> > In addition, a really verbose error messages switch would be 
> > invaluable for the ms error log.
> >
> > Once these three are there, users can put together all manner of 
> > applications together.
> >
> > I didn't know that I had to $shpOb->setBounds, so I kept on trying to 
> > set the map extent to $shpObj->{bounds}. Of course, it wouldn't work, 
> > and the ms error log kept on saying "msCalculateScale(): General error 
> > message. Invalid image extent." okay -- I had no clue why my image 
> > extent was wrong... would have been nice to actually see the wrong 
> > image extent. So eventually I put the wrong image extent in variables, 
> > but did not assign it to the map extent so I could actually see the 
> > vars. The app worked and showed me that my image extent was -1 -1 -1 
> > -1. That made me think perhaps my shp was a line and not a poly... I 
> > don't know... I was flailing. Eventually I emailed the list and Palle 
> > bailed me out.
> >
> > Lowell (and a few others) has done a tremendous job putting the docs 
> > and examples together, but the changing versions (and the need to 
> > provide all of them) and their changing syntax has made keeping up 
> > difficult. Hence...
> >
> >
> 
> Puneet,
> 
> How about we work to eliminate some of the unnecessary intricacies 
> instead of
> (or along with) writing formal documents on how to work around them?
> 
> Here's a proposal: 'bounds' should not be a read-only attribute of a 
> shape
> that is set explicitly or set by a side-effect of another method.  It 
> should
> be a method that returns the bounds of the shape.  Once we make this 
> change,
> the usage problems disappear.
> 
> My particular issue is the 'scale' attribute of the mapObj.  This also 
> should
> be a method and not a read-only class variable.  Once we do this, 
> another
> 'gotcha' (directly changing mapObj extent does not change the scale) is 
> banished.
> 
> Anyway, maybe we should continue this discussion on the developers list?
> 
> cheers,
> Sean
> 
> --
> Sean Gillies
> sgillies at frii dot com
> http://www.frii.com/~sgillies
> 
> _______________________________________________
> Mapserver-users mailing list
> Mapserver-users at l...
> http://lists.gis.umn.edu/mailman/listinfo/mapserver-users