summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2008-10-19 16:22:20 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2008-10-19 16:22:20 (GMT)
commit89675f56467f3a8c563caaf05cbd38f46feabfe2 (patch)
treeefef6375c3ed01e45afde70a90cd08055df9b724
parent103fdf84aa05fef3d37b5a2178fc75eefe64375b (diff)
downloadtcl-89675f56467f3a8c563caaf05cbd38f46feabfe2.zip
tcl-89675f56467f3a8c563caaf05cbd38f46feabfe2.tar.gz
tcl-89675f56467f3a8c563caaf05cbd38f46feabfe2.tar.bz2
Improve documentation of [tcl::prefix].
-rw-r--r--ChangeLog5
-rw-r--r--doc/GetIndex.37
-rw-r--r--doc/prefix.n50
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: