Why the Perl docs are so great was why the perl docs suck

A

Al

looking for info on push() we find this helpful entry in
the help files:

push ARRAY,LIST [ perldoc -f push ]
[ . . ]. It does not even use push.

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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,734
Messages
2,569,441
Members
44,832
Latest member
GlennSmall

Latest Threads

Top