Clarify descriptions of some operations; it's not always clear that

strings are not actually modified.  Problem reported by Dr. Peter
Stoehr <peter.stoehr@weihenstephan.org>.

1 files changed, 107 insertions, 103 deletions

diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index f7189fd..4bf2903 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -57,187 +57,191 @@ The functions defined in this module are:
 
 
 \begin{funcdesc}{atof}{s}
-Convert a string to a floating point number.  The string must have
-the standard syntax for a floating point literal in Python, optionally
-preceded by a sign (\samp{+} or \samp{-}).  Note that this behaves
-identical to the built-in function
-\function{float()}\bifuncindex{float} when passed a string.
+  Convert a string to a floating point number.  The string must have
+  the standard syntax for a floating point literal in Python,
+  optionally preceded by a sign (\samp{+} or \samp{-}).  Note that
+  this behaves identical to the built-in function
+  \function{float()}\bifuncindex{float} when passed a string.
 \end{funcdesc}
 
 \begin{funcdesc}{atoi}{s\optional{, base}}
-Convert string \var{s} to an integer in the given \var{base}.  The
-string must consist of one or more digits, optionally preceded by a
-sign (\samp{+} or \samp{-}).  The \var{base} defaults to 10.  If it is
-0, a default base is chosen depending on the leading characters of the
-string (after stripping the sign): \samp{0x} or \samp{0X} means 16,
-\samp{0} means 8, anything else means 10.  If \var{base} is 16, a
-leading \samp{0x} or \samp{0X} is always accepted.  Note that when
-invoked without \var{base} or with \var{base} set to 10, this behaves
-identical to the built-in function \function{int()} when passed a string.
-(Also note: for a more flexible interpretation of numeric literals,
-use the built-in function \function{eval()}\bifuncindex{eval}.)
+  Convert string \var{s} to an integer in the given \var{base}.  The
+  string must consist of one or more digits, optionally preceded by a
+  sign (\samp{+} or \samp{-}).  The \var{base} defaults to 10.  If it
+  is 0, a default base is chosen depending on the leading characters
+  of the string (after stripping the sign): \samp{0x} or \samp{0X}
+  means 16, \samp{0} means 8, anything else means 10.  If \var{base}
+  is 16, a leading \samp{0x} or \samp{0X} is always accepted.  Note
+  that when invoked without \var{base} or with \var{base} set to 10,
+  this behaves identical to the built-in function \function{int()}
+  when passed a string.  (Also note: for a more flexible
+  interpretation of numeric literals, use the built-in function
+  \function{eval()}\bifuncindex{eval}.)
 \end{funcdesc}
 
 \begin{funcdesc}{atol}{s\optional{, base}}
-Convert string \var{s} to a long integer in the given \var{base}.  The 
-string must consist of one or more digits, optionally preceded by a
-sign (\samp{+} or \samp{-}).  The \var{base} argument has the same
-meaning as for \function{atoi()}.  A trailing \samp{l} or \samp{L} is
-not allowed, except if the base is 0.  Note that when invoked without
-\var{base} or with \var{base} set to 10, this behaves identical to the
-built-in function \function{long()}\bifuncindex{long} when passed a
-string.
+  Convert string \var{s} to a long integer in the given \var{base}.
+  The string must consist of one or more digits, optionally preceded
+  by a sign (\samp{+} or \samp{-}).  The \var{base} argument has the
+  same meaning as for \function{atoi()}.  A trailing \samp{l} or
+  \samp{L} is not allowed, except if the base is 0.  Note that when
+  invoked without \var{base} or with \var{base} set to 10, this
+  behaves identical to the built-in function
+  \function{long()}\bifuncindex{long} when passed a string.
 \end{funcdesc}
 
 \begin{funcdesc}{capitalize}{word}
-Capitalize the first character of the argument.
+  Capitalize the first character of the argument.
 \end{funcdesc}
 
 \begin{funcdesc}{capwords}{s}
-Split the argument into words using \function{split()}, capitalize
-each word using \function{capitalize()}, and join the capitalized
-words using \function{join()}.  Note that this replaces runs of
-whitespace characters by a single space, and removes leading and
-trailing whitespace.
+  Split the argument into words using \function{split()}, capitalize
+  each word using \function{capitalize()}, and join the capitalized
+  words using \function{join()}.  Note that this replaces runs of
+  whitespace characters by a single space, and removes leading and
+  trailing whitespace.
 \end{funcdesc}
 
 \begin{funcdesc}{expandtabs}{s, tabsize}
