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

[Daniel Morissette]

I think we should do more use of bugzilla to track those kind of issues 
once it's been established that something needs a fix (the getBounds() 
thing in this case).  The mailing list gets lots of traffic and chances 
are that the conclusions of those discussions will be lost of forgotten 
unless someone has time to act on the issues right away which is unlikely.

By using bugzilla, we can later on track the reasons behind any change 
back to the initial problem reported by the user (Puneet would be the 
bug reporter in this case), and then we can read in each bug report the 
discussions that led to a decision to change the behavior or not.

The use of bugzilla also makes it easier for developers and other 
contributors (documentation, etc) to query the database and view a list 
of current issues to work on *when* they have time.

Another 0.02$

Daniel



Sean Gillies 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
>