From 9429aca84ade66a412116e045bdc8f2218b6d765 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Sun, 29 May 2022 15:46:45 -0700 Subject: [PATCH] update docs --- CHANGES.md | 29 ++++++++++++++++------------- docs/ChangeLog.html | 29 ++++++++++++++++------------- docs/Tidy.html | 10 ++++------ docs/perltidy.html | 10 +++++----- 4 files changed, 41 insertions(+), 37 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 2214c328..9307ef2a 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,17 +2,23 @@ ## 2022 06 01 - - The flag --encode-output-strings, or -eos, is now set on by default, as - noted in the discussion of issue git #92. This has no effect on the use - of the 'perltidy' binary but could change the behavior of programs which - use the Perl::Tidy module on files encoded in UTF-8. If any problems are - noticed, an emergency fix can be made by reverting to the old default with - the flag -neos. For complete details see: + - Please note the following two significant changes in this distribution: - https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md + - The flag --encode-output-strings, or -eos, is now set 'on' by default. + This has no effect on the use of the 'perltidy' binary script, but could + change the behavior of some programs which use the Perl::Tidy module on + files encoded in UTF-8. If any problems are noticed, an emergency fix + can be made by reverting to the old default by setting -neos. For + an explanation of why this change needs to be made see: - - Add vertical alignment for qw quotes in 'use' statements (see issue #git 93). - This is on by default but can be turned off with -vxl='q': + https://github.com/perltidy/perltidy/issues/92 + + https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md + + - Add vertical alignment for qw quotes and empty parens in 'use' + statements (see issue #git 93). This new alignment is 'on' by default + and will change formatting as shown below. If this is not wanted it can + be turned off with the parameter -vxl='q' (--valign-exclude-list='q'). # old default or -vxl='q' use Getopt::Long qw(GetOptions); @@ -29,7 +35,7 @@ - Previously, if a -dsc command was used to delete all side comments, then any special control comments for non-indenting braces got deleted too. Now, these control side comments are retained when -dsc is set unless - a -nnib flag is also set to deactivate them. + a -nnib (--nonon-indenting-braces) flag is also set to deactivate them. - This version runs 15 to 20 percent faster on large files than the previous release due to optimizations made with the help of Devel::NYTProf. @@ -38,9 +44,6 @@ random input parameters. No failures to converge, internal fault checks, undefined variable references or other irregularities were seen. - - Fixed and reactivated two failing installation tests (they were reading - a local .perltidyrc file) - ## 2022 02 17 diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html index c458f530..09e14393 100644 --- a/docs/ChangeLog.html +++ b/docs/ChangeLog.html @@ -2,17 +2,23 @@

2022 06 01

-
- The flag --encode-output-strings, or -eos, is now set on by default, as
-  noted in the discussion of issue git #92.  This has no effect on the use
-  of the 'perltidy' binary but could change the behavior of programs which
-  use the Perl::Tidy module on files encoded in UTF-8.  If any problems are
-  noticed, an emergency fix can be made by reverting to the old default with
-  the flag -neos.  For complete details see:
+
- Please note the following two significant changes in this distribution:
 
-       https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md
+- The flag --encode-output-strings, or -eos, is now set 'on' by default.
+  This has no effect on the use of the 'perltidy' binary script, but could
+  change the behavior of some programs which use the Perl::Tidy module on
+  files encoded in UTF-8.  If any problems are noticed, an emergency fix
+  can be made by reverting to the old default by setting -neos.  For
+  an explanation of why this change needs to be made see:
 
-- Add vertical alignment for qw quotes in 'use' statements (see issue #git 93).
-  This is on by default but can be turned off with -vxl='q':
+  https://github.com/perltidy/perltidy/issues/92
+
+  https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md
+
+- Add vertical alignment for qw quotes and empty parens in 'use'
+  statements (see issue #git 93).  This new alignment is 'on' by default
+  and will change formatting as shown below. If this is not wanted it can
+  be turned off with the parameter -vxl='q' (--valign-exclude-list='q').
 
     # old default or -vxl='q'
     use Getopt::Long qw(GetOptions);
@@ -29,7 +35,7 @@
 - Previously, if a -dsc command was used to delete all side comments,
   then any special control comments for non-indenting braces got deleted too.
   Now, these control side comments are retained when -dsc is set unless
-  a -nnib flag is also set to deactivate them.
+  a -nnib (--nonon-indenting-braces) flag is also set to deactivate them.
 
 - This version runs 15 to 20 percent faster on large files than the
   previous release due to optimizations made with the help of Devel::NYTProf.
@@ -37,9 +43,6 @@
 - This version of perltidy was stress-tested for many cpu hours with
   random input parameters. No failures to converge, internal fault checks,
   undefined variable references or other irregularities were seen.
-
-- Fixed and reactivated two failing installation tests (they were reading
-  a local .perltidyrc file)
 

 
 
2022 02 17

diff --git a/docs/Tidy.html b/docs/Tidy.html
index 96e326f8..afe49e59 100644
--- a/docs/Tidy.html
+++ b/docs/Tidy.html
@@ -383,13 +383,13 @@
 
 
In the present example, we are only looking for tokens of type i (identifiers), so the for loop skips past all other types. When an identifier is found, its actual text is checked to see if it is one being sought. If so, the above write_line prints the token and its line number.

 
-
The formatter feature is relatively new in perltidy, and further documentation needs to be written to complete its description. However, several example programs have been written and can be found in the examples section of the source distribution. Probably the best way to get started is to find one of the examples which most closely matches your application and start modifying it.

+
The examples section of the source distribution has some examples of programs which use the formatter option.

 
 
For help with perltidy's peculiar way of breaking lines into tokens, you might run, from the command line,

 
 
 perltidy -D filename

 
-
where filename is a short script of interest. This will produce filename.DEBUG with interleaved lines of text and their token types. The -D flag has been in perltidy from the beginning for this purpose. If you want to see the code which creates this file, it is write_debug_entry in Tidy.pm.

+
where filename is a short script of interest. This will produce filename.DEBUG with interleaved lines of text and their token types. The -D flag has been in perltidy from the beginning for this purpose. If you want to see the code which creates this file, it is sub Perl::Tidy::Debugger::write_debug_entry

 
 
EXPORT

 
@@ -411,12 +411,10 @@
 
 
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

-
-
To report a new bug or problem, use the link on this page.

-
 
The source code repository is at https://github.com/perltidy/perltidy.

 
+
To report a new bug or problem, use the "issues" link on this page.

+
 
SEE ALSO

 
 
The perltidy(1) man page describes all of the features of perltidy. It can be found at http://perltidy.sourceforge.net.

diff --git a/docs/perltidy.html b/docs/perltidy.html
index 085b9cd4..93ef5005 100644
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -71,7 +71,9 @@
 
 
DESCRIPTION

 
-
Perltidy reads a perl script and writes an indented, reformatted script.

+
Perltidy reads a perl script and writes an indented, reformatted script. This document describes the parameters available for controlling this formatting.

+
+
Perltidy is a commandline frontend to the module Perl::Tidy. For documentation describing how to call the Perl::Tidy module from other applications see the separate documentation for Perl::Tidy. It is the file Perl::Tidy.pod in the source distribution.

 
 
Many users will find enough information in "EXAMPLES" to get started. New users may benefit from the short tutorial which can be found at http://perltidy.sourceforge.net/tutorial.html

 
@@ -4007,12 +4009,10 @@
 
 
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

-
-
To report a new bug or problem, use the link on this page.

-
 
The source code repository is at https://github.com/perltidy/perltidy.

 
+
To report a new bug or problem, use the "issues" link on this page.

+
 
COPYRIGHT

 
 
Copyright (c) 2000-2022 by Steve Hancock

-- 
2.39.5