Nice post. agentv++ :)

But, the point i was trying to make was not that reference documentation such as this should be terse and void of elementary explanations ... i was trying to show sulfericacid that one should always try to execute the code in question, munge it up, debug it ... etc. Get involved before you involve others ...

There is an underlying question that seems to stem from your post ... "is the documentation is question in need of an 'upgrade'?". I don't think so. Besides building the courage to grok 'man pages', there also exists a skill known as search-foo - the ability to find that one piece of documentation that exists, somewhere "out there", that you can understand.

jeffa

L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)