+=head2 Adding and Deleting Commas
+
+=over 4
+
+=item B<-drc>, B<--delete-repeated-commas>
+
+Repeated commas in a list are undesirable and can be removed with this flag.
+For example, given this list with a repeated comma
+
+ ignoreSpec( $file, "file",, \%spec, \%Rspec );
+
+we can remove it with -drc
+
+ # perltidy -drc:
+ ignoreSpec( $file, "file", \%spec, \%Rspec );
+
+Since the default is not to add or delete commas, this feature is off by default and must be requested.
+
+
+=item B<--want-trailing-commas=s> or B<-wtc=s>, B<--add-trailing-commas> or B<-atc>, and B<--delete-trailing-commas> or B<-dtc>
+
+A trailing comma is a comma following the last item of a list. Perl allows
+trailing commas but they are not required. By default, perltidy does not add
+or delete trailing commas, but it is possible to manipulate them with the
+following set of three related parameters:
+
+ --want-trailing-commas=s, -wtc=s - defines where trailing commas are wanted
+ --add-trailing-commas, -atc - gives permission to add trailing commas to match the style wanted
+ --delete-trailing-commas, -dtc - gives permission to delete trailing commas which do not match the style wanted
+
+The parameter B<--want-trailing-commas=s>, or B<-wtc=s>, defines a preferred style. The string B<s> indicates which lists should get trailing commas, as follows:
+
+ s=0 : no list should have a trailing comma
+ s=1 or * : every list should have a trailing comma
+ s=m a multi-line list should have a trailing commas
+ s=b trailing commas should be 'bare' (comma followed by newline)
+ s=h lists of key=>value pairs, with about one one '=>' and one ',' per line,
+ with a bare trailing comma
+ s=i lists with about one comma per line, with a bare trailing comma
+ s=' ' or -wtc not defined : leave trailing commas unchanged [DEFAULT].
+
+This parameter by itself only indicates the where trailing commas are
+wanted. Perltidy only adds these trailing commas if the flag B<--add-trailing-commas>, or B<-atc> is set. And perltidy only removes unwanted trailing commas
+if the flag B<--delete-trailing-commas>, or B<-dtc> is set.
+
+Here are some example parameter combinations and their meanings
+
+ -wtc=0 -dtc : delete all trailing commas
+ -wtc=1 -atc : all lists get trailing commas
+ -wtc=m -atc : all multi-line lists get trailing commas, but
+ single line lists remain unchanged.
+ -wtc=m -dtc : multi-line lists remain unchanged, but
+ any trailing commas on single line lists are removed.
+ -wtc=m -atc -dtc : all multi-line lists get trailing commas, and
+ any trailing commas on single line lists are removed.
+
+For example, given the following input without a trailing comma
+
+ bless {
+ B => $B,
+ Root => $Root
+ } => $package;
+
+we can add a trailing comma after the variable C<$Root> using
+
+ # perltidy -wtc=m -atc
+ bless {
+ B => $B,
+ Root => $Root,
+ } => $package;
+
+This could also be achieved in this case with B<-wtc=b> instead of B<-wtc=m>
+because the trailing comma here is bare (separated from its closing brace by a
+newline). And it could also be achieved with B<-wtc=h> because this particular
+list is a list of key=>value pairs.
+
+The above styles should cover the main of situations of interest, but it is
+possible to apply a different style to each type of container token by
+including an opening token ahead of the style character in the above table.
+For example
+
+ -wtc='(m [b'
+
+means that lists within parens should have multi-line trailing commas, and that
+lists within square brackets have bare trailing commas. Since there is no
+specification for curly braces in this example, their trailing commas would
+remain unchanged.
+
+For parentheses, an additional item of information which can be given is an
+alphanumeric letter which is used to limit the selection further depending on
+the type of token immediately before the opening paren. The possible letters
+are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these meanings for
+matching whatever precedes an opening paren:
+
+ 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
+ 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
+ 'f' matches if the previous token is a function other than a keyword.
+ 'F' matches if 'f' does not.
+ 'w' matches if either 'k' or 'f' match.
+ 'W' matches if 'w' does not.
+
+These are the same codes used for B<--line-up-parentheses-inclusion-list>.
+For example,
+
+ -wtc = 'w(m'
+
+means that trailing commas are wanted for multi-line parenthesized lists following a function call or keyword.
+
+Here are some points to note regarding adding and deleting trailing commas:
+
+=over 4
+
+=item *
+
+For the implementation of these parameters, a B<list> is basically taken to be
+a container of items (parens, square brackets, or braces), which is not a code
+block, with one or more commas. These parameters only apply to something that
+fits this definition of a list.
+
+Note that a paren-less list of parameters is not a list by this definition, so
+these parameters have no effect on a peren-less list.
+
+Another consequence is that if the only comma in a list is deleted, then it
+cannot later be added back with these parameters because the container no
+longer fits this definition of a list. For example, given
+
+ my ( $self, ) = @_;
+
+and if we remove the comma with
+
+ # perltidy -wtc=m -dtc
+ my ( $self ) = @_;
+
+then we cannot use these trailing comma controls to add this comma back.
+
+=item *
+
+By B<multiline> list is meant a list for which the first comma and trailing comma
+are on different lines.
+
+=item *
+
+A B<bare> trailing comma is a comma which is at the end of a line. That is,
+the closing container token follows on a different line. So a list with a
+bare trailing comma is a special case of a multi-line list.
+
+=item *
+
+The decision regarding whether or not a list is multi-line or bare is
+made based on the B<input> stream. In some cases it may take an iteration
+or two to reach a final state.
+
+=item *
+
+When using these parameters for the first time it is a good idea to practice
+on some test scripts and verify that the results are as expected.
+
+=item *
+
+Since the default behavior is not to add or delete commas, these parameters
+can be useful on a temporary basis for reformatting a script.
+
+=back
+
+=item B<-dwic>, B<--delete-weld-interfering-commas>
+
+If the closing tokens of two nested containers are separated by a comma, then
+welding requested with B<--weld-nested-containers> cannot occur. Any commas in
+this situation are optional trailing commas and can be removed with B<-dwic>.
+For example, a comma in this script prevents welding:
+
+ # perltidy -wn
+ skip_symbols(
+ [ qw(
+ Perl_dump_fds
+ Perl_ErrorNo
+ Perl_GetVars
+ PL_sys_intern
+ ) ],
+ );
+
+Using B<-dwic> removes the comma and allows welding:
+
+ # perltidy -wn -dwic
+ skip_symbols( [ qw(
+ Perl_dump_fds
+ Perl_ErrorNo
+ Perl_GetVars
+ PL_sys_intern
+ ) ] );
+
+Since the default is not to add or delete commas, this feature is off by default.
+Here are some points to note about the B<-dwic> parameter
+
+=over 4
+
+=item *
+
+This operation is not reversible, so please check results of using this parameter carefully.
+
+=item *
+
+Removing this type of isolated trailing comma is necessary for welding to be
+possible, but not sufficient. So welding will not always occur where these
+commas are removed.
+
+=back
+
+=back
+