X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=BUGS;h=d43b28e19677075997b148affa7bc4ab2362c299;hb=736e5d55044509ce0deaaf0e7299a98f4d4b8d15;hp=f43ea14b37a3dc0cfaa0b95b658ada20526522fd;hpb=5c180637bf79ffc2af10f6654d308ce39e2f1f67;p=perltidy.git

diff --git a/BUGS b/BUGS
index f43ea14..d43b28e 100644
--- a/BUGS
+++ b/BUGS
@@ -1,4 +1,4 @@
-Perltidy open BUGS
+Perltidy open BUGS and LIMITATIONS
     You can help perltidy evolve into a better program. If you think you
     have hit a bug or weird behavior, or have a suggested improvement,
     please send a note to perltidy at users.sourceforge.net.
@@ -6,26 +6,40 @@ Perltidy open BUGS
     This file only lists open bugs. For bugs which have been fixed, see the
     ChangeLog.
 
-  The --extrude option can produce code with syntax errors
+  The --extrude and --mangle options can produce code with syntax errors
     The --extrude tries to put as many newlines in the formatted code as
-    possible. This option is very useful for testing perltidy but not for
-    actual formatting. Occasionally it will produce code which Perl
-    considers to have a syntax error. These problems usually involve code
-    where Perl is having to guess the tokenization based on whitespace.
-    Since the --extrude option is typically only used for testing perltidy,
-    this type of error should not normally occur in practice.
-
-  In some rare instances the formatting can oscillate between two states
-    The following example was sent by Denis Moskowitz, Oct 29 2010:
-
-    grep { $_->foo ne 'bar' } # asdfa asdf asdf asdf asdf asdf asdf asdf
-    asdf asdf asdf @baz;
-
-    With standard parameters this oscillates between the above and:
-
-    grep { $_->foo ne 'bar' } # asdfa asdf asdf asdf asdf asdf asdf asdf
-    asdf asdf asdf @baz;
-
-    A workaround here would be to make a slight change to the side comment
-    length.
+    possible. The --mangle tries to remove as many newlines as possible.
+    These options are very useful for stress testing perltidy (and Perl) but
+    not so much for normal formatting. Occasionally they will produce code
+    which Perl considers to have a syntax error. These problems often
+    involve code where Perl is having to guess the tokenization based on
+    whitespace. The given/when and switch/case statements are also
+    particularly vulnerable to unusual line breaks and whitespace. This type
+    of error should not normally occur in practice, but if it does it should
+    be easy to fix the problem by rerunning perltidy with more normal
+    parameters or by manually changing whitespace or newlines.
+
+  The Pod:Html module has some bugs
+    For the most part Pod::Html works very well and is very convenient
+    because it part of the standard Perl distribution. But for example the
+    following line
+
+      =item B<< <Deck> = Session->new_cflt_deck; >>
+
+    which uses double brackets to contain single brackets does not render
+    correctly.
+
+  Perltidy does not handle UTF-8 encoded files
+  Two iterations are sometimes needed
+    Usually the code produced by perltidy on the first pass does not change
+    if it is run again, but sometimes a second pass will produce some small
+    additional change. This mainly happens if a major style change is made,
+    particularly when perltidy is untangling complex ternary statements. Use
+    the iteration parameter -it=2 if it is important that the results be
+    unchanged on subsequent passes, but note that this doubles the run time.
+
+  Latest Bug and Wishlist at CPAN:
+    For the latest list of bugs and feature requests at CPAN see:
+
+    https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy