From: Steve Hancock Date: Thu, 16 Apr 2020 17:57:44 +0000 (-0700) Subject: update docs for --use-unicode-gcstring X-Git-Tag: 20200619~89 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=0dfda8024ffc8d2de5a4474542e1c21790c022f7;p=perltidy.git update docs for --use-unicode-gcstring --- diff --git a/CHANGES.md b/CHANGES.md index 9f27bd9f..3ec41d2d 100644 --- 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 b75d8885..b0b09ef2 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -626,7 +626,31 @@ To process a file in B 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, even if the input encoding was not B. +A perltidy output file is unencoded if the input file is unencoded, and +otherwise it is encoded as B, even if the input encoding was not +B. + +=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 +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>