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]
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;
}
}
Now, perldoc could use improvement (patches welcome), but 'do' is not a good example of the uselessness of perldoc. | [reply]
[d/l]
[select] |
| [reply] |
| [reply] |
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] |
| [reply] |
I've been working on plans for a "better perldoc" for a while now, so if you're going to work something I'd appreciate being contacted, so at least we can not duplicate mistakes. I've also got, at least for a while, a dedicated server I can use to host it.
| [reply] |
I've been secretly building a "commentable Perl documentation web app", which I call AnnoCPAN (for Annotated CPAN). There are still some issues but it already works as a proof of concept. The problem is the hosting; I've been thinking I'll have to pay for a relatively inexpensive host so that I can at least show it to the world; I hope that if it is successful perhaps it could be possible to get some donations or a sponsor to get decent hosting.
| [reply] |
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] |