-Expand tabs in a string, i.e.\ replace them by one or more spaces,
-depending on the current column and the given tab size.  The column
-number is reset to zero after each newline occurring in the string.
-This doesn't understand other non-printing characters or escape
-sequences.
+  Expand tabs in a string, i.e.\ replace them by one or more spaces,
+  depending on the current column and the given tab size.  The column
+  number is reset to zero after each newline occurring in the string.
+  This doesn't understand other non-printing characters or escape
+  sequences.
 \end{funcdesc}
 
 \begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}}
-Return the lowest index in \var{s} where the substring \var{sub} is
-found such that \var{sub} is wholly contained in
-\code{\var{s}[\var{start}:\var{end}]}.  Return \code{-1} on failure.
-Defaults for \var{start} and \var{end} and interpretation of negative
-values is the same as for slices.
+  Return the lowest index in \var{s} where the substring \var{sub} is
+  found such that \var{sub} is wholly contained in
+  \code{\var{s}[\var{start}:\var{end}]}.  Return \code{-1} on failure.
+  Defaults for \var{start} and \var{end} and interpretation of
+  negative values is the same as for slices.
 \end{funcdesc}
 
 \begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
-Like \function{find()} but find the highest index.
+  Like \function{find()} but find the highest index.
 \end{funcdesc}
 
 \begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}}
-Like \function{find()} but raise \exception{ValueError} when the
-substring is not found.
+  Like \function{find()} but raise \exception{ValueError} when the
+  substring is not found.
 \end{funcdesc}
 
 \begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
-Like \function{rfind()} but raise \exception{ValueError} when the
-substring is not found.
+  Like \function{rfind()} but raise \exception{ValueError} when the
+  substring is not found.
 \end{funcdesc}
 
 \begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}}
-Return the number of (non-overlapping) occurrences of substring
-\var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
-Defaults for \var{start} and \var{end} and interpretation of negative
-values is the same as for slices.
+  Return the number of (non-overlapping) occurrences of substring
+  \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
+  Defaults for \var{start} and \var{end} and interpretation of
+  negative values is the same as for slices.
 \end{funcdesc}
 
 \begin{funcdesc}{lower}{s}
-Convert letters to lower case.
+  Return a copy of \var{s}, but with upper case letters converted to
+  lower case.
 \end{funcdesc}
 
 \begin{funcdesc}{maketrans}{from, to}
-Return a translation table suitable for passing to
-\function{translate()} or \function{regex.compile()}, that will map
-each character in \var{from} into the character at the same position
-in \var{to}; \var{from} and \var{to} must have the same length. 
+  Return a translation table suitable for passing to
+  \function{translate()} or \function{regex.compile()}, that will map
+  each character in \var{from} into the character at the same position
+  in \var{to}; \var{from} and \var{to} must have the same length.
 
-\strong{Warning:} don't use strings derived from \code{lowercase} and
-\code{uppercase} as arguments; in some locales, these don't have the
-same length.  For case conversions, always use \function{lower()} and
-\function{upper()}.
+  \strong{Warning:} don't use strings derived from \code{lowercase}
+  and \code{uppercase} as arguments; in some locales, these don't have
+  the same length.  For case conversions, always use
+  \function{lower()} and \function{upper()}.
 \end{funcdesc}
 
 \begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
-Return a list of the words of the string \var{s}.  If the optional
-second argument \var{sep} is absent or \code{None}, the words are
-separated by arbitrary strings of whitespace characters (space, tab,
-newline, return, formfeed).  If the second argument \var{sep} is
-present and not \code{None}, it specifies a string to be used as the
-word separator.  The returned list will then have one more items than
-the number of non-overlapping occurrences of the separator in the
-string.  The optional third argument \var{maxsplit} defaults to 0.  If
-it is nonzero, at most \var{maxsplit} number of splits occur, and the
-remainder of the string is returned as the final element of the list
-(thus, the list will have at most \code{\var{maxsplit}+1} elements).
+  Return a list of the words of the string \var{s}.  If the optional
+  second argument \var{sep} is absent or \code{None}, the words are
+  separated by arbitrary strings of whitespace characters (space, tab, 
+  newline, return, formfeed).  If the second argument \var{sep} is
+  present and not \code{None}, it specifies a string to be used as the 
+  word separator.  The returned list will then have one more items
+  than the number of non-overlapping occurrences of the separator in
+  the string.  The optional third argument \var{maxsplit} defaults to
+  0.  If it is nonzero, at most \var{maxsplit} number of splits occur,
+  and the remainder of the string is returned as the final element of
+  the list (thus, the list will have at most \code{\var{maxsplit}+1}
+  elements).
 \end{funcdesc}
 
 \begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}}
