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

Discussion in 'Perl Misc' started by Al, Oct 16, 2005.

  1. Al

    Al Guest

    wrote:
    [ . . ]
    > 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.

    --
    Al's sig template goes here.
     
    Al, Oct 16, 2005
    #1
    1. Advertising

  2. Al

    Henry Law Guest

    Al wrote:
    > wrote:


    Can't you all see that he's a troll? A well-fed one now.

    --

    Henry Law <>< Manchester, England
     
    Henry Law, Oct 16, 2005
    #2
    1. Advertising

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

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Toby
    Replies:
    4
    Views:
    1,846
    Mike Treseler
    Sep 7, 2005
  2. BethInAK

    I suck. Very basic question.

    BethInAK, Jul 22, 2003, in forum: ASP .Net
    Replies:
    5
    Views:
    364
    Holier Than Thou
    Jul 23, 2003
  3. supercobra
    Replies:
    2
    Views:
    649
    Roedy Green
    Jan 10, 2006
  4. Mr. SweatyFinger
    Replies:
    2
    Views:
    2,237
    Smokey Grindel
    Dec 2, 2006
  5. Eric I.
    Replies:
    0
    Views:
    287
    Eric I.
    Oct 5, 2008
Loading...

Share This Page