Clear questions and runnable codeget the best and fastest answer PerlMonks

### The sad state of Perl documentation

by SuperCruncher (Pilgrim)
 on Sep 14, 2000 at 02:08 UTC ( #32376=perlmeditation: print w/ replies, xml ) Need Help??

I have a number of problems with Perl's documentation. The way I see it, the documentation is currently provided through a system of antiquated man pages or automated conversions from these man pages to HTML. Documentation is not provided in formats suitable for printing such as PDF. At one point on my long search around Perl.com I was able to find a PostScript version of the documentation. This was for Perl 5.003 or something old like that. Postscript?! Until starting university, I had not encountered files in Postscript format before (I had heard of it, but not encountered). It seems to be a very common thing on UNIX platforms. So Perl started out on UNIX, maybe it's time to loosen the ties? Granted PS can be converted to PDF using the ps2pdf program, but not everyone has the time or knowledge to get this program.

Perl's documentation has its problems, and even worse is that Perl's competitors (well, I don't consider them competitors as I think Perl is far superior, but..) all have documentation available in many formats. PHP has documentation available in many formats and languages. With Python, it's a similar story. I recognise though that Python might not be an option for the free software purists since according to RMS it is incompatible with the GPL.

I had hoped that new sites like Perl FAQ and Perldoc would improve the situation, but perldoc especially seems to be a simple a re-hashing of the standard docs.

I also have problems with the actual documentation itself in some cases (not the actual format). In this node I complained about how I consider the documentation for exec() in perlfunc to be misleading. More recently, I also had the misfortune of trying to figure out the documentation for chmod(), also in perlfunc. As is common throughout the Perl documentation, the documentation for chmod assumes much knowledge of UNIX. I have used Linux for around 2-3 years now (albeit not on my own PC) and I have never once used the octal numbers as a mode for chmod. The authors of the chmod documentation in perlfunc consider mentioning how to calculate mode values is beyond the scope of the documentation. It's bad enough that Perl doesn't support the symbolic a+r etc. notation, and it's even worse that the documentation for Perl's chmod function doesn't at least include a table with the values of the most commonly used symbolic modes.

Perl does have good documentation provided by O'Reilly in the form the llama and camel books. However, I'm sure most monks will realise that these books (although very useful) are quite costly. At Amazon.co.uk, Learning Perl and Programming Perl currently cost £15.96 and £26.80 respectively.

I'd be willing to try and help out with the Perl documentation, does anyone know who to ask?

And BTW, I know this post would probably have belonged in the "Rant" section of PerlMonks if there was one, but to me it's the one thing of Perl that really needs major improvement

Comment on The sad state of Perl documentation
Select or Download Code
RE (tilly) 1: The sad state of Perl documentation
by tilly (Archbishop) on Sep 14, 2000 at 02:33 UTC
If you have specific changes, feel free to download the current development version and submit patches. You will need a working diff program, a slow one is available free from PPT. (I recommend using the "-u" option.)

As for the other complaints, I would suggest modifying POD::Parser to spit out other kinds of documentation.

However for the record I started out with less Unix background than you have, and by and large I found the online documentation quite readable and informative. There were sections I had to go back to, nor was it particularly easy, but I am impressed with the quality of the information.

RE: The sad state of Perl documentation
by mdillon (Priest) on Sep 14, 2000 at 03:04 UTC
it's pretty easy to make PDF's from POD using fairly common tools. watch:
$perldoc -u HTTP::Request > HTTP_Request.pod$ pod2latex HTTP_Request.pod
$perl -e 'open TEX, "+< HTTP_Request.tex" or die; @l = <TEX>; seek TEX, 0, 0; truncate TEX, 0; print TEX "\\documentclass[10pt]{article}\\begin{document}",$/,
print TEX map { s/^%\\/\\/; $_ } @l; print TEX "\\end{document}",$/;
close TEX;'
$pdflatex HTTP_Request.tex [download] here are HTTP::Request and strict. PostScript is similarly easy to generate by replacing pdflatex with pslatex. Or even skip all the other steps and just use Pod::Pdf directly! {grin} I think you're largely missing the point. Sure, I can convert the document in whatever format using module Foo::Bar, but I shouldn't have to. What if I want to get a nice clean print-out of part of the perl documentation? The quickest way to do this is to download a PDF, and print the desired pages. The solution should not be that I am forced to write a script to do the converting for me. Also imagine poor Perl newbies trying to figure out how to install module Foo::Bar required for converting into whatever format and then trying to figure out how to actually write the script. if you're really so worried about the "poor newbies", then undertake this task yourself. don't wait for "the leaders" of the "Perl community" to do it for you. you don't even have to write a script. you can just use the one i wrote, or take merlyn's suggestion and use pod2pdf or its underlying module Pod::Pdf. then, find space on a web server somewhere and keep available an up-to-date version of your compiled documentation. i haven't missed any points. you have in assuming that someone else should be creating this documentation that you want. more power to whomever should decide that printable documentation is important enough to themselves and other users of Perl to implement and maintain a resource such as this. RE: The sad state of Perl documentation by extremely (Priest) on Sep 14, 2000 at 03:50 UTC I think you'll find revamping the documentation to be a multi-month full-time job. That is why people like Randal wind up selling books, documentation is HARD! If you think you can do better that the current state of things, MORE POWER TO YA! Me, I've found the docs to be almost exactly what I want. I rarely consult the books these days in favor of the perldoc pod system. (well, and 'less' for the more inscrutable modules. =) Maybe you should consider championing a perl6-docu list for proposed changes in how POD should be used/written in Perl6. If you get something going come back here and shout it from the bell towers! I'll stick my nose in on something like that. --$you = new YOU;
honk() if \$you->love(perl)

RE: The sad state of Perl documentation
by Maclir (Curate) on Sep 14, 2000 at 04:29 UTC
Generally, there are two types of documentation:

1) Stuff that tells you how to do things. This assumes that you know what you want to do in the first place ("Hmmm - is the recurse option on chmod -R or -r?"). We call these "reference manuals" - the Camel book is a fine example of such a beast.

2) Stuff that tells you what things to do. This means you have an understanding of the end result that is needed, but not sure of the way to do it. The "Perl Cookbook" is a fine example of such a manual. These are far more useful for use beginning programmers.

