A
Al
Darn. No example.
You did not list the other side of the coin. Nor did you share (except
for darn, no example) much about why your presented viewpoint should be
preferred.
Perhaps such doc is meant to be used "top down" (start at overview, the
easier stuff. then use other parts as reference).
Has advantage of not cluttering hard drive up with repeated material.
Clutter, ooh, yuck.
Along these lines, perhaps is to grep the pod (documentation) do so
wherever in folders using search terms in order to bring/return a
larger amount of cross referencing. And, what might be in a cross
reference. Perhaps an example.
http://perldoc.perl.org/search.html
I used it's the Google bar (indexed full text search of docs) typed in
two words: push example
http://perldoc.perl.org/perlreftut.html
yes, it's a reference tutorial. But, nonetheless:
<quote>
Line 6 installs the city name into the appropriate array.
$table{$country} now holds a reference to the array of cities seen in
that country so far. Line 6 is exactly like
push @array, $city;
except that the name array has been replaced by the reference
{$table{$country}} . The push adds a city name to the end of the
referred-to array.
</quote>
(found via search/find in web browser) (near the bottom of the page
thereof)
And yes, sometimes perhaps a bit too much (potential) docs can get
returned from word searches *of files* (text files, pod).
*Hey*, there's a pod indexing project currently happening at the CPAN.
Might you like to join it so that the Perl docs can then have even more
venues of access???
It's how open source works. YOU can make a difference.
BTW YOU did NOT make a difference (not here with me anyways) by
starting a thread about why docs suck. Such thread did not alter my
opinion of the docs at all, not even one bit.
I have not shared my opinion of the docs. I have only argued for what
I did not see much included of so far in along with this topic.