commit bash-20120525 snapshot

doc/bash.1

@@ -5,12 +5,12 @@
 .\"	Case Western Reserve University
 .\"	chet@po.cwru.edu
 .\"
-.\"	Last Change: Sat Apr  7 20:01:48 EDT 2012
+.\"	Last Change: Sun May 27 20:28:33 EDT 2012
 .\"
 .\" bash_builtins, strip all but Built-Ins section
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
-.TH BASH 1 "2012 April 7" "GNU Bash 4.2"
+.TH BASH 1 "2012 May 27" "GNU Bash 4.2"
 .\"
 .\" There's some problem with having a `@'
 .\" in a tagged paragraph with the BSD man macros.
@@ -2697,10 +2697,12 @@ or when
 .I parameter
 is followed by a character which is not to be
 interpreted as part of its name.
+The \fIparameter\fP is a shell parameter as described above
+\fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
 .PD
 .PP
 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
-a level of variable indirection is introduced.
+it introduces a level of variable indirection.
 \fBBash\fP uses the value of the variable formed from the rest of
 \fIparameter\fP as the name of the variable; this variable is then
 expanded and that value is used in the rest of the substitution, rather
@@ -2714,7 +2716,8 @@ introduce indirection.
 In each of the cases below, \fIword\fP is subject to tilde expansion,
 parameter expansion, command substitution, and arithmetic expansion.
 .PP
-When not performing substring expansion, using the forms documented below,
+When not performing substring expansion, using the forms documented below
+(e.g., \fB:-\fP),
 \fBbash\fP tests for a parameter that is unset or null.  Omitting the colon
 results in a test only for a parameter that is unset.
 .PP
@@ -2767,33 +2770,50 @@ ${\fIparameter\fP\fB:\fP\fIoffset\fP}
 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
 .PD
 \fBSubstring Expansion\fP.
-Expands to up to \fIlength\fP characters of \fIparameter\fP
+Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
 starting at the character specified by \fIoffset\fP.
-If \fIlength\fP is omitted, expands to the substring of
-\fIparameter\fP starting at the character specified by \fIoffset\fP.
+If \fIparameter\fP is \fB@\fP, an indexed array subscripted by
+\fB@\fP or \fB*\fP, or an associative array name, the results differ as
+described below.
+If \fIlength\fP is omitted, expands to the substring of the value of
+\fIparameter\fP starting at the character specified by \fIoffset\fP
+and extending to the end of the value.
 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
 .SM
 .B
 ARITHMETIC EVALUATION
 below).
+.sp 1
 If \fIoffset\fP evaluates to a number less than zero, the value
-is used as an offset from the end of the value of \fIparameter\fP.
-If \fIlength\fP evaluates to a number less than zero, and \fIparameter\fP
-is not \fB@\fP and not an indexed or associative array, it is interpreted
-as an offset from the end of the value of \fIparameter\fP rather than
-a number of characters, and the expansion is the characters between the
-two offsets.
+is used as an offset in characters
+from the end of the value of \fIparameter\fP.
+If \fIlength\fP evaluates to a number less than zero,
+it is interpreted as an offset in characters
+from the end of the value of \fIparameter\fP rather than
+a number of characters, and the expansion is the characters between
+\fIoffset\fP and that result.
+Note that a negative offset must be separated from the colon by at least
+one space to avoid being confused with the \fB:-\fP expansion.
+.sp 1
 If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional
 parameters beginning at \fIoffset\fP.
+A negative \fIoffset\fP is taken relative to one greater than the greatest
+positional parameter, so an offset of -1 evaluates to the last positional
+parameter.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
 If \fIparameter\fP is an indexed array name subscripted by @ or *,
 the result is the \fIlength\fP
 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
 A negative \fIoffset\fP is taken relative to one greater than the maximum
 index of the specified array.
+It is an expansion error if \fIlength\fP evaluates to a number less than
+zero.
+.sp 1
 Substring expansion applied to an associative array produces undefined
 results.
-Note that a negative offset must be separated from the colon by at least
-one space to avoid being confused with the :- expansion.
+.sp 1
 Substring indexing is zero-based unless the positional parameters 
 are used, in which case the indexing starts at 1 by default.
 If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is