update debian/watch for cpan location instead of sourceforge

[perltidy.git] / BUGS

diff --git a/BUGS b/BUGS
index f43ea14b37a3dc0cfaa0b95b658ada20526522fd..d43b28e19677075997b148affa7bc4ab2362c299 100644 (file)
--- 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.
     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.
 
     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
     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