[PATCH 05/25] doc/bash.1, doc/bashref.texi: Resync.

[G. Branden Robinson]

Break lines in similar places; this eases diffing.

Also apply wording changes that didn't get reflected in bashref.texi or
bash.1, preferring whichever edit was more recent.
---
 doc/bash.1       |  74 +++++++++++++----------
 doc/bashref.texi | 153 +++++++++++++++++++++++++++++------------------
 2 files changed, 138 insertions(+), 89 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 863a8ded..9afddaf3 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -1392,25 +1392,30 @@ .SH PARAMETERS
 assignment statement properties.
 .PP
 In the context where an assignment statement is assigning a value
-to a shell variable or array index, the += operator will
-append to or add to the variable's previous value.
+to a shell variable or array index,
+the += operator will append to
+or add to the variable's previous value.
 This includes arguments to \fIdeclaration\fP commands such as
 \fBdeclare\fP that accept assignment statements.
-When += is applied to a variable for which the \fBinteger\fP attribute
-has been set,
+When += is applied to a variable
+for which the \fBinteger\fP attribute has been set,
 the variable's current value and \fIvalue\fP are each evaluated as
 arithmetic expressions,
 and the sum of the results is assigned as the variable's value.
-The current value is usually an integer constant, but may be an expression.
-When += is applied to an array variable using compound assignment (see
+The current value is usually an integer constant,
+but may be an expression.
+When += is applied to an array variable using compound assignment
+(see
 .B Arrays
-below), the
-variable's value is not unset (as it is when using =), and new values are
-appended to the array beginning at one greater than the array's maximum index
-(for indexed arrays) or added as additional key\-value pairs in an
-associative array.
-When applied to a string-valued variable, \fIvalue\fP is expanded and
-appended to the variable's value.
+below),
+the variable's value is not unset
+(as it is when using =),
+and new values are appended to the array
+beginning at one greater than the array's maximum index
+(for indexed arrays),
+or added as additional key-value pairs in an associative array.
+When applied to a string-valued variable,
+\fIvalue\fP is expanded and appended to the variable's value.
 .PP
 A variable can be assigned the \fInameref\fP attribute using the
 \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
@@ -2108,8 +2113,7 @@ .SS "Shell Variables"
 .B RANDOM
 Each time this parameter is referenced, it expands to a random integer
 between 0 and 32767.
-Assigning
-a value to
+Assigning a value to
 .SM
 .B RANDOM
 initializes (seeds) the sequence of random numbers.
@@ -2280,8 +2284,7 @@ .SS "Shell Variables"
 .TP
 .B BASH_XTRACEFD
 If set to an integer corresponding to a valid file descriptor,
-\fBbash\fP
-will write the trace output generated when
+\fBbash\fP will write the trace output generated when
 .Q "set \-x"
 is enabled to that file descriptor,
 instead of the standard error.
@@ -2314,7 +2317,8 @@ .SS "Shell Variables"
 .TP
 .B CHILD_MAX
 Set the number of exited child status values for the shell to remember.
-\fBBash\fP will not allow this value to be decreased below a POSIX-mandated
+\fBBash\fP does not allow this value to be decreased below a
+POSIX-mandated
 minimum, and there is a maximum value (currently 8192) that this may
 not exceed.
 The minimum value is system-dependent.
@@ -2432,13 +2436,15 @@ .SS "Shell Variables"
 order by modification time (newest first).
 .IP
 The \fInumeric\fP specifier treats names consisting solely of digits as