But - much of perl's power lies in the great array of modules that are constantly being developed. The documentation of these varies from wonderful to woeful. But, what is missing is an extension of the 'how to' approach to incorporate these modules. For example, how many of the questions posed here are answered by:

You should use module Foo::Bar::WDNNS_Documentation

Now maybe that is what more attention needs to be focussed on. There are lots of resources on the web - merlyn's Web techniques column is one that immediately comes to mind. At least the experts here can regularly point us to such sources.

But - much of perl's power lies in the great array of modules that are constantly being developed. The documentation of these varies from wonderful to woeful.
True, but I am unhappy with the standard documentation, not the documentation for other modules. There's no way to force authors of modules to write documentation (except for maybe not putting them into CPAN unless they are accompanied by documentation, but I don't think this would be a good thing), and I'm not too worried about that, but I think that the basic core of the language should be well documented.

I will have to completely disagree here.

Perl itself comes with a huge amount of docs. I am sure it's harder to find your ways around it that let's say a CD player, but that's only because using Perl is a little more complicated than using a CD player.

And I am really unhappy with the sad state of the documentation for all VCR's I have ever owned by the way ;--)

I think enough people care about, and work on the core docs that it is quite comprehensive.</p

The problem is really with modules, as most of the time they are written, supported and documented by te same poor guy, usually better at (and more interested in) writing code than docs.

Plus the author is not necessarily the best person to write an introduction to a complex module. Things that seem easy and natural for someone who has written socket handling software for 10 tears might not be quite as natural to Joe Poor Perl Hacker who was writing COBOL up until last month.

So I think one of the best ways for module users to give feedback to the author is probably to write a piece on how they used the module, or just give some feedback on the doc.

I was documenting religiously and in great detail every single method in XML::Twig, until I realized through a random email on a mailing list stating that a potential user had given up after the first 2 screens (out of 22!). I needed to write a tutorial introducing the basics of the module (but more complex than the usual simple synopsis). Darn! But I'm really glad I caught that feedback. I hate coding stuff that will never be used because nobody looking for an easy way to solve a simple problem did not make it to the 44th method in the 3rd class of the module which was exactly what they needed.

