why the perl documents is hard to understand?

X

Xiaoshen Li

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.
 
X

Xiaoshen Li

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.
 
E

Eric Schwartz

Xiaoshen Li said:
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
 
J

John Bokma

Xiaoshen Li said:
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.
 
E

Eric Schwartz

Xiaoshen Li said:
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
 
A

A. Sinan Unur

Xiaoshen Li said:
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
 
J

Jürgen Exner

Xiaoshen said:
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

John Bokma

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.
 
J

jack

A. Sinan Unur said:
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

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'
 
G

Gunnar Hjalmarsson

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"?
 
P

Paul Lalli

Tassilo said:
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
 
J

Jürgen Exner

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

jack

Jürgen Exner said:
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.
 
T

Tassilo v. Parseval

Also sprach Paul Lalli:
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
 
P

Paul Lalli

Tassilo said:
Also sprach Paul Lalli:


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
 
P

Paul Lalli

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
 
J

jack

Paul said:
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.
 
X

xhoster

Xiaoshen Li said:
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
 
A

axel

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
 
X

xhoster

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
 

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,744
Messages
2,569,483
Members
44,901
Latest member
Noble71S45

Latest Threads

Top