update docs

diff --git a/bin/perltidy b/bin/perltidy
index 99592ce589ff20f1dd8cd6e159d643f103dbcbfd..ea43412317572ab36dba0326c453244b2e0666ac 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -5526,9 +5526,9 @@ 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 might indicate
-an error.
+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.
 
 =item B<s: sigil change but reused bareword>
 
@@ -5540,17 +5540,19 @@ confusing and can be avoided by altering one of the variable names.
 =item B<p: package-crossing variables>
 
 These are lexical variables which are declared in one package and still visible
-in a later package with subroutines in the same file.  This only occurs if
+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.
 
 =item B<u: unused variables>
 
-These are variables which are declared but not used. There are many good
-reasons for having unused variables, but sometimes they can occur due to being
-orphaned by a coding change, due to a misspelling, or by having an
-unintentional preceding C<my>.  So it is worth checking them, especially for
-new code.
+These are variables which are declared but not used. There are many reasons for
+having unused variables.  For example, they can occur in lists of values
+provided by another routine or data structure but which are not needed, or they
+might be defined for possible future program development, clarity or debugging.
+But sometimes they can occur due to being orphaned by a coding change, due to a
+misspelling, or by having an unintentional preceding C<my>.  So it is worth
+checking them, especially for new code.
 
 =back
 
@@ -5572,7 +5574,8 @@ A limitation is that warnings may not be requested for unused variables, type
 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
-B<-wv=1> or B<-wv='*'>.
+B<-wv=1> or B<-wv='*'>.  The default is not to do these checks, and it can
+also be indicated with B<-wv=0>.
 
 A companion flag, B<--want-variables-exclusion-list=string>, or B<-wvxl=string>,
 can be used to skip warning checks for a list of variables.  For example,