So really I whished module docs were better and I think feedback could really help. But I'm happy with the core docs, thank you.

And stop killing trees and use perldoc, man and grep!

RE: The sad state of Perl documentation
by jplindstrom (Monsignor) on Sep 14, 2000 at 15:19 UTC
I remember when first learning Perl that the problem for me was knowing which part of the documentation to read. Reading the FAQ a number of times as I got more comfortable with Perl was very useful, but the most important man page for beginners is IMHO perlfunc.

I still have a special link to that page in my local docs structure simply because most times when I need to refer to the documentation, that's the page I'm after.

RE: The sad state of Perl documentation
by dmmiller2k (Chaplain) on Sep 14, 2000 at 17:49 UTC
> Perl does have good documentation provided by O'Reilly in the form the
> llama and camel books.

Perhaps you've noticed, perhaps not. The Camel book is essentially a printed version of the perlfunc perldoc/manpage. Which means in particular that the exec function is just as obscurely documented for £26.80 as for the free machine readable version.

As to the state of the documentation, you should be aware that the evolution of perl over the past two or three years (since 5.003) has been in great leaps and bounds, with the number of modules in the CPAN more or less keeping pace. The amount of documentation is awe inspiring, if some of the individual examples of it perhaps are not.

Now that 5.6 is out, give the documentation a year or so to catch up.

In the meantime, sites like this one can fill the gap, at least in terms of pointing out which of the hundreds of "things" to read might be helpful apropos of a particular problem.

Camel 3 has been updated to document the non-existent (yet) 5.6.1. Llama 2 is independant of the underlying Perl version, since I'm just showing the basics parts of Perl, which change far less from release to release. {grin}

Llama 3 will show a few new additions like our, but nearly all the examples and exercises would have been just as home on 5.4 from two or three years ago.

RE: The sad state of Perl documentation
by gumpu (Friar) on Sep 14, 2000 at 17:56 UTC

Postscript?! Until starting university, I had not encountered files in Postscript format before (I had heard of it, but not encountered). It seems to be a very common thing on UNIX platforms.

To put things in perspective. Postscript is not such on odd format. Pdf is basicially a souped-up form of postscript. Furthermore a lot of printer use postscript. A lot of programs can generate postscript, even on Win32 (for instance Word, IE). There is also a free postscript viewer (Ghostscript), this also runs on Win32.

Also, while pdf is nice (seach and hyperlinks are useful) it is also a proprietary format, the readers are free, but you have to pay money for the distiller.

Have Fun

And besides Postscript is a cool programming language! I haven't written any programs in Postscript in a while, though. Using Perl to generating Postscript for drawing complex, detailed graphs with lots of labels (basically maps) was pretty easy (no modules involved, I don't think there were Postscript modules way back then) and let me view and print the graphs lots of places. But the world has change a lot since then...

- tye (but my friends call me "Tye")
(redmist) RE: The sad state of Perl documentation
by redmist (Deacon) on Sep 14, 2000 at 22:43 UTC
"So Perl started out on UNIX, maybe it's time to loosen the ties?"

For the love of all that is good and wholesome, no! Under a *nix, developing Perl (and pretty much anything else) is soooooo much easier and better than under Windows. I am not trying to be a bigot (although I am probably being one anyway), but under *nix you have a real Command Line Interface in which you can use utilities like man, grep, tail, and perldoc to accomplish what you need to do in a more efficient manner. Plus you have multiple terminals (which you could have in Windows, but it would hog the task bar and screen in addition to the fact that it would be more difficult to keep track of the content on each terminal).

It's not really *one* thing or another, but many little things that make *nix a better platform to develop on than Windows.

Perl's association with UNIX is important because some of the functionality and use of utilities in *nix has carried over into perl itself. Grep (and regular expressions) for example. In addition to this, Perl culture has been influenced by *nix culture enough that it is important that we not forget our roots. There is no reason why Perl should become more disassociated from UNIX.

As for the quality of the docs, I think that the majority of the docs are fine as far as quality is concerned. Some are a bit misleading or are not as clear as I would like, but that's the nature of the beast. With as much documentation as Perl has, you cannot expect it to be perfect.

