why the perl documents is hard to understand?

A

axel

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,

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

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
 
J

jack

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

I am not suggesting you downgrade, I am suggesting that you just stop
getting pissed-off with the inevitable.
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.

And when the Google conventions become the defacto standard, will you
still be complaining ?
 
X

Xiaoshen Li

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

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".
 
G

Gunnar Hjalmarsson

Tassilo said:
Also sprach Gunnar Hjalmarsson:

I wouldn't be surprised if the purpose of the OP was to ask if we
(the group) knew of any documentation for Perl that is more suitable
to a Perl beginner. 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'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.
 
A

axel

I am not suggesting you downgrade, I am suggesting that you just stop
getting pissed-off with the inevitable.

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?
And when the Google conventions become the defacto standard, will you
still be complaining ?

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
 
E

Eric Schwartz

Xiaoshen Li said:
I cannot give out specific examples.

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

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.
I am criticizing the English language skill of the writer. Writing is
not a simple thing. It is an art.

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

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
 
B

Bart Lateur

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

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

<http://perldoc.perl.org/perlfunc.html>

Split up per function, try

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

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

axel

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

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

Axel
 
S

Smitty

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

Axel

Agreed

from a University of Colorado English Lit. Professor
http://www.colorado.edu/English/ENGL2012Klages/pomo.html

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

A. Sinan Unur

(e-mail address removed) wrote in
Yes... every time I have asked for a definition of 'post-modernism'
from such people, the reply has been totally uninformative.

ROTFL

http://www.google.com/search?q=define:+postmodernism

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? :)

Sinan
 
H

Hugh Lawson

Bart Lateur said:
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.

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

John Bokma

Keith Thompson said:
Google needs to fix their interface. At the very least, they need to
make the default "Reply" button work properly when used with Usenet
newsgroups (what they do with their own non-Usenet groups is up to
them). I've started encouraging users to complain to Google; perhaps
some day they'll listen.

They didn't even reply when I complained :-D
 
J

John W. Kennedy

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

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
corrupts."
-- James D. Barber (1930-2004)
 

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

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top