Reorganizing or fixing Perl's documentation?

Replies are listed 'Best First'.
Re: Reorganizing or fixing Perl's documentation? by geektron (Curate) on Dec 21, 2004 at 09:02 UTC
well, i've had a few ideas ... but nothing particularly immediately applicable. the strength i've seen with some of the PHP documentation is the ability to make associations between files/ modules. granted, it's just a special comment that's parsed, but it would be very helpful to be able to generate some of those programmatically. the other 'weakness' i can see ... is somewhat related. for better or worse, perl uses the nix mentality of building individual tools for individual jobs. the programmer is the one left to document the work (and rightfully so), but* many of the dependencies, called and calling functions, etc get embedded in the developer's head, and don't always make it out into the doc. while perldoc can be invaluable, for some it may be seen as and 'advanced topic'. i went looking for a 'cheat sheet' for POD commands a while back (when i asked a vaguely similar question) and was at a loss to find one. then i got sucked back into bug fixing, and never made the time to go back and find one.	[reply]
Re: Reorganizing or fixing Perl's documentation? by dragonchild (Archbishop) on Dec 21, 2004 at 14:02 UTC
Is my familiarity with Perl and it's documentation blinding me to obvious flaws? Yes. The best thing to do would be to take a look at the SOPW's and FAQ questions for the past three years¹. See what kind of questions keep popping up. There's a disturbing pattern of similar questions. Those questions are the ones the documentation isn't answering in a clear and easy-to-find manner. For one thing, I hate perldoc. With a passion. If I didn't have my 3rdCamel, I'd be up a creek. Plus, perldoc is almost never installed on systems that I didn't personally build. And, it depends so much on the terminal emulation - Exceed can screw up perldoc like nobody's business. The second is that more and more Perl programmers are purely Windows-based. There are several Saints who have almost never programmed on anything but Windows. Yet, why are all the examples Unix? Why isn't there a set of examples, FAQs, and the like for each major OS? I'm pretty sure VMS is a bit different ... Well, File::Spec sure says it is. So is OS-X vs. OS-9 vs. ... you get my point. The third thing is that terminology is tripping people up. A lot of questions I see in SOPW are ones where the answer often is `perldoc foo`. Then, the OP says "How was I supposed to know it was called 'foo'?!?". The true answer here is some sort of Google-like "Did you mean foobarbaz?" when doing some sort of search on this isn't right. In fact, it'd be really nice if Perldoc had a Google-powered search engine instead of the crappy one they currently have. And, I mean it's crappy!! I have done searches for Perl reserved words like, say ... do, and it's come back with everything but the manpage for do. What about searching for -X, which is how 3rdCamel calls the filetest operators? Nope, not gonna help you. And, you know what? I don't care about the differences between 5.6.0 and 5.9.1 ... I just want to find out what do's exact syntax options are! I know they haven't changed. Or, if they have, let me know in the manpage. You know who's got a really good manual? MySQL does, that's who. Check it out and see what I mean. It covers every single version in one document, with user comments². Some of those users are the developers. If there's a version dependency, it lets you know right there in the manual. Upgrade deltas are also covered, in the appendix. It's searchable and provides keywords first before anything else. And, it's easy to read - just like 3rdCamel. Why isn't our documentation like that? I'm sure there's a programmatic way to do this. These comments are a combination of wiki and blog-talkback. It's really neat. Being right, does not endow the right to be rude; politeness costs nothing. Being unknowing, is not the same as being stupid. Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence. Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.	[reply] [d/l]
Re^2: Reorganizing or fixing Perl's documentation? by Anonymous Monk on Dec 21, 2004 at 14:37 UTC
Yes. The best thing to do would be to take a look at the SOPW's and FAQ questions for the past three years. See what kind of questions keep popping up. There's a disturbing pattern of similar questions. Those questions are the ones the documentation isn't answering in a clear and easy-to-find manner. While I agree there's a lot to be improved about the readability (or rather searchability) of the documentation, the fact the same questions keep popping up doesn't prove the documentation isn't answering them in a clear and an easy-to-find manner. Many of those answers are found in the documentation, clearly written, and in an easy-to-find manner. And not only are they easy to find in the documentation, they are easy to find by doing a search here, doing a search on google groups, doing a websearch, or opening one of the many books written about Perl. People don't bother to read documentation (if you get a new gadget, first thing you do is press buttons, not read the manual). And it's not just Perl people, it happens everywhere. The second is that more and more Perl programmers are purely Windows-based. There are several Saints who have almost never programmed on anything but Windows. Yet, why are all the examples Unix? Perhaps because large portions of the documentation are written by people using Unix? Remember that all of the documentation is written by programmers. The initial phrasing of the words, and all updates and improvements are written by Perl programmers. Anyone can submit a patch to improve the documentation. If examples for Windows are missing, who is to blame? Unix people? Having said that, the bulk of Perl is supposed to work to same on each platform. And for the rest, differences are discussed in perlport.pod, which mostly discusses differences grouped by functionality, not by platform (which, IMO, is more useful). I just want to find out what do's exact syntax options are! I thought that was pretty easy with `perldoc`. Assuming you knew the utility is called `perldoc`, invoking it from the command line with no arguments: `Usage: perldoc [-h] [-V] [-r] [-i] [-v] [-t] [-u] [-m] [-n nroffer_pro +gram] [-l] [-T] [-d output_filename] [-o output_format] [-M Formatter +ModuleNameToUse] [-w formatter_option:option_value] [-F] [-X] PageNam +e\|ModuleName\|ProgramName perldoc -f PerlFunc perldoc -q FAQKeywords The -h option prints more help. Also try "perldoc perldoc" to get acquainted with the system. [Perldoc v3.13]` [download] That points you to using the '-f' option, with 'do' as argument. Running `perldoc -f do` gives me: do BLOCK Not really a function. Returns the value of the last command in the sequence of commands indicated by BLOCK. When modified by a loop modifier, exe- cutes the BLOCK once before testing the loop con- dition. (On other statements the loop modifiers test the conditional first.) "do BLOCK" does not count as a loop, so the loop control statements "next", "last", or "redo" can- not be used to leave or restart the block. See perlsyn for alternative strategies. do SUBROUTINE(LIST) A deprecated form of subroutine call. See perl- sub. do EXPR Uses the value of EXPR as a filename and executes the contents of the file as a Perl script. Its primary use is to include subroutines from a Perl subroutine library. do 'stat.pl'; is just like eval `cat stat.pl`; except that it's more efficient and concise, keeps track of the current filename for error messages, searches the @INC libraries, and updates %INC if the file is found. See "Predefined Names" in per- lvar for these variables. It also differs in that code evaluated with "do FILENAME" cannot see lexi- cals in the enclosing scope; "eval STRING" does. It's the same, however, in that it does reparse the file every time you call it, so you probably don't want to do this inside a loop. If "do" cannot read the file, it returns undef and sets $! to the error. If "do" can read the file but cannot compile it, it returns undef and sets an error message in $@. If the file is success- fully compiled, "do" returns the value of the last expression evaluated. Note that inclusion of library modules is better done with the "use" and "require" operators, which also do automatic error checking and raise an exception if there's a problem. You might like to use "do" to read in a program configuration file. Manual error checking can be done this way: # read in config files: system first, then user for $file ("/share/prog/defaults.rc", "$ENV{HOME}/.someprogrc") { unless ($return = do $file) { warn "couldn't parse $file: $@" if $@; warn "couldn't do $file: $!" unless defi +ned $return; warn "couldn't run $file" unless $ret +urn; } } [download] Now, perldoc could use improvement (patches welcome), but 'do' is not a good example of the uselessness of perldoc.	[reply] [d/l] [select]
Re^3: Reorganizing or fixing Perl's documentation? by dragonchild (Archbishop) on Dec 21, 2004 at 14:40 UTC
Now, perldoc could use improvement (patches welcome), but 'do' is not a good example of the uselessness of perldoc. No, but it's an example of the uselessness of perldoc.com's search functionality. (I thought I'd already explained I hate the 'perldoc' command ...) Being right, does not endow the right to be rude; politeness costs nothing. Being unknowing, is not the same as being stupid. Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence. Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.	[reply]
Re^3: Reorganizing or fixing Perl's documentation? by criglerj (Initiate) on Dec 23, 2004 at 18:41 UTC
It's even better when you get perldoc to pop up the changes in your editor. I have macros to do this in elvis and vim. I'll probably get around to doing so for vile when I go back there. Jim Crigler "In 1937, I began, like Lazarus, the impossible return." -- Whittaker Chambers	[reply]
Re^2: Reorganizing or fixing Perl's documentation? by Steve_p (Priest) on Dec 21, 2004 at 17:17 UTC
I've been working the perlbug queue for a while now, and the number of complaints on the Perl documentation has been very minimal. Most issues have been some slight nits, rewordings, and linking to other perldoc files for further examples. I have only found one case where code demonstrated in perldoc didn't work and one factual error in a FAQ (the FAQ claimed there was a Perl bug, when it was actually the underlying filesystem). Perl and its documentation is all open source. If you don't like the documentation or have found a problem, please provide a patch. If you'd like a commentable Perldoc.com alternative, please build it. Don't like the current command-line perldoc? Develop a new one. The Perl community is run by volunteers, not a corporation like MySQL AB. If you'd like something done, do it! By the way, the PODs for the current perl version are also all available at search.cpan.org. You can look up `do` in perlfunc.	[reply] [d/l]
Re^3: Reorganizing or fixing Perl's documentation? by dragonchild (Archbishop) on Dec 21, 2004 at 17:19 UTC
If you'd like a commentable Perldoc.com alternative, please build it. You willing to provide a host if I build the app and port over the current documentation? Being right, does not endow the right to be rude; politeness costs nothing. Being unknowing, is not the same as being stupid. Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence. Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.	[reply]
Re^4: Reorganizing or fixing Perl's documentation? by BUU (Prior) on Dec 21, 2004 at 18:48 UTC
Re^5: Reorganizing or fixing Perl's documentation? by dragonchild (Archbishop) on Dec 21, 2004 at 18:48 UTC
Some notes below your chosen depth have not been shown here
Re^4: Reorganizing or fixing Perl's documentation? by itub (Priest) on Dec 21, 2004 at 18:39 UTC
Re^2: Reorganizing or fixing Perl's documentation? by Mutant (Priest) on Dec 21, 2004 at 16:06 UTC
In fact, it'd be really nice if Perldoc had a Google-powered search engine instead of the crappy one they currently have. And, I mean it's crappy!! Worse than that, about 90% of the time I can't even access the site. I usually end up using docs from PM if I need them, or if I can't find something quickly, I'll use the perldoc commandline... but honestly, is this 1980? Surely we're in the age of the GUI, and the sub-age of the website. I want online docs! I think the main problem with perl documentation is that it just doesn't have an overall structure. People seem to have written stuff, found a place for it and not really cared if no one would be able to find it. Hopefully the mythical Perl6 can solve all our problems :)	[reply]
Re: Reorganizing or fixing Perl's documentation? by Anonymous Monk on Dec 21, 2004 at 13:56 UTC
The biggest complaint I've heard over the years is that the documentation is hard to search. Almost everything is documented, but it's not always easy to find - and sometimes it feels things are documented in illogical places. Scoping for instances, with many details about my() and local() is documented in "perlsub" - which is about subroutines (and this unfortunate marriage of scoping and subroutines has been carried into too many Perl learning books). Furthermore, those who have written significant portions of the documentation have always shied away from copying sections into other relevant PODs. Which means there are a lot of cross-references. Unfortunally, there are even more cross-references missing. There is no index at all, unless you count the list of manual pages from 'man perl'. But that list is incomplete - it only lists the PODs from the /pod/ subdirectory, not the POD that comes with the core modules. Crossreferencing from the core PODs into the core module PODs is almost non-existing. The documentation is overwhelming. At the same moment, it's often terse, and sometimes requires UNIX and/or C knowledge. But it's easy to critisize. Many have done so. Not so many have actually tried to fix the situation. Noone has actually managed to write better documentation. If I were to fix something, I'd first create an index, and the framework to keep the index up to date. BTW, I strongly disagree with the suggested directory structure in the piece you quote. Either you subdivide the documentation on topics, or you subdivide them on their presentation. But you don't put both subdivisions on the same level. Where would I go looking for a tutorial about internals? In the "Tutorials" directory, or in the "Internals" directory?	[reply]
Re: Reorganizing or fixing Perl's documentation? by CloneArmyCommander (Friar) on Dec 22, 2004 at 19:36 UTC
I always found the documentation to be useful. When I first started learning perl, the man pages were the first place I looked, and I felt it did an excellent job, but that is my personal opinion (everything I do is a big jumble anyway ;). I was always able to find what I need through perltoc and pressing "/" and putting in a nice search term and it always returns what I am looking for. I have found if you can not find the answers right away, just grep for them :). I am pleased to find the perldoc website, I did not know it existed. I was pleased by its format, and after a few seconds of looking around I was able to find what I need (although that might be because I am used to the man pages :). I think all of the others will agree that this is a project that is worth all of our effort to try to make more comprehensive to newcomers of perl.	[reply]
Re: Reorganizing or fixing Perl's documentation? by artist (Parson) on Dec 22, 2004 at 02:44 UTC
For me, accessibility is a good issue. Best use of perldoc is done if we put it on Perlmonks. Have the perldoc-box at the top of every page and have the queries directed to perldoc.com. It might be argued that perldoc is right on your machine, but I guess that google has proved the case.	[reply]
Re: Reorganizing or fixing Perl's documentation? by enoch (Chaplain) on Dec 22, 2004 at 18:48 UTC
I had some simple usability ideas on this once.	[reply]
Re^2: Reorganizing or fixing Perl's documentation? by BUU (Prior) on Dec 22, 2004 at 19:38 UTC
Your one idea will probably get implemented. It's trivial after all. I don't see the usefulness but since a couple of people have added it, it will probably get done.	[reply]


Syntactic Confectionery Delight
	PerlMonks