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

[Puneet Kishor]

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...


On Monday, September 22, 2003, at 09:48  AM, Sean Gillies wrote:

> On Monday, September 22, 2003, at 07:52  AM, Puneet Kishor wrote:
>
>> Actually Palle Due Larsen's tip worked. I have to first call 
>> $shpObj->setBounds... then $shpObj->{bounds} returns values happily.
>>
>> What I would like to know is how Palle knew this... where in the docs 
>> could I have read this?
>>
>> I've said this before, and I know that I am on extremely thin grounds 
>> saying this again because I myself have done very little to 
>> contribute to it, but Lowell, the Perl/MapScript documentation is 
>> really really in need of more work.
>>
>> Since you are the one who has done probably the most amount of work 
>> on this -- first, a resounding thanks to you. But a close second, 
>> how, oh how, can we improve the docs?
>>
>> I've added the above tip to the wiki... perhaps that is the best way 
>> to increase the quality and quantity of documentation. But the docs 
>> are getting fragmented -- besides the versioning (different commands 
>> for 3.5, 3.6, 4.0) there is the mapfile reference, the mapscript 
>> reference, and the wiki to look at besides the email archives. Any 
>> ideas on how to bring all this together into one consolidated, 
>> intuitive whole? A user's manual? Is that what a wiki is already > 
>> doing?
>>
>> Simply adding readymade scripts is not going to help because every 
>> app is ever so slightly different.
>>
>> But, once again -- thanks Lowell for all your effort in documenting.
>>
>
> Puneet, all,
>
> Is there no Perl module for generating documentation from a Perl 
> module source?
> Something like Python's pydoc?
>
> cheers,
> Sean
>
>
> --
> Sean Gillies
> sgillies at frii dot com
> http://www.frii.com/~sgillies
>