why the perl documents is hard to understand?

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

  1. Xiaoshen Li

    Xiaoshen Li Guest

    Hi,

    I am learning Perl now. I have computer science background. One
    important tool for learning a language is to learn how to read its help
    manual. For example, JAVA has all the functions document pages online.
    So any time, if I don't understand a function or need a function for
    doing something, I can check out the document pages. But I found Perl's
    document pages are so hard to read.

    http://search.cpan.org/dist/perl/pod/perlfunc.pod

    I have tried to read the descriptions of some functions. I am so totally
    lost. The wording, the phrases are so hard to follow. I feel I am
    reading an acient scripture.

    Unix/Linux 's man pages are also badly written. But I feel Perl's is
    even worse.
     
    Xiaoshen Li, Nov 7, 2005
    #1
    1. Advertising

  2. Xiaoshen Li

    Xiaoshen Li Guest

    Thank you very much for the replies. Yes, a coin has two sides, I agree.
    Anyway, I was taught that there is a trick to learn unix/linux. That is
    to learn how to read man page. Because the man page is always there to
    help you, anytime, anywhere.

    This similar trick clearly cannot work in Perl, unless I am at a
    prefessional level already. (If a person is at that level, I think those
    document pages may not be very useful already, at least its usefulness
    has been dramatically decreased.) I wish the wording, discriptions of
    each function are writen for general people, not for professionals or
    the writer himself to read.

    (By the way, the comment "Unfortunately, Linux/Unix man pages are badly
    writen." is not from me, is from the book "Think Unix" by Jon Lasser and
    I assume & believe a lot of people feel same way.)

    Generally, I wish computer science people could improve their expression
    skills dramatically.

    Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    After finishing a poem, he always read to some old aged general people.
    If they don't understand, he always tore it away and restart to write.
    It is not easy to explain something.


    Xiaoshen Li wrote:
    > Hi,
    >
    > I am learning Perl now. I have computer science background. One
    > important tool for learning a language is to learn how to read its help
    > manual. For example, JAVA has all the functions document pages online.
    > So any time, if I don't understand a function or need a function for
    > doing something, I can check out the document pages. But I found Perl's
    > document pages are so hard to read.
    >
    > http://search.cpan.org/dist/perl/pod/perlfunc.pod
    >
    > I have tried to read the descriptions of some functions. I am so totally
    > lost. The wording, the phrases are so hard to follow. I feel I am
    > reading an acient scripture.
    >
    > Unix/Linux 's man pages are also badly written. But I feel Perl's is
    > even worse.
    >
     
    Xiaoshen Li, Nov 7, 2005
    #2
    1. Advertising

  3. Xiaoshen Li <> writes:
    > So any time, if I don't understand a function or need a function for
    > doing something, I can check out the document pages. But I found Perl's
    > document pages are so hard to read.
    >
    > http://search.cpan.org/dist/perl/pod/perlfunc.pod


    You can also get the documentation for a specific function by typing
    'perldoc -f <funcname>' at the command line; this makes it a good deal
    easier to read only the documentation for the function you're
    considering.

    > I have tried to read the descriptions of some functions. I am so totally
    > lost. The wording, the phrases are so hard to follow. I feel I am
    > reading an acient scripture.


    Please give us an example of a function whose documentation you feel
    is inadequate. We are always trying to improve the state of Perl
    documentation, but if all you tell us is, "It's bad", then we have no
    information that we can actually use to improve things. Instead, what
    we need is, "This documentation is bad, because the way it is written,
    I don't understand if I can do this or that. I think it would be
    easier to understand if you said it this way." Only please be more
    specific than that. :)

    > Unix/Linux 's man pages are also badly written. But I feel Perl's is
    > even worse.


    Many of us don't agree, but I think also that even people who feel the
    docs are fine for them would agree that for other people, they can be
    improved. So tell us how they can be made better, and we'll do what
    we can. Sometimes we may simply disagree, but if you read this
    newsgroup for very long, you'll notice that FAQs are posted frequently
    here, and for very many of them, we will have discussions about how to
    improve them which are frequently concluded with a patch.

    So please give us specific examples of what is not good, why you don't
    think it's good, and if possible, how you think we might improve
    what's there. Some discussion will result, and either you will say,
    "Oh, I didn't realize that, you're right, that is the best way to
    explain it," or perhaps we will say, "That is a confusing way to put
    it. How about this way?". Sometimes, we will have to agree to
    disagree. But if you don't give us specific examples, all we can say
    is, "We're sorry you don't like it," and leave it at that.

    -=Eric
     
    Eric Schwartz, Nov 7, 2005
    #3
  4. Xiaoshen Li

    John Bokma Guest

    Xiaoshen Li <> wrote:

    > Hi,
    >
    > I am learning Perl now. I have computer science background. One
    > important tool for learning a language is to learn how to read its help
    > manual. For example, JAVA has all the functions document pages online.
    > So any time, if I don't understand a function or need a function for
    > doing something, I can check out the document pages. But I found Perl's
    > document pages are so hard to read.
    >
    > http://search.cpan.org/dist/perl/pod/perlfunc.pod
    >
    > I have tried to read the descriptions of some functions. I am so totally
    > lost. The wording, the phrases are so hard to follow. I feel I am
    > reading an acient scripture.


    That's because you are reading a reference manual, not a learning book.

    > Unix/Linux 's man pages are also badly written.


    Yup, if you use them to learn, true. They are reference pages.

    Java class documentation is also very hard to read if you know nothing
    about the language. Of course, since it's a reference, not a tutorial.

    --
    John Small Perl scripts: http://johnbokma.com/perl/
    Perl programmer available: http://castleamber.com/
    I ploink googlegroups.com :)
     
    John Bokma, Nov 8, 2005
    #4
  5. Xiaoshen Li <> writes:
    > Thank you very much for the replies. Yes, a coin has two sides, I agree.
    > Anyway, I was taught that there is a trick to learn unix/linux. That is
    > to learn how to read man page. Because the man page is always there to
    > help you, anytime, anywhere.


    I think man pages are useful to remind you how to do something, but
    quite often, unless you already know, and want to remind yourself,
    more documentation is needed.

    > This similar trick clearly cannot work in Perl, unless I am at a
    > prefessional level already.


    I do not agree; most of how I have learned to program in Perl has been
    reading the online documentation.

    > (If a person is at that level, I think those
    > document pages may not be very useful already, at least its usefulness
    > has been dramatically decreased.) I wish the wording, discriptions of
    > each function are writen for general people, not for professionals or
    > the writer himself to read.


    Please tell us what, specifically, you have a problem with. All you
    are saying now is, "I find Perl documentation hard to read". But if
    you do not tell us WHY it is hard for you, and HOW it might be
    improved, we cannot change anything. Let us pretend that I believe
    that the wording and descriptions of each function is already written
    for general people. (That is not the case, but let us pretend it is.)

    Now, you must convince me that I am wrong, and you are right. Please
    give me one specific function whose documentation you believe is not
    written for general people. Tell me why you believe that function's
    documentation is not written for general people, and if you can, tell
    us how you would change it to be more easily understood. Do not tell
    us, "Oh, they're so confusing and difficult to understand", tell me
    WHAT is confusing, and WHY it is difficult to understand.

    > (By the way, the comment "Unfortunately, Linux/Unix man pages are badly
    > writen." is not from me, is from the book "Think Unix" by Jon Lasser and
    > I assume & believe a lot of people feel same way.)


    Nobody here really cares one way or the other.

    > Generally, I wish computer science people could improve their expression
    > skills dramatically.


    That's probably true. But it doesn't help us here. We are practical
    people-- if someone comes to us and says, "Perl documentation is
    hard", we cannot change anything. If that person continues to say the
    same thing, then we will eventually decide that person does not want
    to make things better, but only complains, and we will stop listening,
    and nothing will change.

    If, however, someone says, "This document is confusing, because I
    don't understand what this means. Please explain it." and then writes
    a better explanation, then we are happy to help, and the documents
    will improve for everyone.

    > Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    > After finishing a poem, he always read to some old aged general people.
    > If they don't understand, he always tore it away and restart to write.
    > It is not easy to explain something.


    No it is not. Will you help us explain things better, or will you
    only complain and not try to improve Perl documentation?

    -=Eric
     
    Eric Schwartz, Nov 8, 2005
    #5
  6. Xiaoshen Li <> wrote in news:dkoua9$adjj$:

    > Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    > After finishing a poem, he always read to some old aged general
    > people. If they don't understand, he always tore it away and restart
    > to write. It is not easy to explain something.


    I am confused as to why you think this analogy is appropriate here? Do
    you expect all Perl programmers the world over to delete all Perl
    documentation on our hard drives and start writing it from scratch?

    You haven't given examples of specific documents that you have
    difficulty with. You haven't pointed out how things can be made better.

    Eric patiently explained why you should do that. You have ignored his
    advice, and trashed your opportunity to actually make things better.

    Instead, we get this drivel about how Unix and Perl docs suck. Tell me,
    what good is that? What purpose does does your complaining serve?

    On second thought, please don't.

    *PLONK*

    Sinan
    --
    A. Sinan Unur <>
    (reverse each component and remove .invalid for email address)

    comp.lang.perl.misc guidelines on the WWW:
    http://mail.augustmail.com/~tadmc/clpmisc/clpmisc_guidelines.html
     
    A. Sinan Unur, Nov 8, 2005
    #6
  7. Xiaoshen Li wrote:
    > Hi,
    >
    > I am learning Perl now. I have computer science background. One
    > important tool for learning a language is to learn how to read its
    > help manual. For example, JAVA has all the functions document pages
    > online.


    How awkward! Do you really have to dial up your ISP, start your favourite
    browser, ... just to find out how a Java function works?

    > So any time, if I don't understand a function or need a
    > function for doing something, I can check out the document pages.


    Well, then that is one point where Perl is vastly superior.
    All the Perl documentation is installed as part of Perl on your local system
    and you can easily access it using "perldoc".
    No large browser to start, not dialup to your ISP, just simple, easy, and
    straightforward.

    > But
    > I found Perl's document pages are so hard to read.
    >
    > http://search.cpan.org/dist/perl/pod/perlfunc.pod


    Never went there once in some 10+ years of on-and-off Perl programming.

    > I have tried to read the descriptions of some functions. I am so
    > totally lost. The wording, the phrases are so hard to follow. I feel
    > I am reading an acient scripture.


    Do you have some concrete example?

    > Unix/Linux 's man pages are also badly written. But I feel Perl's is
    > even worse.


    Well, no. They are terse and to the point for experienced people to check
    out details about how a function (command, operator, ...) works. They are
    definitely not meant as tutorial.

    jue
     
    Jürgen Exner, Nov 8, 2005
    #7
  8. Xiaoshen Li

    John Bokma Guest

    Xiaoshen Li <> wrote:

    Thanks for not top posting.

    > Thank you very much for the replies. Yes, a coin has two sides, I
    > agree. Anyway, I was taught that there is a trick to learn unix/linux.
    > That is to learn how to read man page. Because the man page is always
    > there to help you, anytime, anywhere.


    Yes, it is a reference. Not a tutorial.

    > This similar trick clearly cannot work in Perl,


    Because you have next to zero skills in Perl. Yup, the trick doesn't
    work then since first it isn't a trick, and second it's not a tutorial.

    > unless I am at a prefessional level already.


    Yup, which is the same as with the man pages, funny eh?

    > (If a person is at that level, I think
    > those document pages may not be very useful already, at least its
    > usefulness has been dramatically decreased.)


    Again you're wrong. It's a *reference*, which should be checked if in
    doubt. Even professional programmers check the references, just to
    prevent silly things like "defensive" programming (meaning in this case:
    cluttering the code because one is not sure, and guesses what things
    do).

    > I wish the wording,
    > discriptions of each function are writen for general people, not for
    > professionals or the writer himself to read.


    How does this differ from man pages (the answer is: not).

    > Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    > After finishing a poem, he always read to some old aged general
    > people. If they don't understand, he always tore it away and restart
    > to write. It is not easy to explain something.


    True, and a man page is not the right place. Imagine that each and every
    man page would consist of pages and pages of introductionary material,
    so everybody could understand it (if such a thing is already possible, I
    doubt it). This would make each and every man page a big read.

    --
    John Small Perl scripts: http://johnbokma.com/perl/
    Perl programmer available: http://castleamber.com/
    I ploink googlegroups.com :)
     
    John Bokma, Nov 8, 2005
    #8
  9. Xiaoshen Li

    Guest

    A. Sinan Unur wrote:
    > Xiaoshen Li <> wrote in news:dkoua9$adjj$:
    >
    > > Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    > > After finishing a poem, he always read to some old aged general
    > > people. If they don't understand, he always tore it away and restart
    > > to write. It is not easy to explain something.

    >
    > I am confused as to why you think this analogy is appropriate here? Do
    > you expect all Perl programmers the world over to delete all Perl
    > documentation on our hard drives and start writing it from scratch?
    >
    > You haven't given examples of specific documents that you have
    > difficulty with. You haven't pointed out how things can be made better.
    >
    > Eric patiently explained why you should do that. You have ignored his
    > advice, and trashed your opportunity to actually make things better.
    >
    > Instead, we get this drivel about how Unix and Perl docs suck. Tell me,
    > what good is that? What purpose does does your complaining serve?
    >
    > On second thought, please don't.
    >
    > *PLONK*
    >
    > Sinan
    > --
    > A. Sinan Unur <>
    > (reverse each component and remove .invalid for email address)
    >
    > comp.lang.perl.misc guidelines on the WWW:
    > http://mail.augustmail.com/~tadmc/clpmisc/clpmisc_guidelines.html


    What is it about the 'Generals' in this newsgroup.

    Do you really find yourself getting that agitated about the fact that
    the vast majority of posters into this group are relatively new to
    either perl, newsgroups, or the comp.lang.perl.misc newsgroup that you
    feel compelled to berate them about not having read the
    comp.lang.perl.misc guidelines, or not complying to your idealised
    notion of how to communicate within a newsgroup ?

    Haven't you yet got used to the idea that many of the people posting
    into this newgroup are doing so from Google, and don't realise that
    Google doesn't automatically comply with your guidelines ?

    Haven't you yet realised that when so many people take the time to
    complain about certain aspects of perl, be it the use of seemingly
    every conceivable glyph on the keyboard, to the structure of the
    documentation, to the non-standard (perl-specific) regular expressions
    syntax, that this is an indication that not only may there be a
    problem, but that the poster is probably trying to impart some of their
    wisdom, which like it or not, may well be the result of much more
    programming experience than your own.

    I have only begun to use perl in anger after 18 years as a professional
    programmer. That's just about exactly the same length of time that
    perl itself has been in existance. I am sure that perl, and some of
    the comp.lang.perl.misc regulars, have something to teach me - yet I
    am also sure that those same regulars would benefit from some of my
    experience.

    I am sure that posters are grateful for any help they receive, even
    when they don't say so. I know I am grateful.

    I am certain, however, that many of the 'Generals', the regulars who
    are so instructive and generally helpful, could benefit from a little
    less militancy. I honestly don't see the same degree of hostility in
    other newsgroups in which * I * am a 'regular'
     
    , Nov 8, 2005
    #9
  10. wrote:
    > Do you really find yourself getting that agitated about the fact that
    > the vast majority of posters into this group are relatively new to
    > either perl, newsgroups, or the comp.lang.perl.misc newsgroup that you
    > feel compelled to berate them about not having read the
    > comp.lang.perl.misc guidelines, or not complying to your idealised
    > notion of how to communicate within a newsgroup ?


    You don't need to know Perl or Usenet, you just need a minimum of common
    sense to realize that only saying "the docs are bad", without explaining
    in which way that would be the case, is totally pointless.

    > Haven't you yet got used to the idea that many of the people posting
    > into this newgroup are doing so from Google, and don't realise that
    > Google doesn't automatically comply with your guidelines ?


    Why would using a particular interface to Usenet justify breaking of the
    netiquette? The netiquette is for people to comply with, not for tools.

    > Haven't you yet realised that when so many people take the time to
    > complain about certain aspects of perl, be it the use of seemingly
    > every conceivable glyph on the keyboard, to the structure of the
    > documentation, to the non-standard (perl-specific) regular expressions
    > syntax, that this is an indication that not only may there be a
    > problem, but that the poster is probably trying to impart some of their
    > wisdom, which like it or not, may well be the result of much more
    > programming experience than your own.


    What kind of wisdom do you read in statements similar to "the docs are bad"?

    --
    Gunnar Hjalmarsson
    Email: http://www.gunnar.cc/cgi-bin/contact.pl
     
    Gunnar Hjalmarsson, Nov 8, 2005
    #10
  11. Xiaoshen Li

    Paul Lalli Guest

    Tassilo v. Parseval wrote:
    > Even though I am extremely fond of the perldocs, it
    > certainly does lack beginner's material and it's not explicit at all
    > about the order in which the many manpages ought to be read, if any.


    I would hope that most beginners find it logical to start with `perldoc
    perl` which contains:
    ====================================
    For ease of access, the Perl manual has been split up into
    several sections:

    perl Perl overview (this section)
    perlfaq Perl frequently asked questions
    perltoc Perl documentation table of contents
    perlbook Perl book information

    perlsyn Perl syntax
    perldata Perl data structures

    <SNIP>

    (If you're intending to read these straight through for the
    first time, the suggested order will tend to reduce the
    number of forward references.)
    ====================================

    Certainly seems like it's pretty explicit about the order in which they
    should be read..

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #11
  12. wrote:
    > Haven't you yet got used to the idea that many of the people posting
    > into this newgroup are doing so from Google, and don't realise that
    > Google doesn't automatically comply with your guidelines ?


    No, I haven't. And I will never conceed to the idea that Google can take
    over Usenet at their will and lure more and more people to use their web
    interface because a normal person with a normal news reader cannot
    comprehend postings posted via Google Groups any longer.

    There is no reason to abandon 20 years of tried and proven customs unless
    you replace it with something better. Google Groups is not better in any
    aspect.

    jue
     
    Jürgen Exner, Nov 8, 2005
    #12
  13. Xiaoshen Li

    Guest

    Jürgen Exner wrote:
    > wrote:
    > > Haven't you yet got used to the idea that many of the people posting
    > > into this newgroup are doing so from Google, and don't realise that
    > > Google doesn't automatically comply with your guidelines ?

    >
    > No, I haven't. And I will never conceed to the idea that Google can take
    > over Usenet at their will and lure more and more people to use their web
    > interface because a normal person with a normal news reader cannot
    > comprehend postings posted via Google Groups any longer.
    >
    > There is no reason to abandon 20 years of tried and proven customs unless
    > you replace it with something better. Google Groups is not better in any
    > aspect.
    >
    > jue


    I disagree, Google Groups is superior - to my mind anyway - in the
    follwing ways. It's a Web Interface and so may be accessed through
    most corporate firewalls which typically block anything except port 80,
    and HTML based content they can recognise. It's easier to search than
    the way most of the newsgroup software I have used in the past works.

    As for a 'normal' person, well, my guess is that the current percentage
    of posting from google groups compares close enough to equitably with
    other news reader software to make it 'normal', so unfortunately you
    will probably just have to get used to it.
     
    , Nov 8, 2005
    #13
  14. Also sprach Paul Lalli:

    > Tassilo v. Parseval wrote:
    >> Even though I am extremely fond of the perldocs, it
    >> certainly does lack beginner's material and it's not explicit at all
    >> about the order in which the many manpages ought to be read, if any.

    >
    > I would hope that most beginners find it logical to start with `perldoc
    > perl` which contains:
    >====================================
    > For ease of access, the Perl manual has been split up into
    > several sections:
    >
    > perl Perl overview (this section)
    > perlfaq Perl frequently asked questions
    > perltoc Perl documentation table of contents
    > perlbook Perl book information
    >
    > perlsyn Perl syntax
    > perldata Perl data structures
    >
    ><SNIP>
    >
    > (If you're intending to read these straight through for the
    > first time, the suggested order will tend to reduce the
    > number of forward references.)
    >====================================
    >
    > Certainly seems like it's pretty explicit about the order in which they
    > should be read..


    If that is the proposed order then it's bunkus. Why should the perlfaqs
    be read as second document? It's only useful for those who already know
    a little Perl. And why is perlintro not among the first three manpages
    mentioned?

    The truth is that the various perldocs have not been written with
    any order in mind. They were written in different times by different
    people. No matter in what order you'll read them, there'll be passages
    that refer to material not yet presented. The above suggested order
    speaks about reducing 'forward references'. Howard, it doesn't eliminate
    them.

    Tassilo
    --
    use bigint;
    $n=71423350343770280161397026330337371139054411854220053437565440;
    $m=-8,;;$_=$n&(0xff)<<$m,,$_>>=$m,,print+chr,,while(($m+=8)<=200);
     
    Tassilo v. Parseval, Nov 8, 2005
    #14
  15. Xiaoshen Li

    Paul Lalli Guest

    Tassilo v. Parseval wrote:
    > Also sprach Paul Lalli:
    >
    > >====================================
    > > For ease of access, the Perl manual has been split up into
    > > several sections:
    > >
    > > perl Perl overview (this section)
    > > perlfaq Perl frequently asked questions
    > > perltoc Perl documentation table of contents
    > > perlbook Perl book information
    > >
    > > perlsyn Perl syntax
    > > perldata Perl data structures
    > >
    > ><SNIP>
    > >
    > > (If you're intending to read these straight through for the
    > > first time, the suggested order will tend to reduce the
    > > number of forward references.)
    > >====================================
    > >
    > > Certainly seems like it's pretty explicit about the order in which they
    > > should be read..

    >
    > If that is the proposed order then it's bunkus. Why should the perlfaqs
    > be read as second document? It's only useful for those who already know
    > a little Perl. And why is perlintro not among the first three manpages
    > mentioned?


    Ah, well that's a different criticism entirely. :) And one that,
    fwiw, I agree with. I was just pointing out that the docs *do* suggest
    an order. Just not a particularly good one, it seems.

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #15
  16. Xiaoshen Li

    Paul Lalli Guest

    wrote:

    > As for a 'normal' person, well, my guess is that the current percentage
    > of posting from google groups compares close enough to equitably with
    > other news reader software to make it 'normal', so unfortunately you
    > will probably just have to get used to it.


    There's one key factor you're missing in that statistic: The *vast*
    majority of the "regulars" - the ones who actually *answer* questions,
    as opposed to only ask them - prefer the traditional style of replies
    and do not use Google Groups. If you want a decent chance of getting
    your questions answered, *you* will have to get used to that.

    BTW, this was posted from Google Groups, living proof that it *can* be
    used to post in accordance with the guidelines, and anyone who chooses
    not to is lazy and/or ignorant.

    Paul Lalli
     
    Paul Lalli, Nov 8, 2005
    #16
  17. Xiaoshen Li

    Guest

    Paul Lalli wrote:
    > wrote:
    >
    > > As for a 'normal' person, well, my guess is that the current percentage
    > > of posting from google groups compares close enough to equitably with
    > > other news reader software to make it 'normal', so unfortunately you
    > > will probably just have to get used to it.

    >
    > There's one key factor you're missing in that statistic: The *vast*
    > majority of the "regulars" - the ones who actually *answer* questions,
    > as opposed to only ask them - prefer the traditional style of replies
    > and do not use Google Groups. If you want a decent chance of getting
    > your questions answered, *you* will have to get used to that.
    >
    > BTW, this was posted from Google Groups, living proof that it *can* be
    > used to post in accordance with the guidelines, and anyone who chooses
    > not to is lazy and/or ignorant.


    Again, the inclination to cast aspersions simply cannot be repressed !

    Have a heart, man. A state of ignorance is not *normally* a choice.
    http://en.wiktionary.org/wiki/ignorance

    My guess is than less than half the posters to this newsgroup via
    google realise that their posts are somehow deficient and causing any
    issue amongst the readers. Perhaps your typical diatribes should be
    redirected to the fine folks at Google who provide the interface to
    this group.

    >
    > Paul Lalli
     
    , Nov 8, 2005
    #17
  18. Xiaoshen Li

    Guest

    Xiaoshen Li <> wrote:
    > Thank you very much for the replies. Yes, a coin has two sides, I agree.
    > Anyway, I was taught that there is a trick to learn unix/linux. That is
    > to learn how to read man page. Because the man page is always there to
    > help you, anytime, anywhere.


    Alas, this increasingly seems not to be the case. Now the man page often
    says little more than to see the "info" page, which are often missing or
    useless.

    >
    > This similar trick clearly cannot work in Perl, unless I am at a
    > prefessional level already. (If a person is at that level, I think those
    > document pages may not be very useful already, at least its usefulness
    > has been dramatically decreased.) I wish the wording, discriptions of
    > each function are writen for general people, not for professionals or
    > the writer himself to read.


    I was once a beginner in Perl. I've read the perldoc pages, and understood
    much of it. It is where most of my knowledge comes from. If that doesn't
    work for you, perhaps you should read a book intended to teach beginners,
    rather than reading the documentation.

    >
    > (By the way, the comment "Unfortunately, Linux/Unix man pages are badly
    > writen." is not from me, is from the book "Think Unix" by Jon Lasser and
    > I assume & believe a lot of people feel same way.)
    >
    > Generally, I wish computer science people could improve their expression
    > skills dramatically.


    I agree. I think computer science people should start doing so by
    providing concrete examples and suggested improvements, rather than just
    vague whining, when they criticise other people's expression skills.

    > Now I recall one of the greatest poet in China Tang Dynasty, BaiJuYi.
    > After finishing a poem, he always read to some old aged general people.
    > If they don't understand, he always tore it away and restart to write.
    > It is not easy to explain something.


    Xho

    --
    -------------------- http://NewsReader.Com/ --------------------
    Usenet Newsgroup Service $9.95/Month 30GB
     
    , Nov 8, 2005
    #18
  19. Xiaoshen Li

    Guest

    wrote:

    > What is it about the 'Generals' in this newsgroup.


    > Do you really find yourself getting that agitated about the fact that
    > the vast majority of posters into this group are relatively new to
    > either perl, newsgroups, or the comp.lang.perl.misc newsgroup that you
    > feel compelled to berate them about not having read the
    > comp.lang.perl.misc guidelines, or not complying to your idealised
    > notion of how to communicate within a newsgroup ?


    The guidelines are designed for people to be able to help those
    seeking advice. Hence vague descriptions of problems or errors
    raised are usually useless. Rather than repeating this ad infinitum,
    is it not easier to point people to the posting guidelines?

    > Haven't you yet got used to the idea that many of the people posting
    > into this newgroup are doing so from Google, and don't realise that
    > Google doesn't automatically comply with your guidelines ?


    Er, yes... but by informing people who use Google that it is possible
    to comply with the guidelines, it helps everyone. Otherwise we
    descend into using Google default standards which do not translate
    properly into Usenet standards.

    > Haven't you yet realised that when so many people take the time to
    > complain about certain aspects of perl, be it the use of seemingly
    > every conceivable glyph on the keyboard, to the structure of the
    > documentation, to the non-standard (perl-specific) regular expressions
    > syntax, that this is an indication that not only may there be a
    > problem, but that the poster is probably trying to impart some of their
    > wisdom, which like it or not, may well be the result of much more
    > programming experience than your own.


    If the complaints or comments are specific, then yes, they may make
    sense. Vague complaints do not.

    But then there is always the danger that the complainer might just
    be wanting Perl to be more like his previous language experience.

    For example you mention 'every conceivable glyph on the keyboard'
    - perhaps some people find this a problem. But it would be useful
    to know why these people find it a problem.

    > I have only begun to use perl in anger after 18 years as a professional
    > programmer. That's just about exactly the same length of time that
    > perl itself has been in existance. I am sure that perl, and some of
    > the comp.lang.perl.misc regulars, have something to teach me - yet I
    > am also sure that those same regulars would benefit from some of my
    > experience.


    You are welcome to contribute your experience.

    Axel
     
    , Nov 8, 2005
    #19
  20. Xiaoshen Li

    Guest

    wrote:
    >
    > Again, the inclination to cast aspersions simply cannot be repressed !
    >
    > Have a heart, man. A state of ignorance is not *normally* a choice.
    > http://en.wiktionary.org/wiki/ignorance
    >
    > My guess is than less than half the posters to this newsgroup via
    > google realise that their posts are somehow deficient and causing any
    > issue amongst the readers.


    Considering that this deficiency is pointed out over and over and over
    and over, then lack of comprehension cannot be due to involuntary
    ignorance. It is either willful ignorance or just plain stupidity.

    Xho

    --
    -------------------- http://NewsReader.Com/ --------------------
    Usenet Newsgroup Service $9.95/Month 30GB
     
    , Nov 8, 2005
    #20
    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. torhu
    Replies:
    5
    Views:
    368
  2. Replies:
    1
    Views:
    493
    Juan T. Llibre
    Oct 18, 2006
  3. Mr. SweatyFinger
    Replies:
    2
    Views:
    2,072
    Smokey Grindel
    Dec 2, 2006
  4. TheSaint

    Hard to understand 'eval'

    TheSaint, Jun 14, 2008, in forum: Python
    Replies:
    10
    Views:
    463
    Bruno Desthuilliers
    Jun 16, 2008
  5. pvbemmel-at-xs4all-nl

    program order: hard to understand definition

    pvbemmel-at-xs4all-nl, Nov 29, 2010, in forum: Java
    Replies:
    10
    Views:
    584
    Roedy Green
    Nov 30, 2010
Loading...

Share This Page