On the format issue, I don't know why you are so attached to the pdf format. If you want to print out some docs, nothing is stopping you. If you want docs with links, then docs are also available in html form. I don't understand why this is such a big issue for you.

Cheers, redmist
redmist.dyndns.org
email::redmist
Actually, red, I gotta disagree with you. I feel, and I know many others do as well, that UNIX is NOT a good development platform. Sure, you have this powerful Command Line Interface - so what? Humans do not work that way. The reason the GUI was considered such a huge advance is because it WAS. Even the ability to open four small term windows, each a complete CLI, and see all of them at once is a huge advantage. Add things like inline spell-checking, good Copy/Paste systems, and an interface that automates as much as possible, and you make for an interface that makes almost ANYTHING more efficient than it is with a CLI, including writing code. CLI is powerful, yes, but it's not perfect. It's a hammer, and a good one, but sometimes you need a scalpel.

As it happens, I think the documentation that comes with the core of Perl is pretty good. On the other hand, I *DO* think Perl should dissociate itself from Unix. Why? Because Perl is a tool. It's a great tool, as perfect for its purpose as any - but its purpose is to make live easier for systems admins and web developers. And despite what the hype would have you believe, the internet is NOT UNIX. It never will be. The internet is ANY operating system. Perl should be, too. Take with it what we like about Unix, certainly. But just because Unix was the cradle of Perl doesn't mean Perl should stay there. You can't live in the cradle forever.

- email Ozymandias
OK, message recieved, zero distortion...I still disagree with you though.

"that UNIX is NOT a good development platform. Sure, you have this powerful Command Line Interface - so what? Humans do not work that way."

I don't think that your point about CLI and humans not working in the same way is valid. Why? Because computers and humans don't work in the same way. But it's ok this way. I have to adapt to the machine, because it won't adapt to me (at least until really, really good AI comes along). Even if the machine *could* adapt to me, I don't think that I would want it that way. I have learned to work with CLI, and have come to love it.

One of the reasons why I think that CLI can be so great is that the rules are clearly defined (not intuitively, but through documentation) and both you and the SW that you are interacting with "knows" that you are two seperate entities, with different ways of working. In this type of environment, the SW or interface will not try to anticipate what you want or how you want to do something. Anticipation of human action usually results in it doing the opposite of what it's original purpose was: to help you and make you more efficient.

Once you have adapted yourself to the CLI (or another non-human-anticipating interface), you can reap the results of such an interface.

"And despite what the hype would have you believe, the internet is NOT UNIX. It never will be. The internet is ANY operating system. Perl should be, too."

I don't want Perl to be tied to UNIX in such a way that would inhibit or diminish it's use on other platforms either. I just think that is important to keep the ties to UNIX that are already there. We should *transcend* the cradle.

I realize that the Internet is not UNIX, but a damn big part of it is...and UNIX is also a big part of other networks and computing as a whole.

redmist
redmist.dyndns.org
email::redmist
PerlMonks isn't the place for OS wars, but I have a few slightly on-topic comments:

Actually, red, I gotta disagree with you. I feel, and I know many others do as well, that UNIX is NOT a good development platform.

I disagree with you.

powerful Command Line Interface

Unix != CLI. The Unix (and really I'm talking about all the Unix spinoffs and clones here) philosophy has to do with operating system structure, and nothing to do with GUI vs CLI.

I run Linux, running X windows, and Keep 10-12 xterm (CLI) windows open. The GUI allows this. This is not different than Windows or Macintosh in any way. However I have more tools (Thanks to GNU) available, I have compilers available (Does Windows ship with a C compiler?), etc. ActiveState has to do a fair amount of work for their Windows version of Perl, whereas the conversion to BSD or Linux or other Unix-like systems is far easier.

Windows and Mac restrict access and reduce flexibility. That is why they are a poor development environment, and why Perl stays "in it's cradle".

The reason the GUI was considered such a huge advance is because it WAS.

Absolutely. And it was a huge advance YEARS before Windows was ever thought of. But it isn't a replacement, it's an extension. Some tasks are very difficult to do in a CLI, while others are very difficult to do in a GUI.

Perl is a tool. Perl is flexible. It is and should be system independant.

Sure, you have this powerful Command Line Interface - so what? Humans do not work that way.

/me is surprised to learn that he is not human.

I hate to reach for the mouse because is not well designed for use by humans. It was apparently a design stolen from the race in "The Mote in God's Eye". I'm a programmer so I have to actually type quite a bit and I really prefer to do it fast so I actually use two hands for it. Everytime I have to reach for the mouse (and it usually amazes people how infrequently I'm forced to) I have to take one hand away from the keyboard. I hate that and it slows me down.

