All the Perl that's Practical to Extract and Report

Its not kept behind the scullery maid under an aarvark

redspike on 2010-02-06T22:52:51

How to learn how to get help in Perl

I made a great discovery today but it has taken me a few years to get to it. I have wondered why it has been so hard to get into the shiny ball that surrounds some of the programming languages. This is not just Perl but many of them. I started to compare the way I learn text editors with the way I have learned programming languages. Vi was the first real editor I decided to learn.

  1. Started it at the command line
  2. Wondered how the hell I opened a file
  3. Wondered how the hell I closed a file
  4. Wondered how the hell I edited it
  5. Wondered what all the fuss was about
  6. I then bought a book and read it
  7. Understood somethings and not others
  8. Discovered how powerful it was and realised what all the fuss was about
  9. Flirted with the idea of using it all the time
  10. Found I could use it to do something I needed to do
  11. Discovered how to use the help files
  12. Understood what to do with a file and to do something useful that I could do however small
  13. Used it infrequently when I had to during an ssh session on a server or just played with it
  14. One day decided to use it all the time and be damned
  15. It took a bit of working out and the first project I did with it took at least twice as long as normal
  16. Now I use it all the time except when I am using Emacs in fact I cannot imagine life without it

So what is the difference with programming? Well I thought there would not be too much after all people have said 'if you can use Vi you can program'. So here we go with Perl.

  1. Started it at the command line
  2. Wondered how the hell I created a variable
  3. Wondered what the hell I did with a variable once I had one
  4. Wondered how the hell made anything do anything to do anything
  5. Wondered what all the fuss was about
  6. I then bought a book and read it
  7. Understood somethings and not others
  8. Discovered how powerful it was and realised what all the fuss was about
  9. Flirted with the idea of using it all the time
  10. Found I could use it to do something I needed to do
  11. Null
  12. Null
  13. Used it for a few scripts which help with some very basic cgi stuff
  14. Would liked to have used it for lots of things but could not work out how
  15. Became frustrated because it seemed like a shiney ball that I could not get into
  16. I do not use it every day to do stuff

The big difference which is glaringly obvious now, but I had not seen before is the help system and understanding something I could do that was useful.

I came to this conclusion from the other end of the stick by trying to see where I was falling down and why I could not dash a script off when I needed to do something. I knew that if I was to use it to achieve the programming goals I needed to use it frequently to be able to progress onto larger programs that I have in mind.

It came to the fact that I could not remember things sometimes. I related this to my Vi experience and realised that I had had the same sort of problem but that had not stopped me from using it everyday. The difference was that it was so hard to get help from the help system. In fact I had been using the web for quick howtos and stuff had made it harder as it was a second hand help system in a way, it was not from the guts if you like.

I was walking around the office talking to myself and gesticulating a pieces of paper and trying to see how I could get the kind of help from Perl than I did from :h in Vi.

Of course its perldoc and man perlmodlib. I had played around with it but at no point had any book walked me through the way to use it. I sort of bumbled through and got by the best I could by using books and search engines. While learning any program like vi, emacs or Open Office the help files are there and most are accessible from a help menu or command. Books are bought and read and understood and exercises accomplished. When I forget something I can look it up in the help files, I do it without thinking. So once you learn one program and read some books, you know that there will be a help system to hold your hand when you need it. The book is part of the help system in a way but it is never implied it is just there and assumed that it will be used.

Switching to learning a programming language the same is not true there is not a system called help. In Java there are loads of documentation and tons of libraries of classes to wade through. In Perl there is perdoc. These two are alluded to but not really explained. You get instructions like 'There are thousands of libraries to get to do all the things you want to do without writing code' or 'There is always perldoc to help you out and thousands of modules'. Similar direction are found in program books referring to the help system, but everyone knows about help systems its there in the culture of using a program.

Once I looked at the similarities and differences in learning programming and learning a program and treated them the same it dawned on me that you all out there must be able to find stuff in perldoc that I am missing. So I knew I had to find a way to get what I wanted to know out of the Perl Help System. I looked on the net and looked in books for the bit that I was missing. I got to perldoc but it did not tell me everything. I askerd on IRC where was the list of stuff on Perl that is on the perldoc website and I got the answer. Perldoc perl or perldoc perltoc. WHY IS IT NOT THE FIRST CHAPTER IN ANY PROGRAMMING BOOK OR ON THE FIRST PAGE OF A WEBSITE THAT EXPLAINS HOW TO FIND OUT WHAT YOU WANT TO KNOW? I found it but it has taken me ages to find it. I new it was there but did not know how to access it. If there are books out there that do explain this then I am sorry that I have not read it or perhaps I missed that chapter.

'man perlmodlib' to see what the core modules are

'perldoc -f insert-function-name'

'perldoc perl' for a summary list of functions, other perldoc pages and loads of other stuff. Decide what you want to look up and type perldoc perlref for stuff on perl references - easy huh

'perldoc perltoc' for a an in depth look at everything in Perl

This is the entrance to Perl, not the back door to be found behind the scullery maid under an aardvark when every other avenue has been exhausted

Given this revelation on how to find what I wanted to find I took up the editor of choice and started a very simple script. when I got to something that did not compile and I could not figure out why it wouldn't, I could, with confidence go to the 'help system' and find the right syntax etc.

It then smacked me in the face, I may be wrong but there does not seem to be the same thing in any other system, it may be close but not the same. So why wasn't the 'perldoc how to program like you a have never programmed before even if you have never programmed' message out there. A healthy language needs new recruits and helping them find what and how they can achieve what they want to do is paramount in keeping those new recruits and keeping the language alive. Maybe it is presumed that programmers who are familiar with such things will always read programming books/articles/blogs. Well nobody is born with innate knowledge of a system, they have to learn it and the first thing is to learn how to get help. To a complete novice it is the most important thing to be able to help themselves to help themselves.

Perldoc is not documentation, yes I know they are documents, it is the help system, and it is there on your machine tailored to the version installed on your machine. It is easy to access anywhere where there is Perl installed - your friend in a box. How cool is that?

If you are saying what I think you are saying ...

thickas on 2010-02-07T02:26:09

I agree

I have many, perhaps more than half, of the reputable published Perl books (eg bought all 3 editions of the Camel book) but I don't think I recall any _except_ perhaps 'Perl debugged' & 1st ed of 'Effective Perl', emphasising the usefulness of the Perldoc.

Perldoc is far more helpful to me than the out of band read-this-library of material that I see in Java and other epesh OO languages.

Maybe Padre has the help button that a novice would be consoled by seeing.

Can't RTFM if you can't FTFM

dagolden on 2010-02-11T03:48:21

I have sympathy for your experience. Fortunately, I think the redesigned perl.org makes it much easier now to find documentation, including explaining perldoc.

But to make it even easier, I just committed a patch to the Perl core that adds a note to "perl -h" about running "perldoc perl" for more help.

In perldoc perl (the same thing you'd get from "man perl"), it now mentions perldoc right away, advises users to see perldoc perlintro if they are new to Perl, and points users to perl.org for online resources.

So, come Perl 5.12, if someone can't find the manual, the problem will be behind the keyboard.

-- dagolden

Re:Can't RTFM if you can't FTFM

redspike on 2010-02-11T23:02:46

Thanks dagolden its good to be read and heard. Its also a nice quote.