added note about whitespace control issues; update docs

diff --git a/bin/perltidy b/bin/perltidy
index 4c0a40974fbd6249b9ef5b8b3c352601d5b97d72..12d6a3f4abfd5fb6d85e3b2eac78d60cb3ea100c 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -1141,7 +1141,7 @@ and look at the .DEBUG file to see the tokenization.
 B<WARNING> Be sure to put these tokens in quotes to avoid having them
 misinterpreted by your command shell.
 
-=item Note: Perltidy does always follow whitespace controls 
+=item Note1: Perltidy does always follow whitespace controls 
 
 The various parameters controlling whitespace within a program are requests which perltidy follows as well as possible, but there are a number of situations where changing whitespace could change program behavior and is not done.  Some of these are obvious; for example, we should not remove the space between the two plus symbols in '$x+ +$y' to avoid creating a '++' operator. Some are more subtle and involve the whitespace around bareword symbols and locations of possible filehandles.  For example, consider the problem of formatting the following subroutine:
 
@@ -1161,6 +1161,25 @@ If formatted in this way, the program will not run (at least with recent version
 
 Related issues arise with other binary operator symbols, such as + and -, and in older versions of perl there could be problems with ternary operators.  So to avoid changing program behavior, perltidy has the simple rule that whitespace around possible filehandles is left unchanged.  Likewise, whitespace around barewords is left unchanged.  The reason is that if the barewords are defined in other modules, or in code that has not even been written yet, perltidy will not have seen their prototypes and must treat them cautiously.
 
+=item Note2: Perltidy's whitespace rules are not perfect
+
+Despite these precautions, it is still possible to introduce syntax errors with
+some asymmetric whitespace rules, particularly when call parameters are not
+placed in containg parens or braces.  For example, the following two lines will
+be parsed by perl without a syntax error:
+
+  # original programming, syntax ok
+  my @newkeys = map $_-$nrecs+@data, @oldkeys;
+
+  # perltidy default, syntax ok
+  my @newkeys = map $_ - $nrecs + @data, @oldkeys;
+
+But the following will give a syntax error:
+
+  # perltidy -nwrs='-'
+  my @newkeys = map $_ -$nrecs + @data, @oldkeys;
+
+
 =item Space between specific keywords and opening paren
 
 When an opening paren follows a Perl keyword, no space is introduced after the

diff --git a/docs/BugLog.html b/docs/BugLog.html
index 30b1a49d02f912db05838c52422a34c3a1295d0e..25494409e7bce28930fed48cb2512ab0e0ab4ca8 100644 (file)
--- a/docs/BugLog.html
+++ b/docs/BugLog.html
@@ -21,6 +21,12 @@
 
 <dl>
 
+<dt id="If-an-cut-starts-a-POD-section-within-code-give-a-warning"><b>If an =cut starts a POD section within code, give a warning</b></dt>
+<dd>
+
+<p>Previously only a complaint was given, which went into the log file and was not normally seen. Perl silently accepts this but it can cause significant problems with pod utilities, so a clear warning is better. This situation arose in testing on random files in combination with a -dp flag and it took some time to understand the results because of the lack of a warning.</p>
+
+</dd>
 <dt id="Switched-from-using-an-eval-block-to-the--can-function-for-sub-finish_formatting"><b>Switched from using an eval block to the -</b>can() function for sub finish_formatting&gt;</dt>
 <dd>
 

diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html
index ebd4ac6dceb59edab334de7c12f48a3acbb78611..247b8b18b8266a16290c9fc97fb63f3571911116 100644 (file)
--- a/docs/ChangeLog.html
+++ b/docs/ChangeLog.html
@@ -10,9 +10,13 @@
   opening container token of a multiple-line list.  Related new parameters -bbhbi=n, -bbsbi=n, -bbpi=n
   control indentation of these tokens.
 
+- Added keyword 'isa'.
+
 - Numerous issues have been found during automated testing and fixed. Many involve references to
   uninitialized variables when perltidy is given random text. A complete list is given in
-  the file 'BugLog.pod'.
+  the file 
+
+       https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
 </code></pre>
 
 <h2>2020 09 07</h2>

diff --git a/docs/perltidy.html b/docs/perltidy.html
index bc17a8b947fe41274b134f582a9402a8e6fc754e..f5887ec88438eeb384ef8a11054eb704ec8fd0de 100644 (file)
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -876,7 +876,7 @@
 <p><b>WARNING</b> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p>
 
 </dd>
-<dt id="Note:-Perltidy-does-always-follow-whitespace-controls">Note: Perltidy does always follow whitespace controls</dt>
+<dt id="Note1:-Perltidy-does-always-follow-whitespace-controls">Note1: Perltidy does always follow whitespace controls</dt>
 <dd>
 
 <p>The various parameters controlling whitespace within a program are requests which perltidy follows as well as possible, but there are a number of situations where changing whitespace could change program behavior and is not done. Some of these are obvious; for example, we should not remove the space between the two plus symbols in &#39;$x+ +$y&#39; to avoid creating a &#39;++&#39; operator. Some are more subtle and involve the whitespace around bareword symbols and locations of possible filehandles. For example, consider the problem of formatting the following subroutine:</p>
@@ -897,6 +897,23 @@
 
 <p>Related issues arise with other binary operator symbols, such as + and -, and in older versions of perl there could be problems with ternary operators. So to avoid changing program behavior, perltidy has the simple rule that whitespace around possible filehandles is left unchanged. Likewise, whitespace around barewords is left unchanged. The reason is that if the barewords are defined in other modules, or in code that has not even been written yet, perltidy will not have seen their prototypes and must treat them cautiously.</p>
 
+</dd>
+<dt id="Note2:-Perltidys-whitespace-rules-are-not-perfect">Note2: Perltidy&#39;s whitespace rules are not perfect</dt>
+<dd>
+
+<p>Despite these precautions, it is still possible to introduce syntax errors with some asymmetric whitespace rules, particularly when call parameters are not placed in containg parens or braces. For example, the following two lines will be parsed by perl without a syntax error:</p>
+
+<pre><code>  # original programming, syntax ok
+  my @newkeys = map $_-$nrecs+@data, @oldkeys;
+
+  # perltidy default, syntax ok
+  my @newkeys = map $_ - $nrecs + @data, @oldkeys;</code></pre>
+
+<p>But the following will give a syntax error:</p>
+
+<pre><code>  # perltidy -nwrs=&#39;-&#39;
+  my @newkeys = map $_ -$nrecs + @data, @oldkeys;</code></pre>
+
 </dd>
 <dt id="Space-between-specific-keywords-and-opening-paren">Space between specific keywords and opening paren</dt>
 <dd>