From 89675f56467f3a8c563caaf05cbd38f46feabfe2 Mon Sep 17 00:00:00 2001 From: dkf Date: Sun, 19 Oct 2008 16:22:20 +0000 Subject: Improve documentation of [tcl::prefix]. --- ChangeLog | 5 +++++ doc/GetIndex.3 | 7 ++----- doc/prefix.n | 50 +++++++++++++++++++++++++++++--------------------- 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 + + * doc/prefix.n: Improved the documentation by fixing formatting, + adding good-practice recommendations and cross-references, etc. + 2008-10-17 Jan Nijtmans * 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: -- cgit v0.12