+B<Controls for blank lines around lines of consecutive keywords>
+
+The parameters in this section provide some control over the placement of blank
+lines within and around groups of statements beginning with selected keywords.
+These blank lines are called here B<keyword group blanks>, and all of the
+parameters begin with B<--keyword-group-blanks*>, or B<-kgb*> for short. The
+default settings do not employ these controls but they can be enabled with the
+following parameters:
+
+B<-kgbl=s> or B<--keyword-group-blanks-list=s>; B<s> is a quoted string of keywords
+
+B<-kgbs=s> or B<--keyword-group-blanks-size=s>; B<s> gives the number of keywords required to form a group.
+
+B<-kgbb=n> or B<--keyword-group-blanks-before=n>; B<n> = (0, 1, or 2) controls a leading blank
+
+B<-kgba=n> or B<--keyword-group-blanks-after=n>; B<n> = (0, 1, or 2) controls a trailing blank
+
+B<-kgbi> or B<--keyword-group-blanks-inside> is a switch for adding blanks between subgroups
+
+B<-kgbd> or B<--keyword-group-blanks-delete> is a switch for removing initial blank lines between keywords
+
+B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> can limit the number of times this logic is applied
+
+In addition, the following abbreviations are available to for simplified usage:
+
+B<-kgb> or B<--keyword-group-blanks> is short for B<-kgbb=2 -kgba=2 kgbi>
+
+B<-nkgb> or B<--nokeyword-group-blanks>, is short for B<-kgbb=1 -kgba=1 nkgbi>
+
+Before describing the meaning of the parameters in detail let us look at an
+example which is formatted with default parameter settings.
+
+ print "Entering test 2\n";
+ use Test;
+ use Encode qw(from_to encode decode
+ encode_utf8 decode_utf8
+ find_encoding is_utf8);
+ use charnames qw(greek);
+ my @encodings = grep( /iso-?8859/, Encode::encodings() );
+ my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
+ my @source = qw(ascii iso8859-1 cp1250);
+ my @destiny = qw(cp1047 cp37 posix-bc);
+ my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
+ my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
+ return unless ($str);
+
+using B<perltidy -kgb> gives:
+
+ print "Entering test 2\n";
+ <----------this blank controlled by -kgbb
+ use Test;
+ use Encode qw(from_to encode decode
+ encode_utf8 decode_utf8
+ find_encoding is_utf8);
+ use charnames qw(greek);
+ <---------this blank controlled by -kgbi
+ my @encodings = grep( /iso-?8859/, Encode::encodings() );
+ my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
+ my @source = qw(ascii iso8859-1 cp1250);
+ my @destiny = qw(cp1047 cp37 posix-bc);
+ my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
+ my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
+ <----------this blank controlled by -kgba
+ return unless ($str);
+
+Blank lines have been introduced around the B<my> and B<use> sequences. What
+happened is that the default keyword list includes B<my> and B<use> but not
+B<print> and B<return>. So a continuous sequence of nine B<my> and B<use>
+statements was located. This number exceeds the default threshold of five, so
+blanks were placed before and after the entire group. Then, since there was
+also a subsequence of six B<my> lines, a blank line was introduced to separate
+them.
+
+Finer control over blank placement can be achieved by using the individual
+parameters rather than the B<-kgb> flag. The individual controls are as follows.
+
+B<-kgbl=s> or B<--keyword-group-blanks-list=s>, where B<s> is a quoted string,
+defines the set of keywords which will be formed into groups. The string is a
+space separated list of keywords. The default set is B<s="use require local
+our my">, but any list of keywords may be used. Comment lines may also be included in a keyword group, even though they are not keywords. To include ordinary block comments, include the symbol B<BC>. To include static block comments (which normally begin with '##'), include the symbol B<SBC>.
+
+B<-kgbs=s> or B<--keyword-group-blanks-size=s>, where B<s> is a string
+describing the number of consecutive keyword statements forming a group. If
+B<s> is an integer then it is the minimum number required for a group. A
+maximum value may also be given with the format B<s=min.max>, where B<min> is
+the minimum number and B<max> is the maximum number, and the min and max values
+are separated by one or more dots. No groups will be found if the maximum is
+less than the minimum. The maximum is unlimited if not given. The default is
+B<s=5>. Some examples:
+
+ s min max number for group
+ 3 3 unlimited 3 or more
+ 1.1 1 1 1
+ 1..3 1 3 1 to 3
+ 1.0 1 0 (no match)
+
+
+B<-kgbb=n> or B<--keyword-group-blanks-before=n> specifies whether
+a blank should appear before the first line of the group, as follows:
+
+ n=0 => (delete) an existing blank line will be removed
+ n=1 => (stable) no change to the input file is made [DEFAULT]
+ n=2 => (insert) a blank line is introduced if possible
+
+B<-kgba=n> or B<--keyword-group-blanks-after=n> likewise specifies
+whether a blank should appear after the last line of the group, using the same
+scheme (0=delete, 1=stable, 2=insert).
+
+B<-kgbi> or B<--keyword-group-blanks-inside> controls
+the insertion of blank lines between the first and last statement of the entire
+group. If there is a continuous run of a single statement type with more than
+the minimum threshold number (as specified with B<-kgbs=s>) then this
+switch causes a blank line be inserted between this
+subgroup and the others. In the example above this happened between the
+B<use> and B<my> statements.
+
+B<-kgbd> or B<--keyword-group-blanks-delete> controls the deletion of any
+blank lines that exist in the the group when it is first scanned. When
+statements are initially scanned, any existing blank lines are included in the
+collection. Any such orignial blank lines will be deleted before any other
+insertions are made when the parameter B<-kgbd> is set. The default is not to
+do this, B<-nkgbd>.
+
+B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> specifies B<n>, the
+maximum number of times this logic will be applied to any file. The special
+value B<n=0> is the same as n=infinity which means it will be applied to an
+entire script [Default]. A value B<n=1> could be used to make it apply just
+one time for example. This might be useful for adjusting just the B<use>
+statements in the top part of a module for example.
+
+B<-kgb> or B<--keyword-group-blanks> is an abbreviation equivalent to setting
+B<-kgbb=1 -kgba=1 -kgbi>. This turns on keyword group formatting with a set of
+default values.
+
+B<-nkgb> or B<--nokeyword-group-blanks> is equivalent to B<-kgbb=0 -kgba
+nkgbi>. This flag turns off keyword group blank lines and is the default
+setting.
+
+Here are a few notes about the functioning of this technique.
+
+=over 4
+
+=item *
+
+These parameters are probably more useful as part of a major code reformatting
+operation rather than as a routine formatting operation.
+
+In particular, note that deleting old blank lines with B<-kgbd> is an
+irreversible operation so it should be applied with care. Existing blank lines
+may be serving an important role in controlling vertical alignment.
+
+=item *
+
+Conflicts which arise among these B<kgb*> parameters and other blank line
+controls are generally resolved by producing the maximum number of blank lines
+implied by any parameter.
+
+For example, if the flags B<--freeze-blank-lines>, or
+B<--keep-old-blank-lines=2>, are set, then they have priority over any blank
+line deletion implied by the B<-kgb> flags of this section, so no blank lines
+will be deleted.
+
+For another example, if a keyword group ends at a B<sub> and the flag B<kgba=0> requests no blank line there, but we also have B<--blank-lines-before-subs=2>, then two blank lines will still be introduced before the sub.
+
+=item *
+
+The introduction of blank lines does not occur if it would conflict with other
+input controls or code validity. For example, a blank line will not be placed
+within a here-doc or within a section of code marked with format skipping
+comments. And in general, a blank line will only be introduced at the end of a
+group if the next statement is a line of code.
+
+=item *
+
+The count which is used to determine the group size is not the number of lines
+but rather the total number of keywords which are found. Individual statements
+with a certain leading keyword may continue on multiple lines, but if any of
+these lines is nested more than one level deep then that group will be ended.
+
+=item *
+
+The search for groups of lines with similar leading keywords is based on the
+input source, not the final formatted source. Consequently, if the source code
+is badly formatted, it would be best to make a first formatting pass without
+these options.
+
+=back
+