Big pr update from Roland Huebner.

1 files changed, 175 insertions, 98 deletions

diff --git a/doc/textutils.texi b/doc/textutils.texi
index fdbcf5ec9..7024bdf89 100644
--- a/doc/textutils.texi
+++ b/doc/textutils.texi
@@ -103,6 +103,9 @@ by the Foundation.
 @end titlepage
 
 
+@c If your makeinfo doesn't grok this @ifnottex directive, then either
+@c get a newer version of makeinfo or do s/ifnottex/ifinfo/ here and on
+@c the matching @end directive below.
 @ifnottex
 @node Top
 @top GNU text utilities
@@ -961,23 +964,43 @@ optionally outputting in multicolumn format; optionally merges all
 pr [@var{option}]@dots{} [@var{file}]@dots{}
 @end example
 
-By default, a 5-line header is printed: two blank lines; a line with the
-date, the file name, and the page count; and two more blank lines.  A
-footer of five blank lines is also printed. With the @samp{-f} option, a
-3-line header is printed: the leading two blank lines are omitted; no
-footer used. The default @var{page_length} in both cases is 66 lines.
-The text line of the header takes up the full @var{page_width} in the
-form @samp{yy-mm-dd HH:MM string Page nnnn}. String is a centered
-string.
-
-Form feeds in the input cause page breaks in the output. Multiple form
+By default, a 5-line header is printed at each page: two blank lines;
+a line with the date, the filename, and the page count; and two more
+blank lines.  A footer of five blank lines is also printed.  With the @samp{-F}
+option, a 3-line header is printed: the leading two blank lines are
+omitted; no footer is used.  The default @var{page_length} in both cases is 66
+lines.  The default number of text lines changes from 56 (without @samp{-F})
+to 63 (with @samp{-F}).  The text line of the header takes up the full
+@var{page_width} in the form @samp{yyyy-mm-dd HH:MM string Page nnnn}.
+String is a centered header string.
+
+Form feeds in the input cause page breaks in the output.  Multiple form
 feeds produce empty pages.
 
-Columns have equal width, separated by an optional string (default
-space). Lines will always be truncated to line width (default 72),
-unless you use the @samp{-j} option. For single column output no line
-truncation occurs by default. Use @samp{-w} option to truncate lines
-in that case.
+Columns are of equal width, separated by an optional string (default
+is @samp{space}).  For multicolumn output, lines will always be truncated to
+@var{page_width} (default 72), unless you use the @samp{-J} option.  For single
+column output no line truncation occurs by default.  Use @samp{-W} option to
+truncate lines in that case.
+
+   Including version 1.22i:
+
+Some small @var{letter options} (@samp{-s}, @samp{-w}) has been redefined
+with the object of a better @var{posix} compliance.  The output of some
+further cases has been adapted to other @var{unix}es.  A violation of
+downward compatibility has to be accepted.
+
+Some @var{new capital letter} options (@samp{-J}, @samp{-S}, @samp{-W})
+has been introduced to turn off unexpected interferences of small letter
+options.  The @samp{-N} option and the second argument @var{last_page}
+of @samp{+FIRST_PAGE} offer more flexibility.  The detailed handling of
+form feeds set in the input files requires @samp{-T} option.
+
+Capital letter options dominate small letter ones.
+
+Some of the option-arguments (compare @samp{-s}, @samp{-S}, @samp{-e},
+@samp{-i}, @samp{-n}) cannot be specified as separate arguments from the
+preceding option letter (already stated in the @var{posix} specification).
 
 The program accepts the following options.  Also see @ref{Common options}.
 
@@ -987,32 +1010,39 @@ The program accepts the following options.  Also see @ref{Common options}.
 @itemx --pages=@var{first_page}[:@var{last_page}]
 @opindex +@var{first_page}[:@var{last_page}]
 @opindex --pages
-Begin printing with page @var{first_page} and stop with
-@var{last_page}. Missing @samp{:@var{last_page}} implies end of file. While
-estimating the number of skipped pages each form feed in the input file
-results in a new page. Page counting with and without
-@samp{+@var{first_page}} is identical. By default, it starts with the
-first page of input file (not first page printed). Page numbering may be
-altered by @samp{-N} option.
+Begin printing with page @var{first_page} and stop with @var{last_page}.
+Missing @samp{:@var{last_page}} implies end of file.  While estimating
+the number of skipped pages each form feed in the input file results
+in a new page.  Page counting with and without @samp{+@var{first_page}}
+is identical.  By default, counting starts with the first page of input
+file (not first page printed).  Line numbering may be altered by @samp{-N}
+option.
 
 @item -@var{column}
 @itemx --columns=@var{column}
 @opindex -@var{column}
 @opindex --columns
 @cindex down columns
