why the perl documents is hard to understand?

Discussion in 'Perl Misc' started by Xiaoshen Li, Nov 7, 2005.

  1. Xiaoshen Li

    axel Guest

    Why should I have to downgrade in order to accommodate people
    constrained by their own or their company's restrictions?

    I don't want to use a web interface to Usenet... I am perfectly
    happy with a dedicated text based newsreader which in conjunction
    with the screen utility means I can move between machines in my
    house (or even externally) keeping the same session active, without
    any adverts or other rubbish popping up (unless posted to the groups
    I read of course, and then a quick 'TAB' moves me on).
    No, I have no intention of getting used to an inferior system.
    And so I support every hint to people using Google that they
    should follow Usenet and not Google conventions.

    axel, Nov 8, 2005
    1. Advertisements

  2. Xiaoshen Li

    jack Guest

    Why should I have to downgrade in order to accommodate people
    I am not suggesting you downgrade, I am suggesting that you just stop
    getting pissed-off with the inevitable.
    And when the Google conventions become the defacto standard, will you
    still be complaining ?
    jack, Nov 8, 2005
    1. Advertisements

  3. Xiaoshen Li

    Xiaoshen Li Guest

    I cannot give out specific examples. But believe me, print out a couple
    of descriptions of functions in Perl and go to talk to some *good*
    college students major in literature, explain clearly to them what each
    function does in Perl, and ask them write down the descriptions with
    similar amount of words. I bet, the "documentation" from them is much

    I am criticizing the English language skill of the writer. Writing is
    not a simple thing. It is an art.

    In my life, many times I have seen that one word or one sentence
    explains one concept clearly, while some people use four or five
    sentences still cannot do it, instead they made the concept more
    confusing and "mysterious".
    Xiaoshen Li, Nov 8, 2005
  4. I'm not "extremely fond of" it, but I'm used to it by now. To me, the
    distinction between a reference manual and a tutorial, as pointed out by
    John, appears to be applicable.
    Gunnar Hjalmarsson, Nov 8, 2005
  5. Xiaoshen Li

    axel Guest

    Why inevitable? Do you not realise that people can simply start
    rejecting Google originated posts on either ther server or individual
    level and that many do so?
    Yes. And so will many other people. Usenet is a somewhat rather
    anarchic medium but with established conventions in many portions
    of it, clpm being one.

    I very much do object to any single body or bodies trying to take
    it over - one of its essential natures is that it cannot be dictated
    to by any commercial (or non-commercial come to that matter) body...
    if I want to set up a news server at home on a local machine I am
    free to do so (and have done so in the past). I do not need Google's
    permission or need to abide by their strange conventions in order
    to do so.

    The death of Usenet has been forecast many times... all it seems
    to mean is that we are no longer plaguged with AOL'ers and other
    wastes of time.

    axel, Nov 8, 2005
  6. Then all you are doing is whining, and your opinions deserve no
    attention. If the prevalence of bad docs is as high as you seem to
    think, then it should be easy to pick out one specific function whose
    docs you don't feel are up to snuff.
    Why literature majors? Why not drama, or sculpture? Perl docs are
    written for programmers, not English majors. What's important is that
    a programmer can read them and understand. What is more readable to a
    literature student is quite likely to be incomprehensible to a
    programmer, and given that the odds are pretty strong that the former
    will never write any Perl, and the latter will, I'd prefer to bias the
    documentation so that programmers can understand it best.
    Art is all about communication (in my view), and that implies knowing
    your audience. The online Perl docs are generally written for
    programmers. If you want docs written for a more general audience,
    that's fine, but you want to read any of the several books directed at
    that market, not the online Perl docs.
    That's nice. But if you don't tell us what you find objectionable, we
    can hardly improve anything. Give us a concrete example, or kindly
    stop whining. Either one would be fine, really.

    Eric Schwartz, Nov 8, 2005
  7. Xiaoshen Li

    Bart Lateur Guest

    If you want a nicer-to-read version of the same docs online, try


    Split up per function, try

    Like people said: it's a reference manual. Accuracy is more important
    than being easy to read, it's not a tutorial. You're better off starting
    with a tutorial, I recommend "Learning Perl" by Randal Schwartz (AKA the
    Llama -- the book, not the author). Two days with this book, and you'll
    feel more at ease with Perl.
    Bart Lateur, Nov 9, 2005
  8. Xiaoshen Li

    axel Guest

    Yes... every time I have asked for a definition of 'post-modernism'
    from such people, the reply has been totally uninformative.

    axel, Nov 9, 2005
  9. Xiaoshen Li

    Smitty Guest

    Yes... every time I have asked for a definition of 'post-modernism'

    from a University of Colorado English Lit. Professor

    Postmodernism, like modernism, .... rejecting boundaries between high
    and low forms of art, rejecting rigid genre distinctions, emphasizing
    pastiche, parody, bricolage, irony, and playfulness. Postmodern art
    (and thought) favors ...fragmentation and discontinuity ..., ambiguity,
    simultaneity, and an emphasis on the destructured, decentered,
    dehumanized subject.

    --- In other words post-moderninsm is lack of structured thought,
    q.e.d. is not a form at all. ---

    But then what did you expect from a English Lit.Prof.
    Smitty, Nov 9, 2005
  10. wrote in


    is telling.

    A post-modernist Perl might be fun: There would be no one correct way of
    using, say, split. split would do whatever the programmer thought it
    would. Just a higher order of DWIM, don't you see? :)

    A. Sinan Unur, Nov 9, 2005
  11. Xiaoshen Li

    Hugh Lawson Guest

    I'm a Perl novice, and I found "Learning Perl" helpful.

    The distinction between reference manual and tutorial is also
    useful. Bert did a good job pointing to it rather than sermonizing the
    baffled OP. Novices often don't know that man pages are not
    tutorials. The man pages are usually silent about their place in the
    Great Ladder of Knowledge. (I should acknowledge that perl man pages
    are more informative about this.)

    To novices struggling with a difficult text, the situation seems
    frustrating and insulting. The temptation is to blame the text and
    its author, rather than one's own limitations.

    This being-insulted-by-difficult-text is a normal and natural
    feeling. That is why we have popularizations, tutorials,
    introductions, teachers, and so on.

    OT: For those frustrated by brief explanations of post-modernism, five
    or six weeks of hard reading will probably give you some idea of
    it. But expect to be confused and frustrated much of the time. You can
    enjoy a happy, rich life without bothering with it at all.
    Hugh Lawson, Nov 9, 2005
  12. Xiaoshen Li

    John Bokma Guest

    They didn't even reply when I complained :-D
    John Bokma, Nov 10, 2005
  13. No, you can download the whole thing as a big .zip or .tar.gz file.
    (It's separate from the JDK because it's larger, and the JDK gets
    updated more often, but it downloads from the same webpage.)

    And it uses HTML because it's over 200MiB, which is obviously too big to
    handle with a perldoc-like mechanism.

    And, no, it's not larger /because/ it's HTML; ActivePerl puts the POD
    into HTML, and it comes to less than 16MiB. The Java documentation is
    much more detailed documentation of a much larger library.

    John W. Kennedy
    "The pathetic hope that the White House will turn a Caligula into a
    Marcus Aurelius is as naïve as the fear that ultimate power inevitably
    -- James D. Barber (1930-2004)
    John W. Kennedy, Nov 12, 2005
    1. Advertisements

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 (here). After that, you can post your question and our members will help you out.