-numbers and sorts them using their numeric value (so
+numbers and sorts them using their numeric value
+(so
 .Q 2
 will sort before
 .Q 10 ,
 for example).
 When using \fInumeric\fP, names containing non-digits sort after all
-the all-digit names and are sorted by name using the traditional behavior.
+the all-digit names and are sorted by name using the traditional
+behavior.
 .IP
 A sort specifier of \fInosort\fP disables sorting completely;
 .B bash
@@ -2528,15 +2534,16 @@ .SS "Shell Variables"
 In addition to the normal shell pattern matching characters,
 .Q \fB&\fP
 matches the previous history line.
-A backslash will escape the
-.Q \fB&\fP ;
+.Q \fB&\fP
+may be escaped using a backslash;
 the backslash is removed before attempting a match.
 The second and subsequent lines of a multi-line compound command are
 not tested, and are added to the history regardless of the value of
 .SM
-.BR HISTIGNORE .
+.BR HISTIGNORE ,
+if the first line was saved.
 If the first line was not saved, the second and subsequent lines of
-the command are not saved either.
+the command are not saved, either.
 The pattern matching honors the setting of the \fBextglob\fP shell
 option.
 .TP
@@ -2964,7 +2971,8 @@ .SS "Shell Variables"
 .SS Arrays
 .B Bash
 provides one-dimensional indexed and associative array variables.
-Any variable may be used as an indexed array; the
+Any variable may be used as an indexed array;
+the
 .B declare
 builtin will explicitly declare an array.
 There is no maximum
@@ -2973,10 +2981,13 @@ .SS Arrays
 Indexed arrays are referenced using integers (including arithmetic
 expressions) and are zero-based; associative arrays are referenced
 using arbitrary strings.
-Unless otherwise noted, indexed array indices must be non-negative integers.
+Unless otherwise noted,
+indexed array indices must be non-negative integers.
 .PP
 An indexed array is created automatically if any variable is assigned to
-using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP.  The
+using the syntax
+\fIname\fP[\fIsubscript\fP]=\fIvalue\fP.
+The
 .I subscript
 is treated as an arithmetic expression that must evaluate to a number
 greater than or equal to zero.
@@ -3046,7 +3057,8 @@ .SS Arrays
 array, and an index of \-1 references the last element.
 .PP
 The += operator will append to an array variable when assigning
-using the compound assignment syntax; see
+using the compound assignment syntax;
+see
 .SM
 .B PARAMETERS
 above.
@@ -3093,7 +3105,8 @@ .SS Arrays
 .PP
 Referencing an array variable without a subscript is equivalent to
 referencing the array with a subscript of 0.
-Any reference to a variable using a valid subscript is valid, and
+Any reference to a variable using a valid subscript is valid,
+and
 .B bash
 will create an array if necessary.
 .PP
@@ -5026,7 +5039,8 @@ .SH FUNCTIONS
 scope will become visible.
 If the unset acts on a variable at a previous scope, any instance of a
 variable with that name that had been shadowed will become visible
-(see below how the \fBlocalvar_unset\fP shell option changes this behavior).
+(see below how the \fBlocalvar_unset\fP shell option changes this
+behavior).
 .PP
 The \fBFUNCNEST\fP variable, if set to a numeric value greater
 than 0, defines a maximum function nesting level.
diff --git a/doc/bashref.texi b/doc/bashref.texi
index 9450cb72..2be71c2d 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -476,7 +476,8 @@ @node Top
 
 A double quote may be quoted within double quotes by preceding it with
 a backslash.
-If enabled, history expansion will be performed unless an @samp{!}
+If enabled, history expansion is performed unless an
+@samp{!}
 appearing in double quotes is escaped using a backslash.
 The backslash preceding the @samp{!} is not removed.
 
@@ -1715,9 +1716,10 @@ @node Top
 until it is reset in that scope or until the function returns.
 Once the function returns, any instance of the variable at a previous
 scope will become visible.
-If the unset acts on a variable at a previous scope, any instance of a   
+If the unset acts on a variable at a previous scope, any instance of a
 variable with that name that had been shadowed will become visible
-(see below how @code{localvar_unset} shell option changes this behavior).
+(see below how the @code{localvar_unset} shell option changes this
+behavior).
 
 The @option{-f} option to the @code{declare} (@code{typeset})
 builtin command (@pxref{Bash Builtins})
@@ -1792,25 +1794,29 @@ @node Top
 command export var=value
 @end example
 
-In the context where an assignment statement is assigning a value  
-to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
-operator will append to or add to the variable's previous value.
-This includes arguments to declaration commands such as @code{declare}
-that accept assignment statements.
-When @samp{+=} is applied to a variable for which the @code{integer} attribute
-has been set,
+In the context where an assignment statement is assigning a value
+to a shell variable or array index (@pxref{Arrays}),
+the @samp{+=} operator will append to
+or add to the variable's previous value.
+This includes arguments to declaration commands such as
+@code{declare} that accept assignment statements.
+When @samp{+=} is applied to a variable
+for which the @code{integer} attribute has been set,
 the variable's current value and @var{value} are each evaluated as
 arithmetic expressions,
 and the sum of the results is assigned as the variable's value.
-The current value is usually an integer constant, but may be an expression.
+The current value is usually an integer constant,
+but may be an expression.
 When @samp{+=} is applied to an array variable using compound assignment
-(@pxref{Arrays}), the
-variable's value is not unset (as it is when using @samp{=}), and new
-values are appended to the array beginning at one greater than the array's
-maximum index (for indexed arrays), or added as additional key-value pairs
-in an associative array.
-When applied to a string-valued variable, @var{value} is expanded and
-appended to the variable's value.
+(@pxref{Arrays}),
+the variable's value is not unset
+(as it is when using @samp{=}),
+and new values are appended to the array
+beginning at one greater than the array's maximum index
+(for indexed arrays),
+or added as additional key-value pairs in an associative array.
+When applied to a string-valued variable,
+@var{value} is expanded and appended to the variable's value.
 
 A variable can be assigned the @code{nameref} attribute using the
 @option{-n} option to the @code{declare} or @code{local} builtin commands
@@ -2058,6 +2064,8 @@ @node Top
 and @var{incr}, an optional increment, is an integer.
 When integers are supplied, the expression expands to each number between
 @var{x} and @var{y}, inclusive.
+If the supplied integers are prefixed with @samp{0}, each term will
+have the same width, zero-padding if necessary.
 When either @var{x} or @var{y} begins with a zero, the shell
 attempts to force all generated terms to contain the same number of digits,
 zero-padding where necessary.
@@ -2881,7 +2889,7 @@ @node Top
 If the
 @code{<(@var{list})} form is used, reading the file 
 will obtain the output of @var{list}.
-Note that no space may appear between the @code{<} or @code{>}
+No space may appear between the @code{<} or @code{>}
 and the left parenthesis, otherwise the construct would be interpreted
 as a redirection.
 
@@ -3013,7 +3021,8 @@ @node Top
 However, setting @env{GLOBIGNORE} to a non-null value has the effect of
 enabling the @code{dotglob}
 shell option, so all other filenames beginning with a
-@samp{.} will match.
+@samp{.}
+will match.
 To get the old behavior of ignoring filenames beginning with a
 @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
 The @code{dotglob} option is disabled when @env{GLOBIGNORE}
@@ -3294,10 +3303,15 @@ @node Top
 [@var{n}]>[|]@var{word}
 @end example
 
-If the redirection operator is @samp{>}, and the @code{noclobber}
-option to the @code{set} builtin has been enabled, the redirection
-will fail if the file whose name results from the expansion of
-@var{word} exists and is a regular file.
+If the redirection operator is
+@samp{>},
+and the
+@code{noclobber}
+option to the
+@code{set}
+builtin has been enabled, the redirection will fail if the file
+whose name results from the expansion of @var{word} exists and is
+a regular file.
 If the redirection operator is @samp{>|}, or the redirection operator is
 @samp{>} and the @code{noclobber} option is not enabled,
 Bash attemps the redirection
@@ -6835,7 +6849,8 @@ @node Top
 
 @item CHILD_MAX
 Set the number of exited child status values for the shell to remember.
-Bash will not allow this value to be decreased below a @sc{posix}-mandated
+Bash does not allow this value to be decreased below a
+@sc{posix}-mandated
 minimum, and there is a maximum value (currently 8192) that this may
 not exceed.
 The minimum value is system-dependent.
@@ -7053,9 +7068,12 @@ @node Top
 
 The @samp{numeric} specifier treats names consisting solely of digits as
 numbers and sorts them using their numeric value
-(so "2" will sort before "10", for example).
+(so "2"
+will sort before
+ "10", for example).
 When using @samp{numeric}, names containing non-digits sort after all
-the all-digit names and are sorted by name using the traditional behavior.
+the all-digit names and are sorted by name using the traditional
+behavior.
 
 A sort specifier of @samp{nosort} disables sorting completely;
 Bash returns the results
@@ -7079,20 +7097,22 @@ @node Top
 @item histchars
 Up to three characters which control history expansion, quick
 substitution, and tokenization (@pxref{History Interaction}).
-The first character is the
-@dfn{history expansion} character,
-the character which begins a history expansion, normally @samp{!}.
-The second character is the
-character which signifies "quick substitution" when seen as the first
-character on a line, normally @samp{^}.
-The optional third character is the
-character which indicates that the remainder of the line is a comment when
-found as the first character of a word, usually @samp{#}.
-The history
-comment character disables history substitution for the
-remaining words on the line.
-It does not necessarily cause the shell
-parser to treat the rest of the line as a comment.
+The first character is the @dfn{history expansion} character,
+the character which begins a history expansion, normally
+@samp{!}.
+The second character is the "quick substitution" character, normally
+@samp{^}.
+When it appears as the first character on the line,
+history substitution repeats the previous command,
+replacing one string with another.
+The optional third character is the character which indicates that
+the remainder of the line is a comment when found as the first character
+of a word, normally
+@samp{#}.
+The history comment character disables history substitution
+for the remaining words on the line.
+It does not necessarily cause the shell parser to treat the rest of the
+line as a comment.
 
 @item HISTCMD
 The history number, or index in the history list, of the current
@@ -7146,20 +7166,26 @@ @node Top
 A colon-separated list of patterns used to decide which command
 lines should be saved on the history list.
 If a command line matches one of the patterns in the value of
-@code{HISTIGNORE}, it is not saved on the history list.
-Each pattern is
-anchored at the beginning of the line and must match the complete
-line (Bash will not implicitly append a @samp{*}).
-Each pattern is tested
-against the line after the checks specified by @env{HISTCONTROL}
+@code{HISTIGNORE},
+it is not saved on the history list.
+Each pattern is anchored at the
+beginning of the line and must match the complete line
+(Bash will not implicitly append a
+@samp{*}).
+Each pattern is tested against the line
+after the checks specified by
+@env{HISTCONTROL}
 are applied.
-In addition to the normal shell pattern matching characters, @samp{&}
+In addition to the normal shell pattern matching characters,
+@samp{&}
 matches the previous history line.
-@samp{&} may be escaped using a backslash; the backslash is removed
-before attempting a match. 
+@samp{&}
+may be escaped using a backslash;
+the backslash is removed before attempting a match.
 The second and subsequent lines of a multi-line compound command are
 not tested, and are added to the history regardless of the value of
-@env{HISTIGNORE}, if the first line was saved.
+@env{HISTIGNORE},
+if the first line was saved.
 If the first line was not saved, the second and subsequent lines of
 the command are not saved, either.
 The pattern matching honors the setting of the @code{extglob} shell
@@ -7363,8 +7389,10 @@ @node Top
 
 @item RANDOM
 Each time this parameter is referenced, it expands to a random integer
-between 0 and 32767. Assigning a value to this
-variable initializes (seeds) the random number generator.
+between 0 and 32767.
+Assigning a value to this
+@env{RANDOM}
+initializes (seeds) the sequence of random numbers.
 Seeding the random number generator with the same constant value will
 produce the same sequence of values.
 If @env{RANDOM}
@@ -7778,7 +7806,9 @@ @node Top
 shell with the @option{--login} option, it first attempts to read
 and execute commands from @file{/etc/profile} and @file{~/.profile}, in
 that order.
-The @option{--noprofile} option will inhibit this behavior.
+The
+@option{--noprofile}
+option will inhibit this behavior.
 
 When invoked as an interactive shell with the name @code{sh}, Bash
 looks for the variable @env{ENV}, expands its value if it is defined,
@@ -8369,22 +8399,26 @@ @node Top
 alias definitions on a separate line, and do not use @code{alias}
 in compound commands.
 
-For almost every purpose, shell functions are preferred over aliases.
+For almost every purpose, shell functions are preferable to aliases.
 
 @node Arrays
 @section Arrays
 @cindex arrays
 
-Bash provides one-dimensional indexed and associative array variables.
+Bash
+provides one-dimensional indexed and associative array variables.
 Any variable may be used as an indexed array;
-the @code{declare} builtin will explicitly declare an array.
+the
+@code{declare}
+builtin will explicitly declare an array.
 There is no maximum
 limit on the size of an array, nor any requirement that members
 be indexed or assigned contiguously.
 Indexed arrays are referenced using integers (including arithmetic
 expressions (@pxref{Shell Arithmetic})) and are zero-based;
 associative arrays use arbitrary strings.
-Unless otherwise noted, indexed array indices must be non-negative integers.
+Unless otherwise noted,
+indexed array indices must be non-negative integers.
 
 An indexed array is created automatically if any variable is assigned to
 using the syntax
@@ -8507,7 +8541,8 @@ @node Top
 Referencing an array variable without a subscript is equivalent to
 referencing with a subscript of 0.
 Any reference to a variable using a valid subscript is valid, and
-Bash will create an array if necessary.
+Bash
+will create an array if necessary.
 
 An array variable is considered set if a subscript has been assigned a
 value.
-- 
2.30.2

signature.asc
Description: PGP signature