-With each single @var{file}, produce @var{column}-column output and
-print columns down. The column width is automatically estimated from
-@var{page_width}. This option might well cause some columns to be
-truncated. The number of lines in the columns on each page will be
-balanced. @samp{-@var{column}} may not be used with @samp{-m} option.
+With each single @var{file}, produce @var{column} columns of output
+(default is 1) and print columns down, unless @samp{-a} is used.  The
+column width is automatically decreased as @var{column} increases; unless
+you use the @samp{-W/-w} option to increase @var{page_width} as well.
+This option might well cause some lines to be truncated.  The number of
+lines in the columns on each page are balanced.  The options @samp{-e}
+and @samp{-i} are on for multiple text-column output.  Together with
+@samp{-J} option column alignment and line truncation is turned off.
+Lines of full length are joined in a free field format and @samp{-S}
+option may set field separators.  @samp{-@var{column}} may not be used
+with @samp{-m} option.
 
 @item -a
 @itemx --across
 @opindex -a
 @opindex --across
 @cindex across columns
-With each single @var{file}, print columns across rather than down.
-@var{column} must be greater than one.
+With each single @var{file}, print columns across rather than down.  The
+@samp{-@var{column}} option must be given with @var{column} greater than one.
+If a line is too long to fit in a column, it is truncated.
 
 @item -c
 @itemx --show-control-chars
@@ -1034,7 +1064,7 @@ Double space the output.
 @opindex -e
 @opindex --expand-tabs
 @cindex input tabs
-Expand tabs to spaces on input.  Optional argument @var{in-tabchar} is
+Expand @var{tab}s to spaces on input.  Optional argument @var{in-tabchar} is
 the input tab character (default is @key{TAB}).  Second optional
 argument @var{in-tabwidth} is the input tab character's width (default
 is 8).
@@ -1045,93 +1075,110 @@ is 8).
 @opindex -F
 @opindex -f
 @opindex --form-feed
-Use a form feed instead of newlines to separate output pages. Default
-page length of 66 lines is not altered. But the number of lines of text
-per page changes from 56 to 63 lines.
-
+Use a form feed instead of newlines to separate output pages.  The default
+page length of 66 lines is not altered.  But the number of lines of text
+per page changes from default 56 to 63 lines.
 
 @item -h @var{HEADER}
 @itemx --header=@var{HEADER}
 @opindex -h
 @opindex --header
-Replace the file name in the header with the centered string
-@var{header}. Left-hand-side truncation (marked by a @samp{*}) may occur
-if the total header line @samp{yy-mm-dd HH:MM HEADER Page nnnn}
-becomes larger than @var{page_width}. @samp{-h ""} prints a blank line
-header. Don't use @samp{-h""}. A space between the -h option and the
-argument is always peremptory.
+Replace the filename in the header with the centered string @var{header}.
+Left-hand-side truncation (marked by a @samp{*}) may occur if the total
+header line @samp{yyyy-mm-dd HH:MM HEADER Page nnnn} becomes larger than
+@var{page_width}.  @samp{-h ""} prints a blank line header.  Don't use
+@samp{-h""}.
+A space between the @samp{-h} option and the argument is always
+indispensable.
 
 @item -i[@var{out-tabchar}[@var{out-tabwidth}]]
 @itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
 @opindex -i
 @opindex --output-tabs
 @cindex output tabs
-Replace spaces with tabs on output.  Optional argument @var{out-tabchar}
+Replace spaces with @var{tab}s on output.  Optional argument @var{out-tabchar}
 is the output tab character (default is @key{TAB}).  Second optional
 argument @var{out-tabwidth} is the output tab character's width (default
 is 8).
 
-@item -j
+@item -J
 @itemx --join-lines
-@opindex -j
+@opindex -J
 @opindex --join-lines
-Merge lines of full length. Used together with the column options
-@samp{-@var{column}}, @samp{-a -@var{column}} or @samp{-m}. Turns off
-@samp{-w} line truncation; no column alignment used; may be used with
-@samp{-s[@var{separator}]}.
+Merge lines of full length.  Used together with the column options
+@samp{-@var{column}}, @samp{-a -@var{column}} or @samp{-m}.  Turns off
+@samp{-W/-w} line truncation;
+no column alignment used; may be used with @samp{-S[@var{string}]}.
+@samp{-J} has been introduced (together with @samp{-W} and @samp{-S})
+to disentangle the old (@var{posix} compliant) options @samp{-w} and
+@samp{-s} along with the three column options.
 
 
 @item -l @var{page_length}
 @itemx --length=@var{page_length}
 @opindex -l
 @opindex --length
