Bill, Thanks for your detailed, thoughtful, insightful and helpful reply. I have scanned through it. It merits a detailed response (not for argumentation, but for contributing back something useful), and I will do so in due course, but for now, I merely wanted to express in public my gratitude for you having had three cups of coffee this morning. I shall be perennially grateful to them beans.
And, the short of it -- yes, I am documenting my experience (OL + MS + Pg), and will contribute that document back for the benefit of others. OL is a great piece of work (my compliments to the cooks), horribly hampered by its documentation. I am not an expert by any stretch of imagination, but reasonably deft with Perl, SQL and Javascript (primarily via jQuery nowadays), and I find myself completely lost most of the times with OL. I hope I can contribute back to correct that somehow. Puneet. On Sun, Sep 20, 2009 at 11:13 AM, Bill Thoen <bth...@gisnet.com> wrote: > P Kishor wrote: >> The only place where the above info is available to me is either the >> actual source file for WMSGetFeatureInfo, or [2a] or [2b]. >> >> Once again, I ask, is there some better way, not obvious to me, I >> could have approached this so as to have an easier time discovering >> what I could or could not do to construct a proper constructor? > You'd be a great choice to help put together some documentation written > by users! What's been written is pretty good, but there's lot that still > needs writing and organizing. > > But to answer your question(s), the differences between similar topics > are usually due to the fact that one set of documentation is written by > Natural Docs that scans the comments in the header and builds a sort of > Reference Guide, vs. what's written by humans trying to provide a bit of > a Users Guide, of which is there's not much yet. What's most complete is > automatically generated and is more of a Users Reference, and there's > some gaps in that too. The difference being is that the Users guide > should tell you how to do high-level tasks like how to make a map from A > to Z, while the Users reference should give you the nuts and bolts > details about the functions mentioned by the other. > > The closest thing to a Users Guide here is the List of Examples at > http://openlayers.org/dev/examples/ and some of the stuff under "Other > OpenLayers Documentation" at > http://trac.openlayers.org/wiki/Documentation, but the Examples need to > be cross-referenced by the function(s) they demonstrate and hyperlinked > to the appropriate page(s) of the natural docs. Also a relatively new > but good set of Users Guide documentation is the "Documentation" page at > http://docs.openlayers.org/, but that's not as complete yet as I'd like, > though probably that's one people should read first. All of these can be > found fairly easily by following the obvious links to "Documentation" > from the home page. > > One area of hermetic knowledge that's often not known to new users is > the conventions used in building OpenLayers. These are probably so > second-nature to the developers by now that they don't realize what a > handicap not knowing these conventions is. In fact, knowing some of > these conventions obviates the need for documenting what would be > otherwise a rather long list. > > One simple convention that's worth knowing is how the code modules are > named and organized in the source code library. If you know this one, > then it's very easy to find the source code files for any object; just > change the dots in the object name to forward slashes and that becomes > the path to the source code file. > > Most newbies find that one quickly enough, but a more subtle one is the > convention used to set displayClass names. All objects that have a > displayClass property are set to the value "ol" + class name + object > name, without the period delimiters and camelCased. For example > OpenLayers.Control.Panel would become olConotrolPanel. If it's an object > like a button that has different states you add ItemActive or > ItemInactive to the base, as in olControlDragPanItemActive, and if it's > an object associated with an action, like a cursor , you add Active to > the base, as in olControlDragPanActive. This convention may no big > deal to those who use it all the time, but once you realize it, the > frustrating problem of no documentation listing all these classes just > goes away! > > Another one is the convention for passing an arbitrary list of > user-modified properties to an object's constructor. Not understanding > this one the newcomer can't believe such an obvious gap in the > documentation exists and screams for documentation with a question like > "what are the !...@#$% choices that go in the 'options' hashtable > parameter?" Actually that's fairly hard to document for each class > object because you'd have to repeat some of the properties over and over > (because they're inherited), or just write "see list of properties in > ancestor class.", which is sort what we get told now anyway. But all you > have to do to generate the list of these properties is to open the > source code for the function you're calling and note the classes it > inherits from; which are listed right there in the header after the > words "Inherits from". Then open that module and see where it inherits > from, and continue back until you get the original prototype. Finally, > with that list of classes, go to the Natural Docs pages for each class > and make a list of all properties from the origin function to the one > you're calling and that's your list of potential properties for the > "options" object. Who'd want to document that? Also, 90% of the > possibilities aren't relevant in any given situation, but knowing this > convention and what you need, you could easily determine the parameters > you need for the options without documentation. > > Perhaps knowing the conventions of how classes are built in OpenLayers > would have helped you to home in on your problem, but I think in this > case the root of your problem was more of a JavaScript one than an > OpenLayers one, and then it was further obfuscated by the fact that you > could specify the map parameter in more than one place, but only one > combination would actually work. > > Finally, I'd like to suggest that if you're perceptive enough to analyze > the docs this closely that maybe you'd be interested in going just a bit > further. I think what's needed to encourage users to contribute > documentation for things they've discovered that need more explanation > than what the docs provide now is a framework to provide a place for > little pieces of documentation. Where people might not want to take the > time to do something detailed and formal, they, might be willing to do > short and quickly. This could go in the wiki, linked to the general > Documentation page and eventually be incorporated in the official > documentation. > > (sorry for writing a novel here this morning, but three cups of coffee > can cause loggorhea!) > > - Bill Thoen > > _______________________________________________ > Users mailing list > Users@openlayers.org > http://openlayers.org/mailman/listinfo/users > -- Puneet Kishor http://www.punkish.org Carbon Model http://carbonmodel.org Charter Member, Open Source Geospatial Foundation http://www.osgeo.org Science Commons Fellow, http://sciencecommons.org/about/whoweare/kishor Nelson Institute, UW-Madison http://www.nelson.wisc.edu ----------------------------------------------------------------------- Assertions are politics; backing up assertions with evidence is science ======================================================================= Sent from Madison, WI, United States _______________________________________________ Users mailing list Users@openlayers.org http://openlayers.org/mailman/listinfo/users