[ggm]

I think this is a very insightful comment. If the documents showed:

1) a simple instance of use of the language feature

2) a few typical instances of use

and

3) did NOT use towers-of-hanoi, prime-sieve, mathematical smartness, pointless tricks unrelated to the core functionality, dubious features under dispute..

The best UNIX man pages for systems commands do exactly this. They show all the commandline options in the sort-of BNF, they list the meaning/intent of the options (hopefully alphabetically) and under EXAMPLES they show you the 3 cruicial commands you really came looking for, exactly as the worked when the manual page was written.

I know I used man -s 1 or -s 8 to exemplify how to do man -s 2 and man -s 3 pages, but the point is they obey some simple (BNF) norms, some simple (nroff -man) format and EXAMPLES exemplify real-world use. Not "I am smart, watch me put a fruitloop in my nose" but real world, applicable instances.