-Set the page length to @var{page_length} (default 66) lines. If
-@var{page_length} is less than or equal 10 (and <= 3 with @samp{-f}),
-the headers and footers are omitted, and all form feeds set in input
-files are eliminated, as if the @samp{-T} option had been given.
+Set the page length to @var{page_length} (default 66) lines, including
+the lines of the header [and the footer].  If @var{page_length} is less
+than or equal 10 (and <= 3 with @samp{-F}), the header and footer are
+omitted, and all form feeds set in input files are eliminated, as if
+the @samp{-T} option had been given.
 
 @item -m
 @itemx --merge
 @opindex -m
 @opindex --merge
-Merge and print all @var{file}s in parallel, one in each column. If a
-line is too long to fit in a column, it is truncated (but see
-@samp{-j}). @samp{-s[@var{separator}]} may be used. Empty pages in some
-@var{file}s (form feeds set) produce empty columns, still marked by
-@var{separator}. Completely empty common pages show no separators or
-line numbers. The default header becomes
-@samp{yy-mm-dd HH:MM <blanks> Page nnnn}; may be used with
-@samp{-h @var{header}} to fill up the middle part.
-
+Merge and print all @var{file}s in parallel, one in each column.  If a
+line is too long to fit in a column, it is truncated, unless @samp{-J}
+option is used.  @samp{-S[@var{string}]} may be used.  Empty pages in
+some @var{file}s (form feeds set) produce empty columns, still marked
+by @var{string}.  The result is a continuous line numbering and column
+marking throughout the whole merged file.  Completely empty merged pages
+show no separators or line numbers.  The default header becomes
+@samp{yyyy-mm-dd HH:MM <blanks> Page nnnn}; may be used with
+@samp{-h @var{header}} to fill up the middle blank part.
 
 @item -n[@var{number-separator}[@var{digits}]]
 @itemx --number-lines[=@var{number-separator}[@var{digits}]]
 @opindex -n
 @opindex --number-lines
-Precede each column with a line number; with parallel @var{file}s
-(@samp{-m}), precede only each line with a line number. Optional argument
-@var{number-separator} is the character to print after each number
-(default is @key{TAB}).  Optional argument @var{digits} is the number of
-digits per line number (default is 5). Default line counting starts with
-first line of the input file (not with the first line printed, see
-@samp{-N}).
+Provide @var{digits} digit line numbering (default for @var{digits} is
+5).  With multicolumn output the number occupies the first @var{digits}
+column positions of each text column or only each line of @samp{-m}
+output.  With single column output the number precedes each line just as
+@samp{-m} does.  Default counting of the line numbers starts with 1st
+line of the input file (not the 1st line printed, compare the
+@samp{--page} option and @samp{-N} option).
+Optional argument @var{number-separator} is the character appended to
+the line number to separate it from the text followed.  The default
+separator is a @key{TAB}.  In a strict sense a @key{TAB} is always
+printed with single column output only.  The @var{TAB}-width varies
+with the @var{TAB}-position, e.g. with the left @var{margin} specified
+by @samp{-o} option.  With multicolumn output priority is given to
+@samp{equal width of output columns} (a @var{posix} specification).
+The @var{TAB}-width is fixed to the value of the 1st column and does
+not change with different values of left @var{margin}.  That means a
+fixed number of spaces is always printed in the place of the
+@var{number-separator tab}.  The tabification depends upon the output
+position.
 
 @item -N @var{line_number}
 @itemx --first-line-number=@var{line_number}
 @opindex -N
 @opindex --first-line-number
-Start line counting with no. @var{line_number} at first line of first
-page printed.
+Start line counting with the number @var{line_number} at first line of
+first page printed (in most cases not the first line of the input file).
 
-@item -o @var{n}
-@itemx --indent=@var{n}
+@item -o @var{margin}
+@itemx --indent=@var{margin}
 @opindex -o
 @opindex --indent
 @cindex indenting lines
 @cindex left margin
-Indent each line with @var{n} (default is zero) spaces wide, i.e., set
-the left margin.  The total page width is @var{n} plus the width set
-with the @samp{-w} option.
+Indent each line with a margin @var{margin} spaces wide (default is zero).
+The total page width is the size of the margin plus the @var{page_width}
+set with the @samp{-W/-w} option.  A limited overflow may occur with
+numbered single column output (compare @samp{-n} option).
 
 @item -r
 @itemx --no-file-warnings
@@ -1140,34 +1187,50 @@ with the @samp{-w} option.
 Do not print a warning message when an argument @var{file} cannot be
 opened.  (The exit status will still be nonzero, however.)
 
-@item -s[@var{separator}]
-@itemx --separator[=@var{separator}]
+@item -s[@var{char}]
+@itemx --separator[=@var{char}]
 @opindex -s
 @opindex --separator
