Added TIP#76 implementation, docs + tests.

1 files changed, 17 insertions, 8 deletions

diff --git a/doc/regsub.n b/doc/regsub.n
index 9fe54ab..6fa4bd0 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regsub.n,v 1.7 2001/11/28 13:15:31 dkf Exp $
+'\" RCS: @(#) $Id: regsub.n,v 1.8 2002/02/22 14:52:45 dkf Exp $
 '\" 
 .so man.macros
 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
@@ -15,18 +15,26 @@
 .SH NAME
 regsub \- Perform substitutions based on regular expression pattern matching
 .SH SYNOPSIS
-\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec varName\fR
+.VS 8.4
+\fBregsub \fR?\fIswitches\fR? \fIexp string subSpec \fR?\fIvarName\fR?
+.VE 8.4
 .BE
 
 .SH DESCRIPTION
 .PP
 This command matches the regular expression \fIexp\fR against
 \fIstring\fR,
-and it copies \fIstring\fR to the variable whose name is
-given by \fIvarName\fR.
+.VS 8.4
+and either copies \fIstring\fR to the variable whose name is
+given by \fIvarName\fR or returns \fIstring\fR if \fIvarName\fR is not
+present.
+.VE 8.4
 (Regular expression matching is described in the \fBre_syntax\fR
 reference page.)
 If there is a match, then while copying \fIstring\fR to \fIvarName\fR
+.VS 8.4
+(or to the result of this command if \fIvarName\fR is not present)
+.VE 8.4
 the portion of \fIstring\fR that
 matched \fIexp\fR is replaced with \fIsubSpec\fR.
 If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
@@ -87,7 +95,6 @@ manual page).
 Upper-case characters in \fIstring\fR will be converted to lower-case
 before matching against \fIexp\fR;  however, substitutions specified
 by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
-.VS 8.3
 .TP 10
 \fB\-start\fR \fIindex\fR
 Specifies a character index offset into the string to start
@@ -95,14 +102,16 @@ matching the regular expression at.  When using this switch, `^'
 will not match the beginning of the line, and \\A will still
 match the start of the string at \fIindex\fR.
 \fIindex\fR will be constrained to the bounds of the input string.
-.VE 8.3
 .TP 10
 \fB\-\|\-\fR
 Marks the end of switches.  The argument following this one will
 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 .PP
-The command returns a count of the number of matching ranges that
-were found and replaced.
+.VS 8.4
+If \fIvarName\fR is supplied, the command returns a count of the
+number of matching ranges that were found and replaced, otherwise the
+string after replacement is returned.
+.VE 8.4
 See the manual entry for \fBregexp\fR for details on the interpretation
 of regular expressions.