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:
That points you to using the '-f' option, with 'do' as argument. Running perldoc -f do gives me: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]
Now, perldoc could use improvement (patches welcome), but 'do' is not a good example of the uselessness of perldoc.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; } }
In reply to Re^2: Reorganizing or fixing Perl's documentation?
by Anonymous Monk
in thread Reorganizing or fixing Perl's documentation?
by BUU
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |