update docs for --use-unicode-gcstring

diff --git a/CHANGES.md b/CHANGES.md
index 9f27bd9fbdc193536e110784fb78e0225ae50857..3ec41d2deaa2b0098d2e0dc4762f5ca98772d0e5 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -5,18 +5,26 @@
     - add option --break-at-old-semicolon-breakpoints', -bos, requested 
       in RT#131644.  This flag will keep lines beginning with a semicolon.
 
+    - Added --use-unicode-gcstring to control use of Unicode::GCString for
+      evaluating character widths of encoded data.  By default, for encoded files
+      perltidy will now look for Unicode::GCString and, if found, will use it 
+      to evaluate character display widths.  This improves displayed 
+      vertical alignment. This flag is mainly intended for testing.  Perltidy
+      installation does not require Unicode::GCString, so users wanting
+      to use this feature need to install it separately.
+
     - Added --character-encoding=guess or -guess to have perltidy guess
       if a file is encoded as -utf8 or some older single-byte encoding. This
       is useful when processing a mixture of file types, such as utf8 and 
       latin-1.  Also, specific encodings of input files other than utf8 may
-      now be given, for example --character-encoding=euc-jp.
-
-      The default encoding has been set to be 'guess' instead of 'none'. I
-      do not like to change defaults, but this seems like the best 
-      default choice, since it should make perltidy
-      work properly with both older latin-1 and newer utf8 files.  I have done
-      extensive testing and haven't found any problems, but I will open
-      an issue at git for comments in case this causes problems.
+      now be given, for example --character-encoding=euc-jp.  For a
+      description of the guessing method see the man pages.
+
+      Please Note: The default encoding has been set to be 'guess'
+      instead of 'none'. I do not like to change defaults, but this seems like
+      the right choice, since it should make perltidy work properly with both
+      older latin-1 and newer utf8 files.  I have done extensive testing and
+      so far haven't found any problems.
 
     - Fix for git#22, Preserve function signature on a single line. An
       unwanted line break was being introduced when a closing signature paren

diff --git a/bin/perltidy b/bin/perltidy
index b75d8885142a7585f07ae93fa92e199974d076ca..b0b09ef2c6a9da7281e91d3b554365abcdcf1116 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -626,7 +626,31 @@ To process a file in B<euc-jp> you could use
    
    perltidy -enc=euc-jp file.pl
 
-A perltidy output file is unencoded if the input file is unencoded, and otherwise it is encoded as B<utf8>, even if the input encoding was not B<utf8>.
+A perltidy output file is unencoded if the input file is unencoded, and
+otherwise it is encoded as B<utf8>, even if the input encoding was not
+B<utf8>.
+
+=item B<-gcs>,  B<--use-unicode-gcstring>
+
+This flag controls whether or not perltidy may use module Unicode::GCString.
+It has no effect if that module is not installed on a system.
+If text is encoded then perltidy will by default use the module
+Unicode::GCString to determine the horizontal widths of the text, provided
+Unicode::GCString is available.  This is needed to produce formatted text with
+good vertical alignment when there are wide characters. If the module is not
+available on the system, or if the flag B<--nouse-unicode-gcstring> or B<ngcs>
+has been set, then this module will not be used and characters will have an
+assumed display width of 1.  In this case, vertical alignment may be poor if
+code contains a mixture of wide and normal characters.  The default setting is
+B<--use-unicode-gcstring>.   This flag is mainly intended for testing, and as a
+workaround in case a problem arises with the Unicode::GCString module.
+
+Perltidy installation does not require Unicode::GCString, so users wanting
+to use this feature need to install it separately.
+
+Also note that actual vertical alignment depends upon the fonts used by the
+text display software, so vertical alignment may not be optimal even when
+Unicode::GCString is used.
 
 =item B<-ole=s>,  B<--output-line-ending=s>