-This function behaves identically to \function{split()}.  (In the
-past, \function{split()} was only used with one argument, while
-\function{splitfields()} was only used with two arguments.)
+  This function behaves identically to \function{split()}.  (In the
+  past, \function{split()} was only used with one argument, while
+  \function{splitfields()} was only used with two arguments.)
 \end{funcdesc}
 
 \begin{funcdesc}{join}{words\optional{, sep}}
-Concatenate a list or tuple of words with intervening occurrences of
-\var{sep}.  The default value for \var{sep} is a single space
-character.  It is always true that
-\samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
-equals \var{s}.
+  Concatenate a list or tuple of words with intervening occurrences of 
+  \var{sep}.  The default value for \var{sep} is a single space
+  character.  It is always true that
+  \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
+  equals \var{s}.
 \end{funcdesc}
 
 \begin{funcdesc}{joinfields}{words\optional{, sep}}
-This function behaves identical to \function{join()}.  (In the past,
-\function{join()} was only used with one argument, while
-\function{joinfields()} was only used with two arguments.)
+  This function behaves identical to \function{join()}.  (In the past, 
+  \function{join()} was only used with one argument, while
+  \function{joinfields()} was only used with two arguments.)
 \end{funcdesc}
 
 \begin{funcdesc}{lstrip}{s}
-Remove leading whitespace from the string \var{s}.
+  Return a copy of \var{s} but without leading whitespace characters.
 \end{funcdesc}
 
 \begin{funcdesc}{rstrip}{s}
-Remove trailing whitespace from the string \var{s}.
+  Return a copy of \var{s} but without trailing whitespace
+  characters.
 \end{funcdesc}
 
 \begin{funcdesc}{strip}{s}
-Remove leading and trailing whitespace from the string \var{s}.
+  Return a copy of \var{s} without leading or trailing whitespace.
 \end{funcdesc}
 
 \begin{funcdesc}{swapcase}{s}
-Convert lower case letters to upper case and vice versa.
+  Return a copy of \var{s}, but with lower case letters
+  converted to upper case and vice versa.
 \end{funcdesc}
 
 \begin{funcdesc}{translate}{s, table\optional{, deletechars}}
-Delete all characters from \var{s} that are in \var{deletechars} (if
-present), and then translate the characters using \var{table}, which
-must be a 256-character string giving the translation for each
-character value, indexed by its ordinal.  
+  Delete all characters from \var{s} that are in \var{deletechars} (if 
+  present), and then translate the characters using \var{table}, which 
+  must be a 256-character string giving the translation for each
+  character value, indexed by its ordinal.  
 \end{funcdesc}
 
 \begin{funcdesc}{upper}{s}
-Convert letters to upper case.
+  Return a copy of \var{s}, but with lower case letters converted to
+  upper case.
 \end{funcdesc}
 
 \begin{funcdesc}{ljust}{s, width}
 \funcline{rjust}{s, width}
 \funcline{center}{s, width}
-These functions respectively left-justify, right-justify and center a
-string in a field of given width.
-They return a string that is at least
-\var{width}
-characters wide, created by padding the string
-\var{s}
-with spaces until the given width on the right, left or both sides.
-The string is never truncated.
+  These functions respectively left-justify, right-justify and center
+  a string in a field of given width.  They return a string that is at
+  least \var{width} characters wide, created by padding the string
+  \var{s} with spaces until the given width on the right, left or both
+  sides.  The string is never truncated.
 \end{funcdesc}
 
 \begin{funcdesc}{zfill}{s, width}
-Pad a numeric string on the left with zero digits until the given
-width is reached.  Strings starting with a sign are handled correctly.
+  Pad a numeric string on the left with zero digits until the given
+  width is reached.  Strings starting with a sign are handled
+  correctly.
 \end{funcdesc}
 
 \begin{funcdesc}{replace}{str, old, new\optional{, maxsplit}}
-Return a copy of string \var{str} with all occurrences of substring
-\var{old} replaced by \var{new}.  If the optional argument
-\var{maxsplit} is given, the first \var{maxsplit} occurrences are
-replaced.
+  Return a copy of string \var{str} with all occurrences of substring
+  \var{old} replaced by \var{new}.  If the optional argument
+  \var{maxsplit} is given, the first \var{maxsplit} occurrences are
+  replaced.
 \end{funcdesc}
 
 This module is implemented in Python.  Much of its functionality has