Improve documentation of [tcl::prefix].

3 files changed, 36 insertions, 26 deletions

diff --git a/ChangeLog b/ChangeLog
index a5fcbed..9f20624 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-10-19  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/prefix.n: Improved the documentation by fixing formatting,
+	adding good-practice recommendations and cross-references, etc.
+
 2008-10-17  Jan Nijtmans  <nijtmans@users.sf.net>
 
 	* generic/tclOO.decls:        CONST -> const.
diff --git a/doc/GetIndex.3 b/doc/GetIndex.3
index c0cf623..7d138eb 100644
--- a/doc/GetIndex.3
+++ b/doc/GetIndex.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetIndex.3,v 1.23 2008/10/04 11:04:42 nijtmans Exp $
+'\" RCS: @(#) $Id: GetIndex.3,v 1.24 2008/10/19 16:22:20 dkf Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetIndexFromObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -51,7 +51,6 @@ operation.  The only bit that is currently defined is \fBTCL_EXACT\fR.
 The index of the string in \fItablePtr\fR that matches the value of
 \fIobjPtr\fR is returned here.
 .BE
-
 .SH DESCRIPTION
 .PP
 This procedure provides an efficient way for looking up keywords,
@@ -95,9 +94,7 @@ array of characters at \fItablePtr\fR+\fIoffset\fR bytes, etc.)
 This is particularly useful when processing things like
 \fBTk_ConfigurationSpec\fR, whose string keys are in the same place in
 each of several array elements.
-
 .SH "SEE ALSO"
-Tcl_WrongNumArgs
-
+prefix(n), Tcl_WrongNumArgs(3)
 .SH KEYWORDS
 index, object, table lookup
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: