Update docs for git #64 regarding -lp and side comments

diff --git a/bin/perltidy b/bin/perltidy
index 2a48c85f1e704374a7fd6517a80c38c13cccad0c..6b0eee2423a1f00266909992c88d299b02566d32 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -827,13 +827,12 @@ space, perltidy will use less.   For alternate placement of the
 closing paren, see the next section.
 
 This option has no effect on code BLOCKS, such as if/then/else blocks,
-which always use whatever is specified with B<-i=n>.  Also, the
-existence of line breaks and/or block comments between the opening and
-closing parens may cause perltidy to temporarily revert to its default
-method.
+which always use whatever is specified with B<-i=n>.
 
-Note: The B<-lp> option may not be used together with the B<-t> tabs option.
-It may, however, be used with the B<-et=n> tab method.
+In situations where perltidy does not have complete freedom to choose line
+breaks it may temporarily revert to its default indentation method.  This can
+occur for example if there are blank lines, block comments, multi-line quotes,
+or side comments between the opening and closing parens, braces, or brackets.
 
 In addition, any parameter which significantly restricts the ability of
 perltidy to choose newlines will conflict with B<-lp> and will cause
@@ -842,6 +841,10 @@ B<-ndnl>.  The reason is that the B<-lp> indentation style can require
 the careful coordination of an arbitrary number of break points in
 hierarchical lists, and these flags may prevent that.
 
+The B<-lp> option may not be used together with the B<-t> tabs option.
+It may, however, be used with the B<-et=n> tab method.
+
+
 =item B<-lpxl=s>,  B<--line-up-parentheses-exclusion-list>
 
 This is an experimental parameter; the details might change as experience

diff --git a/local-docs/BugLog.pod b/local-docs/BugLog.pod
index 43e908bf3accdd7c7ce22b438672c9a142ec7458..9ff48eb44545a1c4c7e95347ae0892e0029963f8 100644 (file)
--- a/local-docs/BugLog.pod
+++ b/local-docs/BugLog.pod
@@ -2,6 +2,32 @@
 
 =over 4
 
+=item B<Update docs for git #64 regarding -lp and side comments>
+
+The wording regarding when -lp reverts to the default indentation scheme
+has been revised to include side comment as follows:
+
+In situations where perltidy does not have complete freedom to choose line
+breaks it may temporarily revert to its default indentation method.  This can
+occur for example if there are blank lines, block comments, multi-line quotes,
+or side comments between the opening and closing parens, braces, or brackets.
+
+The word 'may' is significant for side comments.  In a list which is just one
+level deep side comments will work (perhaps with -iscl if side comments are
+long).  For example this is ok
+
+    # perltidy -lp
+    $gif->arc(
+               50, 50,     # Center x, y.
+               30, 30,     # Width, Height.
+               0,  360,    # Start Angle, End Angle.
+               $red
+    );
+
+But if a list is more than one level deep then the default indentation is used.
+
+28 Apr 2021.
+
 =item B<Fix line break rules for uncontained commas + cleanups>
 
 This is an adjustment of update 344519e which had to do with breaking lines