update docs

diff --git a/bin/perltidy b/bin/perltidy
index b8b51e256126f00138dabc7eec5e513a5f7d970b..b8778fbff91c5bbf76aba0351706f8fe1b242d1b 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -5539,22 +5539,22 @@ of the letters, B<r>, B<s>, B<p>, and B<u> as follows:
 =item B<r: reused variable name>
 
 These are variables which are re-declared in the scope of a variable with the
-identical name.  This can be confusing and lead to errors being introduced
-in future program modifications.
+identical name.  This can be confusing.  This is similar to the B<Perl::Critic>
+policy B<Variables::ProhibitReusedNames>
 
 =item B<s: sigil change but reused bareword>
 
 These are variables which have the same bareword name but a different sigil
 (B<$>, B<@>, or B<%>) as another variable in the same scope.  For example, this
 occurs if variables B<$data> and B<%data> share the same scope. This can be
-confusing and can be avoided by altering one of the variable names.
+confusing.
 
 =item B<p: package-crossing variables>
 
 These are lexical variables which are declared in one package and still visible
-in subroutines of a different package in the same file.  This can only occur if
-there are multiple packages in a file. It might be avoided by enclosing such
-variables in a bare block to limit their scope.
+in subroutines of a different package in the same file.  This check is limited
+to packages which are not enclosed in block braces in order skip some common
+use cases.
 
 =item B<u: unused variables>
 
@@ -5582,17 +5582,18 @@ will process F<somefile.pl> normally but issue a warning if either of
 the issues 's' or 'p', described above, are encountered.
 
 A limitation is that warnings may not be requested for unused variables, type
-'u'. The reason is that this would produce many needless warnings, especially
-when perltidy is run on small snippets of code from within an editor.
+'u'. The main reason is that this would produce many needless warnings,
+especially when perltidy is run on small snippets of code from within an
+editor.
 
-All possible variable warnings may be requested with B<-wv=rsp> or simply
+All possible variable warnings may be requested with B<-wvt=rsp> or simply
 B<-wvt=1> or B<-wvt='*'>.  The default is not to do these checks, and it can
 also be indicated with B<-wvt=0>.
 
 A companion flag, B<--warn-variable-exclusion-list=string>, or B<-wvxl=string>,
 can be used to skip warning checks for a list of variables.  For example,
 
-   perltidy -wv=1 -wvxl='$self $class'  somefile.pl
+   perltidy -wvt=1 -wvxl='$self $class'  somefile.pl
 
 will skip all warnings for variables C<$self> and C<$class>.
 

diff --git a/local-docs/tutorial.pod b/local-docs/tutorial.pod
index c5297a3b5761f52ecda2e6c8e72dc1f0065b376f..b8c89a18ef77b49d474ddb6534e0bb57b38a4ad9 100644 (file)
--- a/local-docs/tutorial.pod
+++ b/local-docs/tutorial.pod
@@ -395,39 +395,6 @@ this line:
 
 This kind of error can otherwise be hard to find.
 
-=head2 The Log File
-
-One last topic that needs to be touched upon concerns the F<.LOG> file.
-This is where perltidy records messages that are not normally of any
-interest, but which just might occasionally be useful.  This file is not
-saved, though, unless perltidy detects that it has made a mistake or you
-ask for it to be saved.
-
-There are a couple of ways to ask perltidy to save a log file.  To
-create a relatively sparse log file, use
-
- perltidy -log testfile.pl
-
-and for a verbose log file, use
-
- perltidy -g testfile.pl
-
-The difference is that the first form only saves detailed information at
-least every 50th line, while the second form saves detailed information
-about every line.
-
-So returning to our example, lets force perltidy to save a
-verbose log file by issuing the following command
-
- perltidy -g testfile.pl
-
-You will find that a file named F<testfile.pl.LOG> has been
-created in your directory.  
-
-If you open this file, you will see that it is a text file with a
-combination of warning messages and informative messages.  All you need
-to know for now is that it exists; someday it may be useful.
-
 =head2 Using Perltidy as a Filter on Selected Text from an Editor
 
 Most programmer's editors allow a selected group of lines to be passed
@@ -484,6 +451,27 @@ the bottom (or even midstream!).  You probably cannot control this, and
 perltidy can't, but you need to know where to look when an actual error
 is detected.
 
+=head2 Finding Unused Variables
+
+To get a list of unused, reused, and certain other lexical variables of
+interest in a program named F<testfile.pl> you can use
+
+ perltidy -duv testfile.pl
+
+where -duv is short for --dump-unusual-variables. The information will be
+dumped to the standard output and perltidy will exit without formatting the
+file.  The lines of output identify four types of issues, namely
+
+   u: unused variables
+   r: reused variable name in same scope
+   s: sigil change but reused bareword, such as %file and $file
+   p: package-crossing variables: a variable with scope in multiple packages
+
+These issues, although not errors, can be worth reviewing, especially for new
+code.  Other parameters which can be useful when reviewing code are
+B<--warn-missing-else> and B<--dump-block-summary>.  The manual has further
+information.
+
 =head2 Writing an HTML File
 
 Perltidy can switch between two different output modes.  We have been