Improve documentation of [tcl::prefix].

1 files changed, 29 insertions, 21 deletions

diff --git a/doc/prefix.n b/doc/prefix.n
index 6247583..927318a 100644
--- a/doc/prefix.n
+++ b/doc/prefix.n
@@ -4,14 +4,14 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: prefix.n,v 1.3 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: prefix.n,v 1.4 2008/10/19 16:22:20 dkf Exp $
 '\" 
 .so man.macros
 .TH prefix n 8.6 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-prefix \- Facilities for prefix matching
+prefix \- facilities for prefix matching
 .SH SYNOPSIS
 .nf
 \fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
@@ -26,28 +26,33 @@ The following commands are supported:
 .TP
 \fB::tcl::prefix all\fR \fItable\fR \fIstring\fR
 .
-Returns a list of all elements in \fItable\fR that begins with
-the prefix \fIstring\fR.
+Returns a list of all elements in \fItable\fR that begin with the prefix
+\fIstring\fR.
 .TP
 \fB::tcl::prefix longest\fR \fItable\fR \fIstring\fR
 .
-Returns the longest common prefix among all elements in \fItable\fR that
-begins with the prefix \fIstring\fR.
+Returns the longest common prefix of all elements in \fItable\fR that
+begin with the prefix \fIstring\fR.
 .TP
 \fB::tcl::prefix match\fR ?\fIoptions\fR? \fItable\fR \fIstring\fR
 .
 If \fIstring\fR equals one element in \fItable\fR or is a prefix to exactly
-one element, the matched element is returned.  If not, the result depends
-on the \fB\-error\fR option.
-.TP 20
-\fB\-exact\fR
+one element, the matched element is returned. If not, the result depends
+on the \fB\-error\fR option. (It is recommended that the \fItable\fR be sorted
+before use with this subcommand, so that the list of matches presented in the
+error message also becomes sorted, though this is not strictly necessary for
+the operation of this subcommand itself.)
+.RS
+.TP
+\fB\-exact\fR\0
 .
 Accept only exact matches.
-.TP 20
+.TP
 \fB\-message\0\fIstring\fR
 .
-Use \fIstring\fR in the error message at a mismatch. Default is "option".
-.TP 20
+Use \fIstring\fR in the error message at a mismatch. Default is
+.QW option .
+.TP
 \fB\-error\0\fIoptions\fR
 .
 The \fIoptions\fR are used when no match is found. If \fIoptions\fR is empty,
@@ -55,14 +60,17 @@ no error is generated and an empty string is returned. Otherwise the
 \fIoptions\fR are used as \fBreturn\fR options when generating the error
 message. The default corresponds to setting
 .QW "\-level 0" .
-Example: If \fB\-error\fR "\-errorcode MyError \-level 1" is used, an
-error would be generated as:
+Example: If
+.QW "\fB\-error\fR {\-errorcode MyError \-level 1}"
+is used, an error would be generated as:
 .RS
 .PP
 .CS
-return \-errorcode MyError \-level 1 \-code error "ErrMsg"
+return \-errorcode MyError \-level 1 \-code error \e
+       "ambiguous option ..."
 .CE
 .RE
+.RE
 .SH "EXAMPLES"
 .PP
 Basic use:
@@ -88,23 +96,23 @@ Simplifying option matching:
 .CS
 array set opts {\-apa 1 \-bepa "" \-cepa 0}
 foreach {arg val} $args {
-    set opts([prefix match {\-apa \-bepa \-cepa} $arg]) $val
+    set opts([\fBprefix match\fR {\-apa \-bepa \-cepa} $arg]) $val
 }
 .CE
 .PP
-Switch supporting prefixes:
+Creating a \fBswitch\fR that supports prefixes:
 .PP
 .CS
-switch [prefix match {apa bepa cepa} $arg] {
+switch [\fBprefix match\fR {apa bepa cepa} $arg] {
     apa  { }
     bepa { }
     cepa { }
 }
 .CE
 .SH "SEE ALSO"
-lsearch(n)
+lsearch(n), namespace(n), string(n), Tcl_GetIndexFromObj(3)
 .SH "KEYWORDS"
-prefix
+prefix, table lookup
 '\" Local Variables:
 '\" mode: nroff
 '\" End: