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.