The great advantage to the GUI is that it makes the learning curve more shallow. This is lovely for things that you've never done before or things that you only rarely do. For things that you do all of the time and that you are supposed to be an expert at, a GUI almost always gets in the way and slows things down. On the other hand, I like climbing steep curves so I'm probably a freek as well as being from another planet (certainly many of my cow orkers don't bother to become "experts" at editting, to my eye). On the gripping hand, there is more than one way to do user interfaces (TIMTOWTDUI) and no one way is the best for all situations.

- All in fun, Love Tye
RE: The sad state of Perl documentation
by little (Curate) on Sep 15, 2000 at 16:29 UTC
open your eyes,
Perldoc as PDF 3.0 MB
currently covering Perl Version 5.005_02, so it's in general quite up to ones needs, and if you look further into the document info you will not by chance and not by surprise see that it's been made with pod2ps v1.0.1, which give's you and all of us the ability to convert whole directorys in one handstrike to a new PDF-manual.
So, if you want to help, mail to Andy Dougherty.
RE: The sad state of Perl documentation
by ScottSaddison (Initiate) on Sep 15, 2000 at 23:57 UTC
I am very happy with the documentation that comes with perl. It is an excellent format and reference for perl without the fluff. In fact, last week I began making standard POD templates for the documentation we use in my department.

One of the exceptional features of perldoc that sets it apart from the crowd is simplicity and integration. It's very nice to write in-line formatted documentation and be able to translate that into other formats (i.e. html). Granted, before that, our documentation structure consisted of a box of sand and a stick... but... you get the idea. I have not experienced any of the POD modules yet, but I'm sure they are just as intriguing.

Scott Saddison

in a perfect world, all the servers are UNIX.
RE: The sad state of Perl documentation
by odie (Sexton) on Sep 18, 2000 at 21:28 UTC
And opinions filled the room...
I may as well add a few things:

man / perldoc:
These are not intended (for the most part) to be a tutorial. If you want to learn, you buy a book, like with most other things. Perldoc is however an excellent reference manual. It's not very useful until you actually know perl. On the other hand, when you DO know perl, it is an excellent place to "look something up". The great advantage is that practically everyone installs perldoc along with perl. If you program perl, you always have perldoc. It is however , in my humble opinion, utterly useless when printed. The sections are HUGE and quite impossible to navigate without some form of search/matching. Furthermore, it is nice to know that perldoc is up to date. I do not consider this sad. As soon as you buy a book or print a reference manual, it will become old.

Postscript:
This is not only very common on UNIX platforms. It is also quite common on other systems such as Windows. Printers really like PostScript.
So, following some form of logical deduction, one might say that PostScript is a good format to store text in, if it is intended for printing. This causes no problems, as it can also be viewed with a variety of programs.
) However, following some form of illogical deduction, Windows does things a bit differently. It uses PS. A lot. There are however few programs that can display a simple PS file. Instead they have choosen to use every other format imaginable to store files, ready for printing. They use rtf, doc, pdf and and a variety off odd (and always commercial) formats. This strikes me as very odd. Having dozens of non-free formats that do the exact same thing is not a bright move. Even more so as the first thing that happens when you print it, is a conversion to PS, so the printer will understand it.

When I learned Perl there were no books about Perl. I learned by reading the documentation that came with Perl. I was quite happy with it.

Soon after that the first book about Perl came out and we all bought copies. I read it, enjoyed it, and thought it was a good book. I did learn a few things from reading the book but I think most of those I would have also learned from rereading the standard documentation.

Since then I've bought several books on Perl. Several of them are very good books. I've never finished reading any of them and I don't ever turn to them when I need to look something up.

When I need to look something up I read *.pod files, the source code to modules, the source code to Perl, try something (usually in the Perl debugger), or search the internet or some part of it.

