switched docs from html to markdown, minor formatting tweaks

MANIFEST.SKIP

@@ -86,6 +86,9 @@
 # Github files
 \.travis\.yml
 
+# Jekyl file
+_config.yml
+
 # tidyall files
 \.tidyall
 
@@ -126,8 +129,5 @@
 
 ^local-docs/
 
-# this is reserved for html pages
-^docs/
-
 ^archive/
 

README.md

@@ -1,57 +1,12 @@
-# Welcome to Perltidy!
+# Welcome to Perltidy
 
 Perltidy is a tool to indent and reformat perl scripts.  It can also
 write scripts in html format.
 
 Perltidy is free software released under the GNU General Public
 License -- please see the included file "COPYING" for details.
 
-# PREREQUISITES
+Documentation can be found at the web site [at GitHub](https://perltidy.github.io/perltidy/) 
+or [at Sourceforge](perltidy.sourceforge.net)
 
-`perltidy` should work with most standard Perl installations.
-The following modules are not required, but perltidy may use them if
-detected:
-
-    HTML::Entities  will be used to encode HTML entities if detected
-    Pod::Html will be used to format pod text
-
-The total disk space needed after removing the installation directory will
-about 2 Mb.  
-
-# DOWNLOAD
-
-There are two source distribution files:
-
-- A `.tgz` "tarball", with Unix-style <lf> line endings, and 
-- A zip file, `.zip`, with Windows-style <cr><lf> line endings.
-
-In addition, the web site has links to debian and RPM packages.
-
-# INSTALLATION
-
-For most standard installations, the standard Makefile.PL method should work:
-
-    perl Makefile.PL
-    make
-    make test
-    make install
-
-The INSTALL file has additional installation notes, and tells how
-to use perltidy without doing an installation.
-
-# WHAT NEXT
-
-Please see the CHANGES file for notices of any recent updates.
-
-Please see the BUGS file for a list of all known open bugs.
-
-Documentation can be found in the `docs` directory, and it can also be 
-found at http://perltidy.sourceforge.net
-
-Reading the brief tutorial should help you use perltidy effectively.  
-
-# FEEDBACK / BUG REPORTS
-
-A list of current bugs and issues can be found at the CPAN site [https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy](https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy)
-
-To report a new bug or problem, use the link on this page .  
+A copy of the web site in contained in the docs folder of the distribution.

docs/BUGS.md

@@ -0,0 +1,45 @@
+# 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.
+
+This file only lists open bugs.  For bugs which have been fixed, 
+see the ChangeLog.  
+
+## 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.
+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.
+
+## 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