Poor State of the Man Pages
Shlomi Fish
My friend has recently graduated from the Technion in Electrical
Engineering. He knows English very well, but is short of
practical experience in programming. To remedy this, he decided to install
Linux on his computer, and to learn UNIX and Perl programming thoroughly
in order to become a better hacker.
Now, he learned some Perl by reading my Perl for Perl Newbies notes[1].
However, I only teach there a limited subset of Perl which just aims to
get people started writing their own code. It is not suitable for
programming Perl idiomatically, much less for reading the code of
experienced programmers.
At one point, I suggested the reader that he can now go over the man pages
and should. However, my friend complained that the man pages were hard to
understand, and I can relate to it, as they are certainly not intended for
people with very little background in UNIX.
He's using the Perl that ships with RedHat Linux 9.0. I can instruct him
to install Perl 5.8.2 or bleadperl, if the man pages there are
substantially better.
I recommended him to buy the Camel Book, which is a good read even for
people who are very good programmers. Still, it was a bit pricy for him
(220 NIS or $40). At the moment he is using a pirated version he found on
the Net somewhere. (of the second edition).
For a long time, I complained that the Perl man pages were probably
intended for either experienced Perl 4 programmers or for seasoned UNIX
shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise
and Perl is now being learned by people with very little experience of
either.
Those people could perhaps get started by reading Simon Cozens' "Beginning
Perl" book or whatever, but still need a good reference. This is either
"Programming Perl" or the man pages.
A good idea to revitalize them and adapt them to our needs, would be to
start a Phalanx like project for documentation. Namely, we:
1. Collect user stories on what they did not understand in the
documentation.
2. Assign volunteers to remedy these issues.
3. Assign volunteers to go over sections of the man pages and try to
paraphrase them to make them clear enough.
4. Collectively decide where the man pages could use some re-organization,
and re-organize them.
Once we're through, we release Perl 5.8.3 with all of the changes applied.
(or maybe delay it to Perl 5.10.x due to configuration management issues)
Are you with me? I volunteer to take the initial effort and get this
effort going. One thing that has to be understood is that the man pages
should be clear, explanatory, and organized. We cannot leave
"transliterate" as such because it's a piece of UNIX jargon and not plain
English. (for example).
Regards,
Shlomi Fish
[1] - http://vipe.technion.ac.il/~shlomif/lecture/Perl/Newbies/
----------------------------------------------------------------------
Shlomi Fish shl...@vipe.technion.ac.il
Home Page: http://t2.technion.ac.il/~shlomif/
An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.
Falk Fish
Alan Burlison
> Are you with me? I volunteer to take the initial effort and get this
> effort going. One thing that has to be understood is that the man pages
> should be clear, explanatory, and organized. We cannot leave
> "transliterate" as such because it's a piece of UNIX jargon and not plain
> English. (for example).
Looks like English to me:
http://dictionary.reference.com/search?r=2&q=transliterate
I'm all in favour of improving documentation, but I would not like to see
the documents 'dumbed down'. The online manpages are meant primarily as a
reference for people who already know some perl, not as an introductory text
- as you have already said there are plenty of good introductory books that
already cover this ground.
--
Alan Burlison
--
Shlomi Fish
> Shlomi Fish wrote:
>
> > Are you with me? I volunteer to take the initial effort and get this
> > effort going. One thing that has to be understood is that the man pages
> > should be clear, explanatory, and organized. We cannot leave
> > "transliterate" as such because it's a piece of UNIX jargon and not plain
> > English. (for example).
>
> Looks like English to me:
> http://dictionary.reference.com/search?r=2&q=transliterate
>
It is, but what I meant was its meaning deviates from the meaning we mean
by the tr/// operator.
> I'm all in favour of improving documentation, but I would not like to see
> the documents 'dumbed down'.
Actually, at the moment, the documentation is quite cryptic and hard to
understand and people can have problem understanding it even if they
already know the basis of Perl.
So, in a way it should be made more clear and idiot-proof. I don't know
what you mean by "dumbed down" exactly.
> The online manpages are meant primarily as a
> reference for people who already know some perl, not as an introductory text
> - as you have already said there are plenty of good introductory books that
> already cover this ground.
>
Right, _some_ perl. But let's face it: there are many Perl programmers
nowadays who:
1. Are not experienced in any other programming language.
2. Are not native speakers of English.
3. Have little if any experience with UNIX.
4. Just want to find out how to get a job done.
Now other technologies such as PHP or Python have adapted their
documentation to accomodate with people who are any of the following four.
In Perl, the situation is far from being ideal.
Many times it's not enough to say what a feature does in one clause, but
it is also necessary to explain it for people who are less knowledgable
than us, all mighty Perl/UNIX/English/hacking gurus. My friend is one
example, and I believe many people are considerably worse than him.
Do we agree?
Regards,
Shlomi Fish
Chip Salzenberg
> Are you with me?
No.
> We cannot leave "transliterate" as such because it's a piece of UNIX
> jargon and not plain English. (for example).
http://dictionary.reference.com/search?q=transliterate
--
Chip Salzenberg - a.k.a. - <ch...@pobox.com>
"I wanted to play hopscotch with the impenetrable mystery of existence,
but he stepped in a wormhole and had to go in early." // MST3K
Rafael Garcia-Suarez
>
> At one point, I suggested the reader that he can now go over the man pages
> and should. However, my friend complained that the man pages were hard to
> understand, and I can relate to it, as they are certainly not intended for
> people with very little background in UNIX.
I'd like to point out that the perl manpages are intented to be exactly
that : manpages -- reference documentation, complete but yet concise.
To draw a comparison, I doubt anyone can learn the basics of using a
Unix shell by reading in a row and from cover to cover sh(1), ls(1),
rm(1) and the like.
> I recommended him to buy the Camel Book, which is a good read even for
> people who are very good programmers. Still, it was a bit pricy for him
> (220 NIS or $40). At the moment he is using a pirated version he found on
> the Net somewhere. (of the second edition).
"Learning Perl" would be a more obvious choice IMHO. (BTW may I point
out that O'Reilly has a lower-price program for user groups ? and that
books can be shared ?)
> For a long time, I complained that the Perl man pages were probably
> intended for either experienced Perl 4 programmers or for seasoned UNIX
> shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise
> and Perl is now being learned by people with very little experience of
> either.
Agreed.
> Those people could perhaps get started by reading Simon Cozens' "Beginning
> Perl" book or whatever, but still need a good reference. This is either
> "Programming Perl" or the man pages.
Ultimately, the man pages *are* the reference, and vice versa. I'd be
happy to apply any improvement to the man pages, But I still think
that, as a reference documentation, they need to suppose a minimal level
of knowledge about programming and systems. For example, I don't see the
point of explaining what perl's exec() does without supposing that the
programmer can refer to the exec(3) manpage and understand it. The FAQs
and the *tut* pods have a little different purpose (and it should be
noted that the FAQs are maintained separately.)
Shlomi Fish
> Shlomi Fish wrote:
> >
> > At one point, I suggested the reader that he can now go over the man pages
> > and should. However, my friend complained that the man pages were hard to
> > understand, and I can relate to it, as they are certainly not intended for
> > people with very little background in UNIX.
>
> I'd like to point out that the perl manpages are intented to be exactly
> that : manpages -- reference documentation, complete but yet concise.
> To draw a comparison, I doubt anyone can learn the basics of using a
> Unix shell by reading in a row and from cover to cover sh(1), ls(1),
> rm(1) and the like.
>
Understood.
> > I recommended him to buy the Camel Book, which is a good read even for
> > people who are very good programmers. Still, it was a bit pricy for him
> > (220 NIS or $40). At the moment he is using a pirated version he found on
> > the Net somewhere. (of the second edition).
>
> "Learning Perl" would be a more obvious choice IMHO. (BTW may I point
> out that O'Reilly has a lower-price program for user groups ? and that
> books can be shared ?)
>
Actually, let's assume for the moment that my friend can learn the
_basics_ of Perl from "Perl for Perl Newbies" or from "Beginning Perl"
which are both available online. In any case, he also needs a good
reference to consult with to cover the _whole_ of Perl.
"Programming Perl" is such a good reference. However, it is not available
online for him to make use of. I can lend him my copy, but so far he
wanted to have a copy all of his own. And he found the man pages very hard
to understand.
There's a difference between keeping things "expert" and not aiming for
the general populace. For example saying:
And you can do the C-shell like "fooish".
And that's it, is bad, because not everyone here knows C-shell or ever has
to work with it. As for the exec example. One can say:
exec() executes a different program instead of the current perl
program. That is, it will run instead of the script and execution
will never return to the script. (unless in case of error, in
which it is usually recommended to exit immediately).
That's it! Brief, to the point, and portable for all people. UNIX 101 for
everybody.
> > For a long time, I complained that the Perl man pages were probably
> > intended for either experienced Perl 4 programmers or for seasoned UNIX
> > shell/sed/awk/whatever hackers. But naturally, reality wanted otherwise
> > and Perl is now being learned by people with very little experience of
> > either.
>
> Agreed.
>
> > Those people could perhaps get started by reading Simon Cozens' "Beginning
> > Perl" book or whatever, but still need a good reference. This is either
> > "Programming Perl" or the man pages.
>
> Ultimately, the man pages *are* the reference, and vice versa. I'd be
> happy to apply any improvement to the man pages, But I still think
> that, as a reference documentation, they need to suppose a minimal level
> of knowledge about programming and systems. For example, I don't see the
> point of explaining what perl's exec() does without supposing that the
> programmer can refer to the exec(3) manpage and understand it. The FAQs
> and the *tut* pods have a little different purpose (and it should be
> noted that the FAQs are maintained separately.)
>
I suggest I start by asking people who are new to Perl what they don't
understand in the man pages, and so collect user stories. (I'll ask my
friend to go over the pods and comment as well). Once we have enough, we
can see where should we improve things.
As a general rule, one can expect a beginning Perl programmer to refer to
the perl*.pod documents looking for a nice information or a trick. I feel
that they can be made suitable for almost everybody, without sacrificing
their use for expert hackers.
Regards,
Shlomi Fish
Randal L. Schwartz
Shlomi> A good idea to revitalize them and adapt them to our needs, would be to
Shlomi> start a Phalanx like project for documentation.
I think the problem you'll find in finding recruits is that the
people who need to either write or sign off on such documentation
are already doing everything they can on a volunteer basis, and
that the current docs are perceived to hit that "80/20" mark already.
You know, the first 80% of the work takes 80% of the time to do,
and the last 20% takes the other 80% of the time to do. :)
Yes, the docs are written by Unix-centric programmers for others like
themselves, and yes, that's 80% of Perl's audience. When that wasn't
satisfactory for a large enough chunk of the audience, the marketplace
stepped in and provided (like my "Learning Perl" and our courses,
and free support areas like perlmonks and begi...@perl.org).
But you've haven't completely explained (at least to me) why there's
both a large enough market that should get additional info for free
that isn't being satisified by the existing mechanisms, and enough
motivation to divert resources away from other projects where either
the key developers or relatively smart intermediaries are already
highly in demand. (Good tech writers are hard to find.)
If there's a large enough market that a commercial solution can exist,
please talk to any of many highly motivated local techwriters. I'm
sure they would love to get published, and could take the market size
to the local publishers for a proposal.
Man pages are meant to be a bit rough around the edges anyway. We're
all familiar and comfortable with that. Thank goodness the source is
available for everything with an opaque manpage. :)
--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<mer...@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!
Dave Rolsky
> "Programming Perl" is such a good reference. However, it is not available
> online for him to make use of. I can lend him my copy, but so far he
> wanted to have a copy all of his own. And he found the man pages very hard
> to understand.
Tell your cheap-ass friend to plunk down the $40 and buy a damn copy of
the book. Yes, I know it's not dirt-cheap, but it's not prohibitively
expensive for anyone with the financial resources to already own a
computer!
Buying Perl books supports the authors (like Larry, Randall, and many
others on this list) who've contributed to Perl. Complaining that
learning something requires buying a couple books is ridiculous. There
are not many things in this world worth learning that can be easily
learned with absolutely no investment of money. But $40 is a pretty small
investment, I'd say.
-dave
/*=======================
House Absolute Consulting
www.houseabsolute.com
=======================*/
Tom Christiansen
> jargon and not plain English. (for example).
Transliteration is hardly the same as translation, and this distinction is
wholly unrelated to collective Unix culture. The first is but a simple
rewrite from one character set into another; the second goes substantially
beyond that, substituting instead a term from the target language whose
*meaning* corresponds to the one used in the first language.
By way of illustration:
Greek word θεοκτονία τετραγλωττος πρεσβύτεροi μαργαρῐτις
Latin transliteration theoktonia tetraglottos presbyteroi margarītis
Latin translation deicīdium quadrilinguis seniores nacrum (MedL)
English translation god-killing four-tongued elders pearl
(Just as the Romans would further Latinize transliterated Greek words into
forms that better fit into their language (eg, k to c, -os to -us, -oi
to -i), we do the same in English; sometimes we even have Anglicized
versions of both the Greek and the Latin, such as theoktony coexisting
with deicide, tetraglot with quadrilingual.)
According to The Dictionary, transliteration is a transitive verb defined as:
To replace (letters or characters of one language) by those of
another used to represent the same sounds; to write (a word, etc.)
in the characters of another alphabet. Hence transˈliterated ppl. a.
On the other hand, the relevant definition for translation (def II 2 a) defines
it as a transitive verb meaning:
To turn from one language into another; ‘to change into another language
retaining the sense’ (J.); to render; also, to express in other words,
to paraphrase. (The chief current sense.)
In summary, because to translate is to paraphrase, and because the tr///
operator does no such thing, transliterate is the correct term to describe
its operation of mere character-set (that is, alphabet) transcription.
Or did you want it to be "transcription"? :-)
--tom
Alan Burlison
> Actually, let's assume for the moment that my friend can learn the
> _basics_ of Perl from "Perl for Perl Newbies" or from "Beginning Perl"
> which are both available online. In any case, he also needs a good
> reference to consult with to cover the _whole_ of Perl.
>
> "Programming Perl" is such a good reference. However, it is not available
> online for him to make use of. I can lend him my copy, but so far he
> wanted to have a copy all of his own. And he found the man pages very hard
> to understand.
--
Alan Burlison
--
Yitzchak Scott-Thoennes
> Once we're through, we release Perl 5.8.3 with all of the changes applied.
> (or maybe delay it to Perl 5.10.x due to configuration management issues)
I think you should aim for 5.8.5 (June 2004) at the earliest. I also
assume Nicholas will want the changes to go into bleadperl, and then
be integrated back to maint.
> Are you with me? I volunteer to take the initial effort and get this
> effort going. One thing that has to be understood is that the man pages
> should be clear, explanatory, and organized. We cannot leave
> "transliterate" as such because it's a piece of UNIX jargon and not plain
> English. (for example).
Transliterate is a bad example. It's an English word meaning translating
by character into a different language or alphabet. The extension to
Computer Science should be obvious.
In general, avoiding technical terms, including perl-specific ones,
will make the documentation worse, not better. What is needed is a
short definition of each such term, either where a newbie is likely to
first encounter it or in a perlglossary.pod or both. (I've always
wondered why the Camel glossary never made it to the pods.)
Shlomi Fish
> On Thu, 27 Nov 2003, Shlomi Fish wrote:
>
> > "Programming Perl" is such a good reference. However, it is not available
> > online for him to make use of. I can lend him my copy, but so far he
> > wanted to have a copy all of his own. And he found the man pages very hard
> > to understand.
>
> Tell your cheap-ass friend to plunk down the $40 and buy a damn copy of
> the book. Yes, I know it's not dirt-cheap, but it's not prohibitively
> expensive for anyone with the financial resources to already own a
> computer!
My friend at the moment has a low-paying half-time job and is supported by
his parents. The situation is tough here and many people are out of job,
much less my friend who still has a lot to learn and has to get a decent
experience. Note that in Israel $40 is quite a lot as even high tech wages
go into 40 NIS (or $8 dollars) per hour. Maybe more. Still, income tax
takes most of it, unfortunately.
While my friend likes to learn Perl now, he cannot afford to buy a book
for anything he would like to learn. I survived for a long time without
reading too many paperback books, and I don't see why my friend should
follow suit. And besides, like I said: I can temporarily lend him my own
copy.
>
> Buying Perl books supports the authors (like Larry, Randall, and many
> others on this list) who've contributed to Perl. Complaining that
> learning something requires buying a couple books is ridiculous. There
> are not many things in this world worth learning that can be easily
> learned with absolutely no investment of money.
Actually, as far as computer technologies are concerned, the opposite is
true. If you can't learn a computer technology from online resources
alone, then there's something very fishy about it.
Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
Ruby and the list go on. They all have very adequate documentation online
for beginners, as well as reference material that is very accessible.
Generally, the developers of a technology must make sure it is adequately
documented in an accessible online format if they actually want people to
learn it. Paperback books are a deprecated, inferior form of
documentation. When I'm hacking at something I usually don't consult a
book I have for reference. It is simply too inconvenient. Likewise, I
learned many things from online resources alone.
If you tell someone that he needs paperware as a reference for a
technology or as a way to learn it, then it means that someone did not
give enough time to make sure it is adequately documented as is.
> But $40 is a pretty small
> investment, I'd say.
>
Are you willing to make a check for the name of my friend to cover the
expenses of buying the book? Or order it from him in Amazon?
Regards,
Shlomi Fish
>
> -dave
>
> /*=======================
> House Absolute Consulting
> www.houseabsolute.com
> =======================*/
>
----------------------------------------------------------------------
Shlomi Fish
Is it a gratis service? No. Is:
http://www.python.org/doc/2.3.2/
a gratis service? Yes!
Check:
http://www.fsf.org/philosophy/free-doc.html
And Perl is mentioned there speicifically.
Shlomi Fish
I never said we should avoid the term transliterate or other computer
terms or jargon. I meant that we should follow them with a short, clear
description explaining what they mean for people who are half-laymen.
"Programming Perl" does just that. (except it has much longer
descriptions) I think we should do so with the man pages too. (except they
should have descriptions that are brief but to the point). Unless of
course, we are going to maintain a different reference (for example, by
forking the man pages).
Regards,
Shlomi Fish
Shlomi Fish
Oh Jesus Christ!
How many Perl 5 Porters does it take to screw in a lightbulb? Will you
leave the verb "transliterate" alone? Here are the facts about it:
1. It is the proper technical term.
2. Its meaning in English is not identical to its technical meaning.
3. Plus, not everybody are familiar with the English word, to begin
with.
Now, I say that these items warrant a short explanation that explains what
it means. I don't want to avoid it. We should never avoid the proper
terms. But we should also explain them.
Yitzchak Scott-Thoennes
> I never said we should avoid the term transliterate or other computer
> terms or jargon. I meant that we should follow them with a short, clear
> description explaining what they mean for people who are half-laymen.
Sorry, I thought you were advocating removing the term. I think we are
in violent agreement.
Dave Rolsky
> Actually, as far as computer technologies are concerned, the opposite is
> true. If you can't learn a computer technology from online resources
> alone, then there's something very fishy about it.
> Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
> Ruby and the list go on. They all have very adequate documentation online
> for beginners, as well as reference material that is very accessible.
Hmm, I've found the qmail docs pretty horrid, far inferior to Perl's. But
that's comparing apples to oranges. Most of the things you list are apps
(qmail, make, postgres, etc.) and have a much narrower scope than Perl,
and as such are much easier to learn through online docs. Of course, if
you've never used SQL before at all, good luck learning to use MySQL or
Postgres from their online docs.
I haven't looked too much at the Ruby, Python or PHP online docs. My
impression from the PHP docs I've looked at online was that it was mostly
reference material with user-supplied annotations, and I wasn't hugely
impressed with it, but I've not delved into it in an attempt to learn the
language, so there's probably bits I've missed.
For Ruby, it looks like the Programming Ruby book is available online
under the Open Publication License, a great choice I strongly support (see
masonbook.com), but that's hardly the same as the core Ruby docs.
If that book weren't available online, would someone write the equivalent
for the Ruby docs? I doubt it. They'd tell people to go read the book.
> Generally, the developers of a technology must make sure it is adequately
> documented in an accessible online format if they actually want people to
> learn it. Paperback books are a deprecated, inferior form of
> documentation. When I'm hacking at something I usually don't consult a
> book I have for reference. It is simply too inconvenient. Likewise, I
> learned many things from online resources alone.
I generally like to read a book (or books) first, and then use online
resources as references. I have no problem with buying the "deprecated,
inferior" form of documentation.
> If you tell someone that he needs paperware as a reference for a
> technology or as a way to learn it, then it means that someone did not
> give enough time to make sure it is adequately documented as is.
>
> > But $40 is a pretty small investment, I'd say.
>
> Are you willing to make a check for the name of my friend to cover the
> expenses of buying the book? Or order it from him in Amazon?
No.
Abigail
>
> Oh Jesus Christ!
>
> How many Perl 5 Porters does it take to screw in a lightbulb? Will you
> leave the verb "transliterate" alone? Here are the facts about it:
>
> 1. It is the proper technical term.
>
> 2. Its meaning in English is not identical to its technical meaning.
>
> 3. Plus, not everybody are familiar with the English word, to begin
> with.
>
> Now, I say that these items warrant a short explanation that explains what
> it means. I don't want to avoid it. We should never avoid the proper
> terms. But we should also explain them.
But when do you stop? If the goal is to write documentation in English
for people who don't master English, when do you stop explaining?
Until you have no multi-syllable words left? Until the documentation is
70% dictionary and 30% technical? Until Dr. Suess approves it?
Don't dumb down the documentation. It'll lose value.
Abigail
Abigail
> On Thu, 27 Nov 2003, Dave Rolsky wrote:
>
> > Buying Perl books supports the authors (like Larry, Randall, and many
> > others on this list) who've contributed to Perl. Complaining that
> > learning something requires buying a couple books is ridiculous. There
> > are not many things in this world worth learning that can be easily
> > learned with absolutely no investment of money.
>
> Actually, as far as computer technologies are concerned, the opposite is
> true. If you can't learn a computer technology from online resources
> alone, then there's something very fishy about it.
> Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
> Ruby and the list go on. They all have very adequate documentation online
> for beginners, as well as reference material that is very accessible.
You must have a totally different view of valuable documentation than I
have. One reason I'm not as proficient with Python as I like to be is it's
utter lack of documentation:
$ man python | wc -l
Reformatting python(1), please wait...
270
$ man python | grep 'SEE ALSO'
Reformatting python(1), please wait...
$
MySQL doesn't even come with a manual page, just one large HTML file,
which lacks too much vital information IMO. GNU make uses a twisty
little maze of info files, where it's very hard to find what you want.
If I have to pick only one thing why I think Perl is superiour to other
languages, my pick will be "the documentation that comes with it".
> Generally, the developers of a technology must make sure it is adequately
> documented in an accessible online format if they actually want people to
> learn it. Paperback books are a deprecated, inferior form of
> documentation. When I'm hacking at something I usually don't consult a
> book I have for reference. It is simply too inconvenient. Likewise, I
> learned many things from online resources alone.
>
> If you tell someone that he needs paperware as a reference for a
> technology or as a way to learn it, then it means that someone did not
> give enough time to make sure it is adequately documented as is.
That's quite an insult to the people who have spend countless unpaid
hours to make the documentation what it is.
> > But $40 is a pretty small
> > investment, I'd say.
>
> Are you willing to make a check for the name of my friend to cover the
> expenses of buying the book? Or order it from him in Amazon?
$40 won't let you hire someone long enough to write 1 page of
documentation. People have invested enormous amounts of time,
inconvenience and money to make Perl and the documentation what it is,
and now you are whining that that hasn't been enough, because you have
a friend who doesn't want to invest $40 in his future.
That pisses me off.
Abigail
Russ Allbery
> You must have a totally different view of valuable documentation than I
> have. One reason I'm not as proficient with Python as I like to be is
> it's utter lack of documentation:
> $ man python | wc -l
> Reformatting python(1), please wait...
> 270
> $ man python | grep 'SEE ALSO'
> Reformatting python(1), please wait...
> $
Well, Python doesn't use manual pages, but I'm not sure one can really say
that means it has an utter lack of documentation. It ships with several
rather comprehensive manuals in HMTL.
I'd really prefer a manual page too, and I'm kind of annoyed at the way
that more and more major software packages these days are coming with tons
of different types of documentation, all of which are harder to access,
organize, and search than manual pages. But it's still documentation.
--
Russ Allbery (r...@stanford.edu) <http://www.eyrie.org/~eagle/>
Allan Fields
No, I'm with Alan, please don't dumb down the well written man pages.
;)
They are concise, make good logical sense and have a degree of
perfection just the way they are.
Not that you have a bad idea. If one must "revise", look only to the
seemingly infinite expanse of free bits.
> Regards,
>
> Shlomi Fish
Allan Fields
Vadim Konovalov
SF> technology or as a way to learn it, then it means that someone did not
SF> give enough time to make sure it is adequately documented as is.
Please tell your friend to go to www.perlmonks.org : there's a lot of
tutorials there, also he will be able to learn by examples, and
there's a lot of supportive people.
This discussion becomes offtopic, and I really think there should be a
very link to perlmonks site at the very enterance of p5p, because it's
quite often novices ask simple questions here, and they should go to
PM site.
--
Best regards,
Vadim
Andy Lester
> start a Phalanx like project for documentation.
I'm honored that you invoke Phalanx as an inspiration for this project.
However, there's one key part of Phalanx that you missed: I started it
myself. It wasn't a committee. It wasn't me coming to p5p and saying
"Hey, guys, let's start a project!" I never posted to p5p about it
until after I'd started it. I just did it.
> Namely, we:
> 1. Collect user stories on what they did not understand in the
> documentation.
> 2. Assign volunteers to remedy these issues.
> 3. Assign volunteers to go over sections of the man pages and try to
> paraphrase them to make them clear enough.
> 4. Collectively decide where the man pages could use some
> re-organization,
> and re-organize them.
I think this is a great plan, except for one word. Change "we" to "I".
Stop arguing about it and DO IT. If it's a worthwhile project, people
will come on board and make things happen. If it's not, then they
won't. It's the way open source works.
I also suggest that you'll get better results without coming out with
both barrels saying "The docs suck and need to be replaced."
And I ask that the rest of p5p not bother squabbling about this. Until
there's some actual content from Shlomi's project, there's nothin' to
really discuss.
xoa
--
Andy Lester
an...@petdance.com, AIM:petdance
http://petdance.com/ http://use.perl.org/~petdance/
Tassilo Von Parseval
> On Thu, 27 Nov 2003, Dave Rolsky wrote:
> > Buying Perl books supports the authors (like Larry, Randall, and many
> > others on this list) who've contributed to Perl. Complaining that
> > learning something requires buying a couple books is ridiculous. There
> > are not many things in this world worth learning that can be easily
> > learned with absolutely no investment of money.
>
> Actually, as far as computer technologies are concerned, the opposite is
> true. If you can't learn a computer technology from online resources
> alone, then there's something very fishy about it.
> Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
> Ruby and the list go on. They all have very adequate documentation online
> for beginners, as well as reference material that is very accessible.
Are you sure that what you say about Python and Ruby is true? My
experience is quite a different one. I was able to pick up Perl around
three years ago with relative ease. I had none of those suggested books.
I started with a flimsy Perl introduction that was part of a SELFHTML,
in total not more than four internet-pages. Fortunately though, I had a
friend who knew a little bit of Perl already. Not much really, but he
knew enough to point me to the perldocs. The only printed stuff I had
at this time was the Perl section of "Linux in a nutshell".
All it takes is some willingness to learn the stuff. With perldoc, some
googling and the help of begi...@perl.org and/or clpm everything is
there. However, if someone has written a nice tutorial or some other
piece of documentation that might be useful, it can always be included
in a Perl distribution. But when you are asking the porters to write
this stuff, you are probably asking the wrong people.
I'd like to add that I rather prefer to see additional documentation
over altering the existing material. The current perldocs work extremely
well and can't so easily be tweaked to satisfy both the beginners and
the experienced users.
Tassilo
--
$_=q#",}])!JAPH!qq(tsuJ[{@"tnirp}3..0}_$;//::niam/s~=)]3[))_$-3(rellac(=_$({
pam{rekcahbus})(rekcah{lrePbus})(lreP{rehtonabus})!JAPH!qq(rehtona{tsuJbus#;
$_=reverse,s+(?<=sub).+q#q!'"qq.\t$&."'!#+sexisexiixesixeseg;y~\n~~dddd;eval
Tassilo Von Parseval
> Check:
>
> http://www.fsf.org/philosophy/free-doc.html
>
> And Perl is mentioned there speicifically.
Haha, it makes for a good laughter that particularly the GNU folks would
complain about the Perl documentation. I am sure that I had never learnt
Perl if it had been documented the way GNU projects are.
The chaps from the Free Software Foundation live in a sort of parallel
universe, as it sometimes seems. In the mentioned article they complain
that O'Reilly doesn't let users copy and modify the source of their
books. Of course, they are neglecting the rather obvious fact that it'd
be pretty hard to earn any money when allowing that.
Shlomi Fish
> > A good idea to revitalize them and adapt them to our needs, would be to
> > start a Phalanx like project for documentation.
>
> I'm honored that you invoke Phalanx as an inspiration for this project.
> However, there's one key part of Phalanx that you missed: I started it
> myself. It wasn't a committee. It wasn't me coming to p5p and saying
> "Hey, guys, let's start a project!" I never posted to p5p about it
> until after I'd started it. I just did it.
>
Hey, relax!
I was just posting the idea here to get some feedback. (not one of
incredibly good S/N ratio evidently, but still)
> > Namely, we:
> > 1. Collect user stories on what they did not understand in the
> > documentation.
> > 2. Assign volunteers to remedy these issues.
> > 3. Assign volunteers to go over sections of the man pages and try to
> > paraphrase them to make them clear enough.
> > 4. Collectively decide where the man pages could use some
> > re-organization,
> > and re-organize them.
>
> I think this is a great plan, except for one word. Change "we" to "I".
>
> Stop arguing about it and DO IT. If it's a worthwhile project, people
> will come on board and make things happen. If it's not, then they
> won't. It's the way open source works.
>
> I also suggest that you'll get better results without coming out with
> both barrels saying "The docs suck and need to be replaced."
>
> And I ask that the rest of p5p not bother squabbling about this. Until
> there's some actual content from Shlomi's project, there's nothin' to
> really discuss.
>
Very well, I will.
Regards,
Shlomi Fish
> xoa
>
> --
> Andy Lester
> an...@petdance.com, AIM:petdance
> http://petdance.com/ http://use.perl.org/~petdance/
>
----------------------------------------------------------------------
Shlomi Fish
> On Thu, Nov 27, 2003 at 10:41:32PM +0200 Shlomi Fish wrote:
>
> > Check:
> >
> > http://www.fsf.org/philosophy/free-doc.html
> >
> > And Perl is mentioned there speicifically.
>
> Haha, it makes for a good laughter that particularly the GNU folks would
> complain about the Perl documentation. I am sure that I had never learnt
> Perl if it had been documented the way GNU projects are.
>
It depends on the GNU project. GNU awk has an excellent documentation and
I learned Awk from there (albeit after I knew Perl). GNU make also has a
good documentation, and I think I learned how to write makefiles from
there. Still, I found out that it was hard to find out what I was looking
for there, after I became experienced.
Some GNU packages are documented just enough to explain the basic flags
and operation modes, and nothing too much besides. For example, the docs
of gcc do not teach you C, or the docs of wget do not teach you WWW
basics. It vastly depends on how original the particular application is.
I found the GNU documentation as a whole to be a good, clear, reference,
which I'm not sure can be said on the Perl pod files.
> The chaps from the Free Software Foundation live in a sort of parallel
> universe, as it sometimes seems. In the mentioned article they complain
> that O'Reilly doesn't let users copy and modify the source of their
> books. Of course, they are neglecting the rather obvious fact that it'd
> be pretty hard to earn any money when allowing that.
>
You might as well complain that Microsoft or a different vendor of
proprietary software does not let users copy and modify the source of
their software. And neglect the rather obvious fact that it'd be pretty
hard to earn any money when allowing that. ;-)
Seriously, some books distributed online under an open content license,
actually sold pretty well in paperware. Not all, but then again, not every
book that wasn't placed online was successful, either.
I'm not someone who thinks that every book should be distributed online
(even though everyting I created and transcribed to a digital format is,
and I hope I will continue this trend). But I agree that releasing a piece
of software, without supplying a good and thorough introduction and
reference documentation, is very bad for the software. Simply put, users
will shy away from it, become frustrated using it and use something else
instead. Many computer users nowadays expect (and rightfully so) that an
open source software (that is free as in beer), will be also adequately
documented without having to pay for paperware. If someone likes books,
then he may be willing to pay or borrow such a book, but we must also
accomodate for people who like learning from Internet resources. (like me)
My point is that the perl*.pod pages should be suitable for a large part
of our demographic. Telling someone to buy "Programming Perl" is
equivalent to telling him to "learn Python instead because it has good
documentation online". (you might not like it, but it's life). It is my
intention to make perl*.pod suitable for people like my friend. And my
friend, mind you is an Electrical Engineering graduate from the Technion,
so he is well above average intelligence. Again, it may be a good idea to
fork the man pages, and turn them into something more organized that will
cater to a more average demographic. We'll see.
Of course, all of this would have been much easier if "Programming Perl"
was available online for free. There are already some replacements for
"Learning Perl" (like Simon Cozens' book) online. This all reminds me of
the "triple development" symptom of open-source:
1. Someone decides to write KDE based on Qt, where Qt is not free.
2. Someone decides to write GNOME based on the free Gtk, to pose an
alternative to KDE.
3. Someone decides to write a free Qt replacement (Harmony).
So, in order to provide a good reference to the core language of Perl, we
have to duplicate the efforts of other people.
Shlomi Fish
> On Thu, 27 Nov 2003, Shlomi Fish wrote:
>
> > Actually, as far as computer technologies are concerned, the opposite is
> > true. If you can't learn a computer technology from online resources
> > alone, then there's something very fishy about it.
> > Take a look at Python, PHP, MySQL, PostgreSQL, GNU make, GNU awk, qmail,
> > Ruby and the list go on. They all have very adequate documentation online
> > for beginners, as well as reference material that is very accessible.
>
> Hmm, I've found the qmail docs pretty horrid, far inferior to Perl's. But
> that's comparing apples to oranges. Most of the things you list are apps
> (qmail, make, postgres, etc.) and have a much narrower scope than Perl,
> and as such are much easier to learn through online docs. Of course, if
> you've never used SQL before at all, good luck learning to use MySQL or
> Postgres from their online docs.
>
I learned SQL from the MS Access online help. Can't tell about MySQL or
Post because I already knew SQL when I was introduced to them.
> I haven't looked too much at the Ruby, Python or PHP online docs. My
> impression from the PHP docs I've looked at online was that it was mostly
> reference material with user-supplied annotations, and I wasn't hugely
> impressed with it, but I've not delved into it in an attempt to learn the
> language, so there's probably bits I've missed.
>
Yes, but PHP has some very good tutorials online (one I believe to be part
of the core documentation), which you can easily learn from them. And I
was talking about _reference material_, not introducory material. I think
the Perl 5 reference material (perl*.pod) is lacking in several respects.
> For Ruby, it looks like the Programming Ruby book is available online
> under the Open Publication License, a great choice I strongly support (see
> masonbook.com), but that's hardly the same as the core Ruby docs.
>
> If that book weren't available online, would someone write the equivalent
> for the Ruby docs? I doubt it. They'd tell people to go read the book.
>
> > Generally, the developers of a technology must make sure it is adequately
> > documented in an accessible online format if they actually want people to
> > learn it. Paperback books are a deprecated, inferior form of
> > documentation. When I'm hacking at something I usually don't consult a
> > book I have for reference. It is simply too inconvenient. Likewise, I
> > learned many things from online resources alone.
>
> I generally like to read a book (or books) first, and then use online
> resources as references. I have no problem with buying the "deprecated,
> inferior" form of documentation.
>
Well, there are many people out there. Some of whom, would rather point
their browsers at the documentation, or just invoke a few commands on
their computer. We should cater for every demographic.
> > If you tell someone that he needs paperware as a reference for a
> > technology or as a way to learn it, then it means that someone did not
> > give enough time to make sure it is adequately documented as is.
> >
> > > But $40 is a pretty small investment, I'd say.
> >
> > Are you willing to make a check for the name of my friend to cover the
> > expenses of buying the book? Or order it from him in Amazon?
>
> No.
>
"But $40 is a pretty small investment"... ;-)
Never mind, we are getting way off-topic here. I'll go on setting up the
Podlanx project, and start collecting user stories.
Regards,
Shlomi Fish
Randal L. Schwartz
Shlomi> My point is that the perl*.pod pages should be suitable for a
Shlomi> large part of our demographic.
AND THEY ARE!
You really don't know of what you speak.
The core audience of Perl is programmers and sysadmins who know Unix
and have smatterings of other languages under their belt, like C, and
because of Perl's origin, are also fluent in English.
Please read my other posting on this.
You just don't get it, do you?
Shlomi> Of course, all of this would have been much easier if
Shlomi> "Programming Perl" was available online for free.
Frankly, other than some editing, there's not a heckuva lot that's in
Programming Perl now that isn't already online. In fact, there
are clearly more tutorials and quickstarts in perl*.pod than there
is in Programming Perl now!
Shlomi> There are already some replacements for "Learning Perl" (like
Shlomi> Simon Cozens' book) online.
Why must *everything* be free?
Maybe you don't realize that even with the wonderful sales of the
books I've been involved in, the return has never been greater than a
bit better than minimum wage when you count the hundreds of hours that
go in to making a quality book.
Shlomi - you disrespect the very people that you want to entice into
a different behavior.
The core docs (free!) meet the needs of the core audience. When
that's not enough, online communities fill in the gaps. When there's
a market demand for more than that, commercial entities have stepped
in to help.
Where is the failure you keep noting?
Shlomi Fish
> >>>>> "Shlomi" == Shlomi Fish <shl...@vipe.technion.ac.il> writes:
>
> Shlomi> My point is that the perl*.pod pages should be suitable for a
> Shlomi> large part of our demographic.
>
> AND THEY ARE!
>
> You really don't know of what you speak.
>
> The core audience of Perl is programmers and sysadmins who know Unix
> and have smatterings of other languages under their belt, like C, and
> because of Perl's origin, are also fluent in English.
>
My friend:
1. Knows C well enough. (at least the language itself)
2. Is fully fluent in English.
3. Has a little (but not a lot of) background in UNIX.
And still found the man pages (at least those that ship with RedHat 9.0)
hard to understand.
By demographic I also mean the demographic of people who are relatively
new to Perl, not just or even more so than the people who are already
fluent with it.
> Please read my other posting on this.
>
I read it again now. I do not agree with it completely.
> You just don't get it, do you?
>
> Shlomi> Of course, all of this would have been much easier if
> Shlomi> "Programming Perl" was available online for free.
>
> Frankly, other than some editing, there's not a heckuva lot that's in
> Programming Perl now that isn't already online. In fact, there
> are clearly more tutorials and quickstarts in perl*.pod than there
> is in Programming Perl now!
>
Probably, but as a concentrated _reference_, Programming Perl beats the
hell out of the core (non *tut) man pages. And the perl*.pod documents are
considered the core reference documentation to Perl.
> Shlomi> There are already some replacements for "Learning Perl" (like
> Shlomi> Simon Cozens' book) online.
>
> Why must *everything* be free?
>
I'm not saying it should. The way I see it, putting "Learning Perl" online
now would be redundant. There are already good replacements for it
available online.
> Maybe you don't realize that even with the wonderful sales of the
> books I've been involved in, the return has never been greater than a
> bit better than minimum wage when you count the hundreds of hours that
> go in to making a quality book.
>
Very well. So, you agree that there is more about writing a book than
getting payed for it? And I'm not sure that putting the Camel book online
would harm its sales one bit. For example, if I were an employer, I would
make sure my company bought a copy of it (and other good books) to
circulate between the employees. (and I would recommend my own employer to
do so as well). If or if not it is available online.
> Shlomi - you disrespect the very people that you want to entice into
> a different behavior.
>
I do not.
> The core docs (free!) meet the needs of the core audience. When
> that's not enough, online communities fill in the gaps. When there's
> a market demand for more than that, commercial entities have stepped
> in to help.
>
> Where is the failure you keep noting?
>
I'd like to have a good, free, high-quality reference for Perl, that would
be suitable for beginners as well as hard-core Perl/UNIX/shell/whatever
hacker-supreme gurus. Something like Python has at
http://www.python.org/doc/2.3.2/, PHP has at
http://www.php.net/manual/en/, etc. Is it too much to ask? Is it too much
to expect? And if it is, how come you explain that it exists for both
Python and PHP now, which are two of our biggest competitors?
Yet, even as I tried to revamp the existing documentation and make it
idiot-proof (without reducing its usability for experts), I keep getting
feedback as "No! Let's keep it as guru-centric as it is!". I believe the
perl*.pod pages have outgrown their purpose as common UNIX "man pages" and
have become the primum reference for Perl. As such, they should be made
more suitable for people who are less knowledgable then the average
_current_ Perl programmer, or else we'll hear people saying: "I thought
about studying Perl, but heard it has an awful documentation and so
learned PHP/Python/whatever instead." or "I tried learning Perl, but could
not make heads nor tails of its man pages so I switched to
PHP/Python/whatever".
As time goes by, the younger generations who became introduced to
computers in an early age, will be less and less willing to bother getting
hold of a book just to learn how to hack something. For them, learning to
hack something is a trial-by-error, write-this-write-that,
consult-this-and-that, google-here-and-there, etc. procedure. I know,
because I can tell that that's how I learned a great deal of things, and
still do to a great extent. And Python and PHP give way to these
kind of people much more than Perl at the moment.
I think this all makes sense.
Chromatic
> For example, if I were an employer, I would make sure my company bought a
> copy of it (and other good books) to circulate between the employees.
> As time goes by, the younger generations who became introduced to
> computers in an early age, will be less and less willing to bother getting
> hold of a book just to learn how to hack something. For them, learning to
> hack something is a trial-by-error, write-this-write-that,
> consult-this-and-that, google-here-and-there, etc. procedure. I know,
> because I can tell that that's how I learned a great deal of things, and
> still do to a great extent.
These are both examples of the logical fallacy known as "hasty
generalization". It is a logical fallacy to argue that everyone (or, at
least, many people) will behave a certain way just because you claim
that you would behave that way in certain circumstances.
Besides that, as Andy pointed out, it's really a waste of time to argue
this. The best way to get your point across is to produce improved or
new documentation for public review. If it's useful and accurate and
the pumpking likes it, it'll be accepted into the core.
If not, nothing stops you from putting it up on your own site.
You don't need a big project for this. You don't need legions of
volunteers, use cases, or a documented workflow process. You just need
to sit down and do it. If it's useful, it'll work out. If not, or if
no one with the time, talent, or desire steps up to help, it won't.
No amount of arguing, berating, or blue-sky dreaming will change this
because this is how it works.
If you do start writing documentation instead of e-mail, one useful idea
floated on p5p recently was a glossary of terms used in the
documentation. That'd be especially helpful for people who lack a Unix
background that much of the documentation assumes. It's also a much
smaller job than rewriting Unixy terms out of tens of thousands of pages
of documentation.
-- c
Yitzchak Scott-Thoennes
> If you do start writing documentation instead of e-mail, one useful idea
> floated on p5p recently was a glossary of terms used in the
> documentation. That'd be especially helpful for people who lack a Unix
> background that much of the documentation assumes. It's also a much
> smaller job than rewriting Unixy terms out of tens of thousands of pages
> of documentation.
chromatic, I have a vague recollection that you have some association
with O'Reilly. Can you or someone else look into releasing the
Programming Perl glossary? Even from the 2nd edition would be
nice[1]. I'd be glad to format it into a perlglossary.pod.
[1] I actually only have the 2nd edition, and am only assuming the 3rd
has an updated glossary.
Stas Bekman
> My friend ...
Shlomi, is it possible that your friend is you?
Just kidding ;)
But seriously, you don't want to make enemies with the very people who decide
whether to commit your contributions or not. With every post on the line you
have taken now, your p5p karma is exponentially decrementing. Probably it has
already passed 0 and heading into a deep minus. Once you are in minus, it will
take a hell of an effort to get yourself above zero. People will simply ignore
your posts, without even trying to see whether they are of any use.
Before you come out with any big suggestions you need to gain that karma by
working hard and contributing a lot. You don't have to be a core C programmer
or understand perl guts to be a great asset to the perl community.
As someone who wrote a lot of docs in the last 5 years, if you will allow me
to give you an advice, it's really easy to improve docs incrementally by just
watching discussions on this list, beginners list, perlmonks.org and any other
lists that you are hanging on, and post patches based on the threads that
won't have been started if the docs were there, and fixing the gaps by making
summaries of those threads and posting them here as patches to .pod files.
Notice that you don't even have to participate in those threads, all you need
is to be a good librarian.
The majority of the mod_perl 1.0 guide
(http://perl.apache.org/docs/1.0/guide/) which is more than 1000pp worth of
docs, was written just like that. People asked questions on the list, gurus
have answered them, someone has summarized those threads and added them to the
docs, so the broken records effect won't repeat again. It worked and still
works perfectly for us, and you can do the same.
Take it in baby steps and you will get far...
As for gaining back your karma, stop this thread right now, don't post any
follow ups which just turn into more flame baits. Not even to this email. Take
a deep breath. Go over the p5p archives from the last week and see whether
there was something discussed that is not (well?) documented well in .pods and
post a patch fixing the situation. Once you are done, go to the week before,
and repeat the process again. The cool thing is that you don't have to think
about what should be fixed, others tell you that all the time.
Many times I don't have the time to write summaries, so I mark candidate
threads as something that I'd like to be documented. and hopefully come back
to them later. In fact I've a whole lot of docs to write, based on the recent
input from TomC and NI-S about the intricacies of the IO stuff. I hope I'll
catch up with those soonish.
Finally, it's being a good example that you are after, not volunteers. You
want to be an example to other potential contributors. When people see that
someone does a great job contributing, they want to do the same (who am I
kidding ;).
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:st...@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Chromatic
> chromatic, I have a vague recollection that you have some association
> with O'Reilly. Can you or someone else look into releasing the
> Programming Perl glossary? Even from the 2nd edition would be
> nice[1]. I'd be glad to format it into a perlglossary.pod.
Good idea! I've started looking into this.
-- c
Adam Turoff
> On Fri, 28 Nov 2003, Randal L. Schwartz wrote:
> > Where is the failure you keep noting?
>
> I'd like to have a good, free, high-quality reference for Perl, that would
> be suitable for beginners as well as hard-core Perl/UNIX/shell/whatever
> hacker-supreme gurus. Something like Python has at
> http://www.python.org/doc/2.3.2/, PHP has at
> http://www.php.net/manual/en/, etc. Is it too much to ask? Is it too much
> to expect? And if it is, how come you explain that it exists for both
> Python and PHP now, which are two of our biggest competitors?
Shlomi, this is the third or fourth time you've held up the Python and
PHP documentation as an idealized version of what you think the Perl
docs should be.
Both PHP and Python were created with a primary goal of being easy to use
for beginning programmers -- those new to programming, those new to the
language, and those who do not have deep experience with Unix or some
other platform. Comparing Perl's docs to those of Python and PHP is simply
a red herring. Perl *NEVER* had a goal of being easy to learn as a first
programming language, or being easy for non-Unix hackers to learn. Perl
was designed to be easy to *USE*, initially by english-speaking Unix
hackers, and now, sixteen years later, Perl is used by programmers around
the world speaking a variety of different languages, using different
operating systems, with skills ranging from the newbie baby-talk
programmer to the very experienced hacker.
Perl is a power tool designed and used by know what they want to do an
need to do it with a minimum of fuss. Perl's documentation, printed
books, magazines, websites, mailing lists, conferences, tutorials and
either (a) cater to that audience or (b) teach the skills necessary to
become part of that audience.
We're sorry that your friend can't find the information he needs across
the thousands of pages of documentation, gigabytes of web content, or
hundreds of books on the topic. Quite frankly, it is not our job to
make Perl as easy to learn as possible for the greatest number of people
across the globe, regardless of aptitude, ability to pay, the state of the
<insert-country-name-here>'s economy, or access to a computer.
Furthermore, your friend's immediate problem seems to have been solved
already. He doesn't need to *BUY* Programming Perl, he needs to *READ*
it. Lending him your copy (gasp!) addresses his immediate needs.
Attacking literally thousands of volunteers telling us, "your docs are
all bad because my friend can't understand them!" doesn't help anyone,
especially you or your friend.
Finally, you have failed to prove that there even *is* a significant gap
in Perl's documentation. You have succeeded in proving that *you* *think*
there is, based on a handful of data points. You have also succeeded in
demonstrating that the vast majority of those who are competant enough to
help you disagree with pretty much all of your basic assumptions.
> As time goes by, the younger generations who became introduced to
> computers in an early age, will be less and less willing to bother getting
> hold of a book just to learn how to hack something. For them, learning to
> hack something is a trial-by-error, write-this-write-that,
> consult-this-and-that, google-here-and-there, etc. procedure. I know,
> because I can tell that that's how I learned a great deal of things, and
> still do to a great extent. And Python and PHP give way to these
> kind of people much more than Perl at the moment.
If that's the case, then don't let us stop you. You don't need our
permission to write better docs that let everyone learn how to program
Perl. Get started and let us know the results. If the need is truly as
great as you say it is, your docs will surely be indispensible.
Z.
Iain Truskett
[...]
> If you do start writing documentation instead of e-mail,
> one useful idea floated on p5p recently was a glossary of
> terms used in the documentation.
That would be:
http://faq.perl.org/glossary.html
Source POD, along with the FAQ, available from:
cvs -d :pserver:anon...@cvs.perl.org:/cvs/public co perlfaq
Patches sent to perlfaq...@perl.org are welcome.
cheers,
--
Iain.
Arthur Bergman
On Friday, November 28, 2003, at 08:31 pm, Shlomi Fish wrote:
>
> I'd like to have a good, free, high-quality reference for Perl, that
> would
> be suitable for beginners as well as hard-core Perl/UNIX/shell/whatever
> hacker-supreme gurus. Something like Python has at
> http://www.python.org/doc/2.3.2/, PHP has at
> http://www.php.net/manual/en/, etc. Is it too much to ask? Is it too
> much
> to expect? And if it is, how come you explain that it exists for both
> Python and PHP now, which are two of our biggest competitors?
>
>
Shlomi,
Here in London.pm we usually use the term JFDI when discussing problems.
This stands for
JUST FUCKING DO IT
So I suggest, instead of wasting more of my valuable time with this
thread, go and write a good free high-quality reference for Perl that
would be suitable for beginners.
Arthur
Shlomi Fish
I intend to do just that.
Nicholas Clark
no-one here is not stopping you starting this project, so please commence.
On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish wrote:
> 1. Collect user stories on what they did not understand in the
> documentation.
>
> 2. Assign volunteers to remedy these issues.
>
> 3. Assign volunteers to go over sections of the man pages and try to
> paraphrase them to make them clear enough.
This is not the first thread that you have started where you assume that
there is a pool of volunteer labour that can be tapped into.
Life is not like this.
(I forget what the previous thread was, but at that time I checked my
understanding of Life with my father, who has nothing to do with computer
programming, and he and I are in agreement - in a volunteer organisation
the most precious commodity, the one in shortest supply, is volunteers.
ie people who will actually do stuff, rather than just talking about doing
stuff.)
We (for any perl definition of "we") does not have a pool of volunteer time
that we can lend you for this project. You will have to find your own.
You may not be counting, but there are about a dozen active perl 5
developers on p5p, about half with commit rights. Similarly parrot has
about 5 active committers.
This is the number of competent volunteers that a well established 16-year
old programming language used by many individuals and many organisations
can muster. From the entire world.
On Thu, Nov 27, 2003 at 04:37:41PM +0200, Shlomi Fish wrote:
> And that's it, is bad, because not everyone here knows C-shell or ever has
> to work with it. As for the exec example. One can say:
>
> exec() executes a different program instead of the current perl
> program. That is, it will run instead of the script and execution
> will never return to the script. (unless in case of error, in
> which it is usually recommended to exit immediately).
>
> That's it! Brief, to the point, and portable for all people. UNIX 101 for
> everybody.
Sure that's good for the introduction.
But I don't want that as the only text in the man pages. The man pages are
meant as a reference, not a tutorial. For reference I want to know what
the errors might be. I want to know that scalar exec uses the shell.
(which has security implications).
Somewhere between I'd want to know that the new program runs as the same
process, and what the rules on inheriting things are (such as open file
descriptors)
> As a general rule, one can expect a beginning Perl programmer to refer to
> the perl*.pod documents looking for a nice information or a trick. I feel
> that they can be made suitable for almost everybody, without sacrificing
> their use for expert hackers.
There seems to be a consensus on perl5-porters that ever more documentation
is good.
Bollocks.
LESS documentation is good. If you can say the same things with less words,
this is much better. The danger we have in increasing the amount of
documentation is given constant programmer time, they read less and less
of it, and are more and more likely to miss the important bits.
I feel that we need to keep the reference separate from the tutorial.
It may well be possible to build them from the same pod source, (
=begin tutorial
=end
=for tutorial
IIRC)
but reference documentation such as man pages doesn't want the tutorial
in it.
On Thu, Nov 27, 2003 at 11:52:36AM -0800, Yitzchak Scott-Thoennes wrote:
> On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish <shl...@vipe.stud.technion.ac.il> wrote:
> > Once we're through, we release Perl 5.8.3 with all of the changes applied.
> > (or maybe delay it to Perl 5.10.x due to configuration management issues)
>
> I think you should aim for 5.8.5 (June 2004) at the earliest. I also
> assume Nicholas will want the changes to go into bleadperl, and then
> be integrated back to maint.
I'm glad that someone is paying attention :-)
Yes and yes.
Also why do documentation changes have to be step changes? Can't most of
this be done incrementally?
On Fri, Nov 28, 2003 at 12:19:47PM +0200, Shlomi Fish wrote:
> I was just posting the idea here to get some feedback. (not one of
> incredibly good S/N ratio evidently, but still)
I thought that the S/N was OK as far as p5p goes.
It just didn't agree with you on some of the points you make.
Andy:
> > Stop arguing about it and DO IT. If it's a worthwhile project, people
> > will come on board and make things happen. If it's not, then they
> > won't. It's the way open source works.
> Very well, I will.
Good luck.
Nicholas Clark
H.Merijn Brand
> > Haha, it makes for a good laughter that particularly the GNU folks would
> > complain about the Perl documentation. I am sure that I had never learnt
> > Perl if it had been documented the way GNU projects are.
> >
>
> It depends on the GNU project. GNU awk has an excellent documentation and
> I learned Awk from there (albeit after I knew Perl). GNU make also has a
> good documentation, and I think I learned how to write makefiles from
> there. Still, I found out that it was hard to find out what I was looking
> for there, after I became experienced.
If you regard 'info' files as documentation, I fully disagree. One has to be
an emacs user to be able to read that, and even then, finding the info you
need takes too much time. man or pod, all info is ready for immediate
trashcanning and can IMHO *never* be marked good documentation. If you ask me,
it cannot be marked documentation at all.
I realy like perl's pod, and not only because it auto-translates to plain old
manpages, but also because it rather well translates to HTML, which is easy to
browse with Opera, and then is rather good to print.
> Some GNU packages are documented just enough to explain the basic flags
> and operation modes, and nothing too much besides. For example, the docs
> of gcc do not teach you C, or the docs of wget do not teach you WWW
> basics. It vastly depends on how original the particular application is.
>
> I found the GNU documentation as a whole to be a good, clear, reference,
> which I'm not sure can be said on the Perl pod files.
--
H.Merijn Brand Amsterdam Perl Mongers (http://amsterdam.pm.org/)
using perl-5.6.1, 5.8.0, & 5.9.x, and 806 on HP-UX 10.20 & 11.00, 11i,
AIX 4.3, SuSE 8.2, and Win2k. http://www.cmve.net/~merijn/
http://archives.develooper.com/daily...@perl.org/ per...@perl.org
send smoke reports to: smokers...@perl.org, QA: http://qa.perl.org
Rafael Garcia-Suarez
>
> If you regard 'info' files as documentation, I fully disagree. One has to be
> an emacs user to be able to read that, and even then, finding the info you
> need takes too much time. man or pod, all info is ready for immediate
> trashcanning and can IMHO *never* be marked good documentation. If you ask me,
> it cannot be marked documentation at all.
I wholeheartedly agree with this intolerant statement.
Also, I've often remarked that it's very hard to find specific info in
the GNU docs : changes and history ? no. Deviations from the standard ?
nope. Portability issues ? none. Edge cases ? surely you jest. The perl
docs aren't so bad after all.
Calle Dybedahl
> If you regard 'info' files as documentation, I fully disagree. One
> has to be an emacs user to be able to read that
Not that I want to defend the info format, but that statement is
wrong. There are standalone info browsers available, and there has
been since at least the 1980s (the first one I ever used ran under
TOPS-20). One is included in the FreeBSD base system, even.
Given that, I don't think the info format does anything that HTML
doesn't do at least as well.
--
Calle Dybedahl <ca...@lysator.liu.se>
"I'd definitely like to see more rubber-clad literature in future."
-- Penny Dreadful
Alan Burlison
> I found the GNU documentation as a whole to be a good, clear, reference,
> which I'm not sure can be said on the Perl pod files.
I can think of an English phrase that sums up what I think of that statement
in one word, but I'll refrein from using it in polite company.
You've dug such a big hole for yourself your suggestion is never going to
get off the ground. Rewriting the perl docs for one person's benefit (you
friend) is never going to happen - get over it. I suggest you cease banging
on about this topic - it has become very tedious.
Regards,
--
Alan Burlison
--
Peter Scott
mer...@stonehenge.com (Randal L. Schwartz) writes:
>The core audience of Perl is programmers and sysadmins who know Unix
>and have smatterings of other languages under their belt, like C, and
>because of Perl's origin, are also fluent in English.
Do you have a reference for this? Please note that I'm neither
disagreeing with you nor attempting to be combative; I have a
vested interest in knowing the demographics of the Perl audience
and real data on same would be highly useful. It seems likely
to me that O'Reilly may have done a survey to which you are
alluding. Google only got me salary data.
--
Peter Scott
http://www.perldebugged.com/
*** NEW *** http//www.perlmedic.com/
Nick Ing-Simmons
>
>There seems to be a consensus on perl5-porters that ever more documentation
>is good.
>
>Bollocks.
>
>LESS documentation is good. If you can say the same things with less words,
>this is much better. The danger we have in increasing the amount of
>documentation is given constant programmer time, they read less and less
>of it, and are more and more likely to miss the important bits.
Also given finite maintainer time, the more docs there are the more
likely they are to "rot" and not track the code changes.
I hold up the many places where aspects of 'open' are now documented
as an example.
What the commercial books get, that pods do not, is an editor.
Yitzchak Scott-Thoennes
> Also why do documentation changes have to be step changes? Can't most of
> this be done incrementally?
Each change would certainly get better review if done incrementally.
Mark Jason Dominus
I don't know if this will be interesting,
but here's a note I've had in my PROJECTS file for several years:
Make a permuted index for the Camel book. Ask everyone on
clpm and p5p to open the book at random, enter a one-sentence
desription of something on the page, and mail it to me with a
page number. If they send
Mapping from parentheses to backreference variables in regex match
then make entries for
backreference variables in regex match, Mapping from parentheses to
Mapping from parentheses to backreference variables in regex match
match, Mapping from parentheses to backreference variables in regex
parentheses to backreference variables in regex match, Mapping from
regex match, Mapping from parentheses to backreference variables in
variables in regex match, Mapping from parentheses to backreference
If a hundred people do this, it might be useful. Then again
maybe not---but it's worth a try.
20030907
Get O'Reilly to give you an online copy of the Camel book.
Display a random page, and have the web user fill in a form
with the description. That way you can (a) control the
randomization; (b) ensure that there's no duplication of
effort, and (c) collate the index automatically.
I didn't mention it in the note, but I should probably point out that
displaying a single random page of a book is not going to give people
an opportunity to steal the book.
Stas Bekman
Mark, another way to reach this is to use the brilliant idea used by the
authors of the mod_perl cookbook. They have a full-text search capability on
their site: http://modperlcookbook.org/cgi-bin/swish.cgi
You get to search the real book, and it gives you a short context and the page
numbers in the book. e.g. searching for Apache::Registry:
http://modperlcookbook.org/cgi-bin/swish.cgi?query=Apache%3A%3ARegistry&submit=Search%21&sort=pageno
I've mentioned this idea to Nat, and hopefully we will see ora.com adding this
feature to all ORA books. Next they may want to mix it with Safari.
Andy Lester
> authors of the mod_perl cookbook. They have a full-text search capability
> on their site: http://modperlcookbook.org/cgi-bin/swish.cgi
In Geoff's case, it was totally ad hoc, since the SAMS folks did such
a piss-poor job on the index.
print $invention->mother(); # "Necessity"
xoa
--
Andy Lester => an...@petdance.com => www.petdance.com => AIM:petdance
David Nicol
Do we have a glossary? It is common for reference works to
have glossaries. It is curious that I find myself referring to
ESR's "Jargon pages" rather than a closer reference for perl jargon.
http://catb.org/~esr/jargon/html/go01.html
does not list "transliterate" and tr(1) claims to be short
for "translate."
> But when do you stop? If the goal is to write documentation in English
> for people who don't master English, when do you stop explaining?
> Until you have no multi-syllable words left? Until the documentation is
> 70% dictionary and 30% technical? Until Dr. Suess approves it?
>
> Don't dumb down the documentation. It'll lose value.
>
>
> Abigail
--
david nicol "I'll be working, working; but if you come visit I'll
put down what I'm doing: my friends are important" -- David Byrne
David Nicol
> [...]
> In summary, because to translate is to paraphrase, and because the tr///
> operator does no such thing, transliterate is the correct term to describe
> its operation of mere character-set (that is, alphabet) transcription.
>
> Or did you want it to be "transcription"? :-)
>
> --tom
but tr(1) does neither translation or transliteration in the linguistic
sense. It creates a "translation table" and looks up characters in it
and creates a new string by mapping each character in the input to the
character listed in the table under the input character.
This operation was termed "translation" by some whimsical software
engineer deep in the mists of long-ago, due to the functional similarity
between the operation of tr(1) and the activity of translating language
by looking up words in a bilinugal dictionary.
Tony Bowden
> I've mentioned this idea to Nat, and hopefully we will see ora.com adding
> this feature to all ORA books. Next they may want to mix it with Safari.
And give permission to do so to Amazon?
Tony
Abhijit Menon-Sen
>
> This operation was termed "translation" by some whimsical software
> engineer deep in the mists of long-ago, due to the functional
> similarity between the operation of tr(1) and the activity of
> translating language by looking up words in a bilinugal dictionary.
Er, did you mean to say transliterate instead of translate? If so, then
the rest of your message makes no sense, because there is no similarity
between the operation of tr(1) and looking up words in a dictionary. If
not, then your message still makes no sense, because the operation was
never termed translation in the first place.
I don't understand the argument anyway. My copy of the OED defines the
word transliterate as «To replace letters or characters of one language
by those of another used to represent the same sounds; to write (a word,
etc.) in the characters of another alphabet.»
That's precisely what tr(1) does: takes a string written in one language
(whose symbols are characters in some charset), and replaces the letters
with the language described by the arguments (which consists of the same
symbols, except that the ones in SEARCHLIST are replaced by the ones in
the REPLACEMENTLIST).
Or are people just forgetting that "language" is also a term stolen from
linguistics and given a specific meaning by computer science? :-)
-- ams
h...@crypt.org
:At 2003-12-01 17:50:32 -0600, what...@davidnicol.com wrote:
:>
:> This operation was termed "translation" by some whimsical software
:> engineer deep in the mists of long-ago, due to the functional
:> similarity between the operation of tr(1) and the activity of
:> translating language by looking up words in a bilinugal dictionary.
:
:Er, did you mean to say transliterate instead of translate? If so, then
:the rest of your message makes no sense, because there is no similarity
Though I enjoy such perilinguistic nitpickery in its place (and am itching
to write the rebuttal), I'm not convinced this is it (though, in this
context, I'm not sure what is). Perhaps taking it to direct mail would
be better.
Hugo
Ronald J Kimball
> At 2003-12-01 17:50:32 -0600, what...@davidnicol.com wrote:
> >
> > This operation was termed "translation" by some whimsical software
> > engineer deep in the mists of long-ago, due to the functional
> > similarity between the operation of tr(1) and the activity of
> > translating language by looking up words in a bilinugal dictionary.
>
> Er, did you mean to say transliterate instead of translate? If so, then
> the rest of your message makes no sense, because there is no similarity
> between the operation of tr(1) and looking up words in a dictionary. If
> not, then your message still makes no sense, because the operation was
> never termed translation in the first place.
The operation *was* termed translation in the first place. In fact, tr(1)
is still termed translation: "tr -- translate characters".
Some time ago the perl docs were changed to describe tr/// as the
transliteration operator instead of the translation operator . This was
not a consensus decision, by the way.
Personally, I think "translate" is the better choice. In particular, true
transliteration would sometimes require a single character to be replaced
with a sequence of characters, which is not possible with tr///.
translation more accurately describes the one-to-one relationship possible
with tr///.
Ronald
Shlomi Fish
> At 2003-12-01 17:50:32 -0600, what...@davidnicol.com wrote:
> >
> > This operation was termed "translation" by some whimsical software
> > engineer deep in the mists of long-ago, due to the functional
> > similarity between the operation of tr(1) and the activity of
> > translating language by looking up words in a bilinugal dictionary.
>
> Er, did you mean to say transliterate instead of translate? If so, then
> the rest of your message makes no sense, because there is no similarity
> between the operation of tr(1) and looking up words in a dictionary. If
> not, then your message still makes no sense, because the operation was
> never termed translation in the first place.
>
> I don't understand the argument anyway. My copy of the OED defines the
> word transliterate as «To replace letters or characters of one language
> by those of another used to represent the same sounds; to write (a word,
> etc.) in the characters of another alphabet.»
>
> That's precisely what tr(1) does:
Not exactly. When transliterating a spoken language in another spoken
language, I may have more or less letters in each language for each sound
than the other (depending on how it sounds). For example, in Hebrew the
word "Shalom" has four letters while the English Transliteration has 6.
Regards,
Shlomi Fish
> takes a string written in one language
> (whose symbols are characters in some charset), and replaces the letters
> with the language described by the arguments (which consists of the same
> symbols, except that the ones in SEARCHLIST are replaced by the ones in
> the REPLACEMENTLIST).
>
> Or are people just forgetting that "language" is also a term stolen from
> linguistics and given a specific meaning by computer science? :-)
>
> -- ams
>
----------------------------------------------------------------------
Rafael Garcia-Suarez
> Not exactly. When transliterating a spoken language in another spoken
> language, I may have more or less letters in each language for each sound
> than the other (depending on how it sounds). For example, in Hebrew the
> word "Shalom" has four letters while the English Transliteration has 6.
Hey, I've this great idea : let us start a completely off-topic thread
about transliteration and Unicode surrogates.
David Nicol
> At 2003-12-01 17:50:32 -0600, what...@davidnicol.com wrote:
> >
> > This operation was termed "translation" by some whimsical software
> > engineer deep in the mists of long-ago, due to the functional
> > similarity between the operation of tr(1) and the activity of
> > translating language by looking up words in a bilinugal dictionary.
I took latin in junior high and I remember this algorithm for
doing homework:
0: bookmark glossary in textbook
1: identify latin word
2: look up latin word in dictionary
3: write down english word
4: end-of-homework or goto 1
This maps directly into the operation of tr(1):
0: create dictionary from arguments
1: identify input character
2: look up input character in dictionary
3: write down output character
4: end-of-string or goto 1
> Er, did you mean to say transliterate instead of translate? If so, then
> the rest of your message makes no sense, because there is no similarity
> between the operation of tr(1) and looking up words in a dictionary. If
> not, then your message still makes no sense, because the operation was
> never termed translation in the first place.
man tr on the system I am using claims that tr is "translate"
> I don't understand the argument anyway. My copy of the OED defines the
> word transliterate as «To replace letters or characters of one language
> by those of another used to represent the same sounds; to write (a word,
> etc.) in the characters of another alphabet.»
Transliteration implies this same-sound thing. tr does not have
anything to do with sounds in different alphabets. If you use tr
to implement a reversible single substitution cipher like so:
tr/a-zA-Z0-9/0-9A-Za-z/
you're not pretending that there is a written language where zero
sounds like little ay.
Tr creates a "dictionary" mapping and "translates" the string,
character for character, just like a dissatisfied seventh-grader
doing their latin homework (with extreme disregard for the subtleties
of latin grammar.)
> Or are people just forgetting that "language" is also a term stolen from
> linguistics and given a specific meaning by computer science? :-)
>
> -- ams
Or that reality is a metaphor for Go?
Abigail
> On Tue, 2003-12-02 at 07:28, Abhijit Menon-Sen wrote:
>
> > Er, did you mean to say transliterate instead of translate? If so, then
> > the rest of your message makes no sense, because there is no similarity
> > between the operation of tr(1) and looking up words in a dictionary. If
> > not, then your message still makes no sense, because the operation was
> > never termed translation in the first place.
>
> man tr on the system I am using claims that tr is "translate"
When I started university, we also got introduced to programming, and
programming languages. Our professor taught us that programming languages
used symbols (or keywords), that sometimes looked like English words,
but that was purely a coincidence - they weren't, and one shouldn't
derive the function of a keyword from the meaning of an English word
that looked like it.
I think that was a valuable lessons. I always think of the 'tr' operator
as the 'tee-ar operator'.
Abigail
Tom Christiansen
>as the 'tee-ar operator'.
y??? :-)
--tom