So I think there are quite a few fine books that you could buy to help you learn Perl. But I don't think there is any need to buy a book.

There are certainly some parts of the standard Perl documentation that I believe could stand some major improvements. For example, I find the explanations on pack() and unpack() confusing and worse. But it isn't hard to submit patches to the documentation so I don't bitch much since it just means I haven't bothered to fix the problem. (:

- tye (but my friends call me "Tye")
RE: The sad state of Perl documentation
by footpad (Monsignor) on Sep 20, 2000 at 00:53 UTC

I wouldn't say perl is poorly documented, but that it, like many languages, relies heavily on some basic proficiency with the underlying OS and its rules.

What many Unix/Linux advocates seem to forget is that Windows has a different mindset, one that needs to be unlearned or discarded when dealing with *nix os's.

For example, I'm still pretty new to perl and had a project dropped in my lap. Write, in way too little time, a form-based emailer. Simple stuff for you folks, I'm sure, but since the lionshare of my development experience is with Windows languages, it wasn't something I felt entirely comfortable doing.

So I fired up several search engines, blundered around until I found some relevant material and managed to scrape something together. I did manage to meet the deadline, but I would never consider posting the code because it's flat out awful.

In finishing the project, I did run into several hurdles that would have been easier to solve had they been documented more clearly.

For example, you all know (I'm sure) that here documents are, by default, interpolated. Granted, it's not the best way to include a stylesheet, but I was against a time crunch. However, the stylesheet had external file references...

As another example, I didn't find clear examples of printing scalars with leading zeros or sending email attachments from mtulti-part forms until I heard about this site today. (If I'd only found the site a few months back...)

Each of these three behaviors took ~two days to puzzle out. I would have been far happier if I'd seen, very clearly in "Learning Perl," a warning about the interpolation issue. I did manage to figure it out using "Learning Perl" and "Programming with Perl," but it took a bit of page flipping.

You've all paid similar dues, I'm sure.

I have three main points:

1. If you write documentation, web articles, pod, or even answers to newsgroup/discussion messages, please take a moment to step back and review the technical overhead your information requires. I consider myself a literate, intelligent person, but half the man pages are too obscure for me. Yes, I can eventually puzzle them out, but I really don't have the time to invest. (I've got five projects due by the end of next month.) If you obfuscate behind a dizzying array of details, I get lost and annoy the heck out of my sysadmin..

At the very least, provide some cross-references for those of us who aren't as experienced as you are. (Remember when "man printf(3)" caused you errors?)

2. If you don't like the way one author has put it and you can't find one you like, then this is an opportunity for you to step up. For example, I am in the process of writing short web articles for a site I'm bringing online. Nothing that would appeal to you folks, I know, but it's stuff I ran into while learning the language, the rules, and the OS. You can do the same. There are several places where you can get free server space; use it.

3. If you provide links, web articles, or other online content, please review those from time to time. Some folks haven't touched their pages since '96. 'Nuff said.</P

Compared to other languages, perl is reasonably well documented. that's not to say there aren't areas where improvements could be made, but the docs are out there.

(P.S. In general, _please_ design your pages so they can be easily printed. Far too many sites clip content when printed.)
Re: The sad state of Perl documentation
by wazoox (Prior) on Jul 20, 2006 at 10:32 UTC
The complete Perl 5.8.8 documentation is available online at http://perldoc.perl.org/, and on the main page you may download both the HTML (with a very useful included javascript search engine) and the PDF version. ( http://perldoc.perl.org/perldoc.tar.gz). I don't think other languages are doing any better in this regard.

update: BTW if you want to learn Perl, there are very good docs available here : http://www.techbooksforfree.com/perlpython.shtml
"Extreme Perl" and "Learning Perl the hard way" are especially worth reading.

update: I don't disagree anymore :)

wazoox, please keep in mind that you're responding to a post which is almost 6 years old. That's a lot of water under the bridge.

We're building the house of the future together.
I'm afraid I forgot to look at the date, shame on me :)

Log In?
 Username: Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://32376]
Approved by root
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (12)
As of 2015-01-26 08:02 GMT
Sections?
Information?
Find Nodes?
Leftovers?
Voting Booth?