From 9bb0eeb6f67ebb56d3bd7842e561c6cc22435272 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Wed, 10 Jul 2024 15:48:48 -0700 Subject: [PATCH] expand some abbreviations in docs, git #144 suggestion --- bin/perltidy | 300 +++++++++++++++++++++++++++------------------------ 1 file changed, 161 insertions(+), 139 deletions(-) diff --git a/bin/perltidy b/bin/perltidy index f7849a6b..2aef0b80 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -250,7 +250,7 @@ appear in whatever directory contains F. If the path contains spaces, it should be placed in quotes. This parameter will be ignored if output is being directed to standard output, -or if it is being specified explicitly with the B<-o=s> parameter. +or if it is being specified explicitly with the B<-outfile=s> parameter. =item B<-b>, B<--backup-and-modify-in-place> @@ -267,10 +267,11 @@ correctly in your environment and operating system. A B<-b> flag will be ignored if input is from standard input or goes to standard output, or if the B<-html> flag is set. -In particular, if you want to use both the B<-b> flag and the B<-pbp> -(--perl-best-practices) flag, then you must put a B<-nst> flag after the -B<-pbp> flag because it contains a B<-st> flag as one of its components, -which means that output will go to the standard output stream. +In particular, if you want to use both the B<-b> flag and the +B<--perl-best-practices> (B<-pbp>) flag, then you must put a +B<-nostandard-output> (B<-nst>) flag after the B<-pbp> flag because it contains a +B<--standard-output> flag as one of its components, which means that output +will go to the standard output stream. =item B<-bext>=ext, B<--backup-file-extension>=ext @@ -371,7 +372,7 @@ If you set the B<-npro> flag, perltidy will not look for this file. To simplify testing and switching .perltidyrc files, this command may be used to specify a configuration file which will override the default -name of .perltidyrc. There must not be a space on either side of the +name of F<.perltidyrc>. There must not be a space on either side of the '=' sign. For example, the line perltidy -pro=testcfg @@ -487,9 +488,9 @@ and one uses B<-wc=15>, then if the leading whitespace on a line exceeds about from there. If the whitespace never exceeds this limit the formatting remains unchanged. -The combination of B<-vmll> and B<-wc=n> provides a solution to the problem of -displaying arbitrarily deep data structures and code in a finite window, -although B<-wc=n> may of course be used without B<-vmll>. +The combination of B<--variable-maximum-line-length> and +B<--whitespace-cycle=n> provides a solution to the problem of displaying +arbitrarily deep data structures and code in a finite window, although B<--whitespace-cycle=n> may of course be used without B<--variable-maximum-line-length>. The default is not to use this, which can also be indicated using B<-wc=0>. @@ -503,7 +504,7 @@ options. Except for possibly introducing tab indentation characters, as outlined below, perltidy does not introduce any tab characters into your file, and it removes any tabs from the code (unless requested not to do so -with B<-fws>). If you have any tabs in your comments, quotes, or +with B<--freeze-whitespace>). If you have any tabs in your comments, quotes, or here-documents, they will remain. =over 4 @@ -530,10 +531,10 @@ The default is not to use this, which can also be indicated using B<-et=0>. This flag causes one leading tab character to be inserted for each level of indentation. Certain other features are incompatible with this option, and if these options are also given, then a warning message will -be issued and this flag will be unset. One example is the B<-lp> +be issued and this flag will be unset. One example is the B<--line-up-parentheses> option. This flag is retained for backwards compatibility, but -if you use tabs, the B<-et=n> flag is recommended. If both B<-t> and -B<-et=n> are set, the B<-et=n> is used. +if you use tabs, the B<--entab-leading-whitespace=n> flag is recommended. If both B<--tabs> and +B<--entab-leading-whitespace=n> are set, then B<--entab-leading-whitespace=n> is used. =item B<-dt=n>, B<--default-tabsize=n> @@ -571,14 +572,12 @@ as they are, you can add B<--freeze-blank-lines>. With this option perltidy is still free to modify the indenting (and outdenting) of code and comments as it normally would. If you also want to -prevent long comment lines from being outdented, you can add either B<-noll> or -B<-l=0>. +prevent long comment lines from being outdented, you can add either B<--nooutdent-long-lines> (B<-noll>) or B<--maximum-line-length=0> (B). Setting this flag will prevent perltidy from doing any special operations on closing side comments. You may still delete all side comments however when this flag is in effect. - =item B<-enc=s>, B<--character-encoding=s> This flag indicates if the input data stream uses a character encoding. @@ -757,14 +756,14 @@ The same example, with n=0, is a little harder to read: The value given to B<-ci> is also used by some commands when a small space is required. Examples are commands for outdenting labels, -B<-ola>, and control keywords, B<-okw>. +B<--outdent-labels> (B<-ola>), and control keywords, B<--outdent-keywords> (B<-okw>). When default values are not used, it is recommended that either (1) the value B given with B<-ci=n> be no more than about one-half of the number of spaces assigned to a full indentation level on the B<-i=n> command, or -(2) the flag B<-extended-continuation-indentation> is used (see next section). +(2) the flag B<--extended-continuation-indentation> is used (see next section). =item B<-xci>, B<--extended-continuation-indentation> @@ -815,8 +814,8 @@ the default formatting for the following snippet is: . "' found" ); The second and third lines are one level deep in a container, and are also -statement continuations, so they get indented by the sum of the B<-i> -value and the B<-ci> value. If this flag is set, the indentation is reduced by +statement continuations, so they get indented by the sum of the full indentation B<-i> +value and the continuation indentation B<-ci> value. If this flag is set, the indentation is reduced by B<-ci> spaces, giving # perltidy -mci @@ -837,8 +836,8 @@ To guess the starting indentation level perltidy simply assumes that indentation scheme used to create the code snippet is the same as is being used for the current perltidy process. This is the only sensible guess that can be made. It should be correct if this is true, but otherwise it probably won't. -For example, if the input script was written with -i=2 and the current perltidy -flags have -i=4, the wrong initial indentation will be guessed for a code +For example, if the input script was written with B<-i=2> and the current perltidy +flags have B<-i=4>, the wrong initial indentation will be guessed for a code snippet which has non-zero initial indentation. Likewise, if an entabbing scheme is used in the input script and not in the current process then the guessed indentation will be wrong. @@ -902,8 +901,8 @@ specific line breaks (such as line breaks after statements). For both the B<-lp> and B<-xlp> flags, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with these -flags and will cause them to be deactivated. These include B<-io>, B<-fnl>, -B<-nanl>, and B<-ndnl>. +flags and will cause them to be deactivated. These include B<--indent-only>, B<--freeze-newlines>, +B<-noadd-newlines>, and B<-nodelete-old-newlines>. =item * @@ -965,9 +964,9 @@ By default, the B<-lp> flag applies to as many containers as possible. The set of containers to which the B<-lp> style applies can be reduced by either one of these two flags: -Use B<-lpil=s> to specify the containers to which B<-lp> applies, or +Use B<--line-up-parentheses-inclusion-list=s> (B<-lpil=s>) to specify the containers to which B<-lp> applies, or -use B<-lpxl=s> to specify the containers to which B<-lp> does NOT apply. +use B<--line-up-parentheses-exclusion-list=s> (B<-lpxl=s>) to specify the containers to which B<-lp> does NOT apply. Only one of these two flags may be used. Both flags can achieve the same result, but the B<-lpil=s> flag is much easier to describe and use and is @@ -1024,17 +1023,17 @@ a keyword or function. Clearly, the B<-lpil=s> method is easier to understand. An optional numeric code may follow any of the container types to further refine the selection based on container contents. The numeric codes are: - '0' or blank: no check on contents is made - '1' exclude B<-lp> unless the contents is a simple list without sublists - '2' exclude B<-lp> unless the contents is a simple list without sublists, without + '0' or blank: no restriction is placed on container contents + '1' the container contents must be a simple list without sublists + '2' the container contents must be a simple list without sublists, without code blocks, and without ternary operators For example, -lpil = 'f(2' -means only apply -lp to function call lists which do not contain any sublists, -code blocks or ternary expressions. +means only apply -lp to function calls with simple lists (not containing any sublists, +code blocks or ternary expressions). =item B<-cti=n>, B<--closing-token-indentation> @@ -1048,8 +1047,8 @@ a C<)>, C<]>, or a non-block C<}>. Such a line receives: ); or ]; or }; -cti = 3 one extra indentation level always -The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous -section). +The flags B<-cti=1> and B<-cti=2> work well with the B<--line-up-parentheses> +(B<-lp>) flag (previous section). # perltidy -lp -cti=1 @month_of_year = ( @@ -1154,19 +1153,20 @@ For example, to match the side comment '#++', the parameter would be When B<-olq> is set, lines which is a quoted string longer than the value B will have their indentation removed to make them more readable. This is the default. To prevent such out-denting, -use B<-nolq> or B<--nooutdent-long-lines>. +use B<-nolq>. =item B<-oll>, B<--outdent-long-lines> -This command is equivalent to B<--outdent-long-quotes> and +This command is equivalent to the combination B<--outdent-long-quotes> and B<--outdent-long-comments>, and it is included for compatibility with previous versions of perltidy. The negation of this also works, B<-noll> or B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>. =item B B<-ola>, B<--outdent-labels> -This command will cause labels to be outdented by 2 spaces (or whatever B<-ci> -has been set to), if possible. This is the default. For example: +This command will cause labels to be outdented by the number of spaces defined +by B<--continuation-indentation=n>, if possible. +This is the default. For example: my $i; LOOP: while ( $i = ) { @@ -1175,7 +1175,7 @@ has been set to), if possible. This is the default. For example: fixit($i); } -Use B<-nola> to not outdent labels. To control line breaks after labels see L<"-bal=n, --break-after-labels=n">. +Use B<-nola> to prevent this. To control line breaks after labels see L<"-bal=n, --break-after-labels=n">. =item B @@ -1184,7 +1184,8 @@ Use B<-nola> to not outdent labels. To control line breaks after labels see L<" =item B<-okw>, B<--outdent-keywords> The command B<-okw> will cause certain leading control keywords to -be outdented by 2 spaces (or whatever B<-ci> has been set to), if +be outdented by the number of spaces defined by +B<--continuation-indentation=n>spaces, if possible. By default, these keywords are C, C, C, C, and C. The intention is to make these control keywords easier to see. To change this list of keywords being outdented, see @@ -1199,7 +1200,8 @@ For example, using C on the previous example gives: fixit($i); } -The default is not to do this. +Notice that the keyword B has been outdented. The default is not to do +this. =item B B<-okwl=string>, B<--outdent-keyword-list=string> @@ -1210,8 +1212,7 @@ By itself, it does not cause any outdenting to occur, so the B<-okw> command is still required. For example, the commands C<-okwl="next last redo goto" -okw> will cause -those four keywords to be outdented. It is probably simplest to place -any B<-okwl> command in a F<.perltidyrc> file. +those four keywords to be outdented. =back @@ -1306,13 +1307,14 @@ B<--extended-block-tightness>. The specific types of small blocks to which this parameter applies is controlled by a companion control parameter, described in the next section. -Note that if the two flags B<-bbt=n> and B<-bt=n> have the same value -B then there would be no reason to set this flag. +Note that if the two flags B<--block-brace-tightness=n> and +B<--brace-tightness=n> have the same value B then there would be no reason +to set this flag. =item B<-xbtl=s>, B<--extended-block-tightness-list=s> -The previous parameter B<-xbt> can be made to apply to curly braces preceded -by any of the keywords +The previous parameter B<--extended-block-tightness> (B<-xbt>) can be made to +apply to curly braces preceded by any of the keywords print printf exec system say @@ -1321,7 +1323,8 @@ and/or the special symbols $ @ % & * $# The parameter string B may contain a selection of these keywords and symbols -to indicate the brace types to which B<-xbt> applies. For convenience, all of +to indicate the brace types to which B<--extended-block-tightness> applies. +For convenience, all of the keywords can be selected with 'k', and all of the special symbols can be selected with 't'. The default is equivalent to B<-xbtl='k'>, which selects all of the keywords. @@ -1334,9 +1337,9 @@ Examples: -xbtl="kt" # selects all keywords and symbols -xbtl="print say" # selects just keywords B and B: -Here are some formatting examples using the default values of B<-bt=n> and -B<-bbt=n>. Note that in these examples B<$ref> is in block braces but B<$key> -is not. +Here are some formatting examples using the default values of +B<--brace-tightness=n> and B<--block-brace-tightness=n>. Note that in these +examples B<$ref> is in block braces but B<$key> is not. # default formatting print {*STDERR} $message; @@ -1409,7 +1412,7 @@ comment). Setting this option allows perltidy to add certain whitespace to improve code readability. This is the default. If you do not want any whitespace added, but are willing to have some whitespace deleted, use -B<-naws>. (Use B<-fws> to leave whitespace completely unchanged). +B<-naws>. (Use B<--freeze-whitespace> (B<-fws>) to leave whitespace completely unchanged). =item B<-dws>, B<--delete-old-whitespace> @@ -1690,10 +1693,11 @@ The set of keywords to which this parameter applies are by default are: These can be changed with the parameter B<-kpitl=s> described in the next section. -=item B<-kpitl=string> or B<--keyword-paren-inner-tightness=string> +=item B<-kpitl=string> or B<--keyword-paren-inner-tightness-list=string> -This command can be used to change the keywords to which the the B<-kpit=n> -command applies. The parameter B is a required list either keywords or +This command can be used to change the keywords to which the previous +parameter, B<-kpit=n>, +applies. The parameter B is a required list either keywords or functions, which should be placed in quotes if there are more than one. By itself, this parameter does not cause any change in spacing, so the B<-kpit=n> command is still required. @@ -2184,8 +2188,8 @@ single '#'. =item B<-osbc>, B<--outdent-static-block-comments> -The command B<-osbc> will cause static block comments to be outdented by 2 -spaces (or whatever B<-ci=n> has been set to), if possible. +The command B<-osbc> will cause static block comments to be outdented by +the number of B<--continuation-spaces=n>, if possible. =back @@ -2259,6 +2263,7 @@ this: #>>V +(The last character V is like a < or > rotated 90 degrees). Additional text may appear on the special comment lines provided that it is separated from the marker by at least one space to highlight the sign, as in the above examples. @@ -2423,10 +2428,10 @@ B<-fnl>, and they will remain fixed, and the rest of the commands in this section and sections L<"Controlling List Formatting">, L<"Retaining or Ignoring Existing Line Breaks">. -You may want to use B<-noll> with this. +You may want to use B<-nooutdent-long-lines> with this. Note: If you also want to keep your blank lines exactly -as they are, you can use the B<-fbl> flag which is described +as they are, you can use the B<--freeze-blank-lines> flag which is described in the section L<"Blank Line Control">. =back @@ -2464,19 +2469,20 @@ on the same line. Other keywords and function names which are formatted with this "cuddled" style are B, B, B, B. Other block types can be formatted by specifying their names on a -separate parameter B<-cbl>, described in a later section. +separate parameter B<--cuddled-block-list>, described in a later section. Cuddling between a pair of code blocks requires that the closing brace of the first block start a new line. If this block is entirely on one line in the input file, it is necessary to decide if it should be broken to allow cuddling. -This decision is controlled by the flag B<-cbo=n> discussed below. The default +This decision is controlled by the flag B<--cuddled-break-options=n> +(B<-cbo=n>) discussed below. The default and recommended value of B<-cbo=1> bases this decision on the first block in the chain. If it spans multiple lines then cuddling is made and continues along the chain, regardless of the sizes of subsequent blocks. Otherwise, short lines remain intact. -So for example, the B<-ce> flag would not have any effect if the above snippet -is rewritten as +So for example, the B<--cuddled-else> flag would not have any effect if the +above snippet is rewritten as if ($task) { yyy() } else { zzz() } @@ -2492,7 +2498,7 @@ chain if possible. =item B<-cb>, B<--cuddled-blocks> -This flag is equivalent to B<-ce>. +This flag is equivalent to B<--cuddled-else> (B<-ce>). =item B<-cbl>, B<--cuddled-block-list> @@ -2519,21 +2525,20 @@ Using commas avoids the need to protect spaces with quotes. As a diagnostic check, the flag B<--dump-cuddled-block-list> or B<-dcbl> can be used to view the hash of values that are generated by this flag. -Finally, note that the B<-cbl> flag by itself merely specifies which blocks are formatted -with the cuddled format. It has no effect unless this formatting style is activated with -B<-ce>. +Finally, note that the B<--cuddled-block-list> parameter by itself merely +specifies which blocks are formatted with the cuddled format. It has no effect +unless this formatting style is activated with B<--cuddled-else>. =item B<-cblx>, B<--cuddled-block-list-exclusive> -When cuddled else formatting is selected with B<-ce>, setting this flag causes -perltidy to ignore its built-in defaults and rely exclusively on the block types -specified on the B<-cbl> flag described in the previous section. For example, -to avoid using cuddled B and B, which are among the defaults, the -following set of parameters could be used: +When cuddled else formatting is selected with B<-cuddled-else>, setting this +flag causes perltidy to ignore its built-in defaults and rely exclusively on +the block types specified on the B<--cuddled-block-list> flag described in the +previous section. For example, to avoid using cuddled B and B, +which are among the defaults, the following set of parameters could be used: perltidy -ce -cbl='else elsif continue' -cblx - =item B<-cbo=n>, B<--cuddled-break-option=n> Cuddled formatting is only possible between a pair of code blocks if the @@ -2645,11 +2650,12 @@ This flag is negated with B<-nasbl>, and the default is B<-nasbl>. =item B<-bli>, B<--brace-left-and-indent> The flag B<-bli> is similar to the B<-bl> flag but in addition it causes one -unit of continuation indentation ( see B<-ci> ) to be placed before -an opening and closing block braces. +unit of continuation indentation ( see B<--continuation-indentation> ) to be +placed before an opening and closing block braces. -For example, perltidy -bli gives +For example + # perltidy -bli if ( $input_file eq '-' ) { important_function(); @@ -2657,10 +2663,11 @@ For example, perltidy -bli gives By default, this extra indentation occurs for block types: B, B, B, B, B, B, B, B, and -also B and blocks preceded by a B