-Separate columns by a string @var{separator}. Don't use
-@samp{-s @var{separator}}, no space between flag and argument. If this
-option is omitted altogether, the default is @key{TAB} together with
-@samp{-j} option and space otherwise (same as @samp{-s" "}). With
-@samp{-s} only, no separator is used (same as @samp{-s""}). @samp{-s}
-does not affect line truncation or column alignment.
+Separate columns by a single character @var{char}.  Default for @var{char}
+is the @key{TAB} character without @samp{-w} and @samp{no character} with
+@samp{-w}.  Without @samp{-s} default separator @samp{space} is set.
+@samp{-s[char]} turns off line truncation of all three column options
+(@samp{-COLUMN}|@samp{-a -COLUMN}|@samp{-m}) except @samp{-w} is set.
+That is a @var{posix} compliant formulation.
+
+
+@item -S[@var{string}]
+@itemx --sep-string[=@var{string}]
+@opindex -S
+@opindex --sep-string
+Separate columns by any string @var{string}.  The @samp{-S} option doesn't
+react upon the @samp{-W/-w} option (unlike @samp{-s} option does).  It
+does not affect line truncation or column alignment.  A separator is
+defined, nothing else.  Without @samp{-S}: default separator @key{TAB}
+is used with @samp{-J} and @samp{space} otherwise (same as @samp{-S" "}).
+With @samp{-S} only: no separator is used, same as @samp{-S""}.  Quotes
+should be used with blanks and some shell active characters.  Some of the
+@code{pr} options don't allow the option letter to be separated from its
+argument.  @samp{-S/-s} is one of them.  Don't use @samp{-S "STRING"}.
+That's @var{posix} compliant.
 
 @item -t
 @itemx --omit-header
 @opindex -t
 @opindex --omit-header
 Do not print the usual header [and footer] on each page, and do not fill
-out the bottoms of pages (with blank lines or a form feed). No page
-structure is produced, but retain form feeds set in the input files. The
-predefined page layout is not changed. @samp{-t} or @samp{-T} may be
-useful together with other options; e.g.: @samp{-t -e4}, expand
-@key{TAB} in the input file to 4 spaces but do not do any other changes.
-Use of @samp{-t} overrides @samp{-h}.
+out the bottom of pages (with blank lines or a form feed).  No page
+structure is produced, but form feeds set in the input files are retained.
+The predefined pagination is not changed.  @samp{-t} or @samp{-T} may be
+useful together with other options; e.g.: @samp{-t -e4}, expand @key{TAB}
+in the input file to 4 spaces but don't make any other changes.  Use of
+@samp{-t} overrides @samp{-h}.
 
 @item -T
 @itemx --omit-pagination
 @opindex -T
 @opindex --omit-pagination
-Do not print header [and footer]. In addition eliminate all form feeds
+Do not print header [and footer].  In addition eliminate all form feeds
 set in the input files.
 
 @item -v
@@ -1180,14 +1243,28 @@ Print unprintable characters in octal backslash notation.
 @itemx --width=@var{page_width}
 @opindex -w
 @opindex --width
-Set the page width to @var{page_width} (default 72) characters.
-With/without @samp{-w}, header lines are always truncated to
-@var{page_width} characters. With @samp{-w}, text lines are truncated,
-unless @samp{-j} is used. Without @samp{-w} together with one of the
-column options @samp{-@var{column}}, @samp{-a -@var{column}} or
-@samp{-m}, default truncation of text lines to 72 characters is used.
-Without @samp{-w} and without any of the column options, no line
-truncation is used. That's equivalent to @samp{-w 72 -j}.
+Set page width to @var{page_width} characters for multiple text-column
+output only (default for @var{page_width} is 72).  @samp{-s[CHAR]} turns
+off the default page width and any line truncation and column alignment.
+Lines of full length are merged, regardless of the column options
+set.  No @var{page_width} setting is possible with single column output.
+A @var{posix} compliant formulation.
+
+@item -W @var{page_width}
+@itemx --page_width=@var{page_width}
+@opindex -W
+@opindex --page_width
+Set the page width to @var{page_width} characters.  That's valid with and
+without a column option.  Text lines are truncated, unless @samp{-J}
+is used.  Together with one of the three column options
+(@samp{-@var{column}}, @samp{-a -@var{column}} or @samp{-m}) column
+alignment is always used.  The separator options @samp{-S} or @samp{-s}
+don't affect the @samp{-W} option.  Default is 72 characters.  Without
+@samp{-W @var{page_width}} and without any of the column options NO line
+truncation is used (defined to keep downward compatibility and to meet
+most frequent tasks).  That's equivalent to @samp{-W 72 -J}.  With and
+without @samp{-W @var{page_width}} the header line is always truncated
+to avoid line overflow.
 
 @end table
 
@@ -1207,7 +1284,7 @@ lines.  Synopsis:
 fold [@var{option}]@dots{} [@var{file}]@dots{}
 @end example
 
-By default, @code{fold} breaks lines wider than 80 columns. The output
+By default, @code{fold} breaks lines wider than 80 columns.  The output
 is split into as many lines as necessary.
 
 @cindex screen columns