[Bug 2914943]: Correct the first option(n) example.

Also define what the format of option patterns is; that's a much less
commonly known fact than it used to be.

2 files changed, 51 insertions, 15 deletions

diff --git a/ChangeLog b/ChangeLog
index a4bba57..61e528d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,14 +1,20 @@
+2009-12-25  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/option.n: [Bug 2914943]: Correct the first example.
+	Also define what the format of option patterns is; that's a much less
+	commonly known fact than it used to be.
+
 2009-12-22  Jan Nijtmans  <nijtmans@users.sf.net>
 
-    * unix/tcl.m4           Sync with current Tcl version
-    * unix/Makefile.in      Use EXE_SUFFIX for Cygwin, and
-                            install libtk8.6.dll in bin directory
-    * unix/configure        (regenerated)
+	* unix/tcl.m4:		Sync with current Tcl version.
+	* unix/Makefile.in:	Use EXE_SUFFIX for Cygwin, and install
+				libtk8.6.dll in bin directory.
+	* unix/configure:	(regenerated)
 
 2009-12-22  Joe English  <jenglish@users.sourceforge.net>
 	
-	* library/ttk/sizegrip.tcl: Patch to avoid bizarro behavior
-	under compiz [Bug 2912356].
+	* library/ttk/sizegrip.tcl: [Bug 2912356]: Patch to avoid bizarro
+	behavior under compiz.
 
 2009-12-20  Donal K. Fellows  <dkf@users.sf.net>
 
@@ -17,10 +23,11 @@
 
 2009-12-16  Jan Nijtmans  <nijtmans@users.sf.net>
 
-	* generic/tkListbox.c:	Fix gcc warning: ignoring return value of "strtol",
-	                        declared with attribute warn_unused_result.
-	* unix/tkUnixEvent.c:   Fix gcc warning: dereferencing pointer "xgePtr" does
-	                        break strict-aliasing rules.
+	* generic/tkListbox.c:	Fix gcc warning: ignoring return value of
+				"strtol", declared with attribute
+				warn_unused_result.
+	* unix/tkUnixEvent.c:   Fix gcc warning: dereferencing pointer
+				"xgePtr" does break strict-aliasing rules.
 	* generic/tkInt.decls:  CONSTify return values of TkKeysymToString,
 	* generic/tkBind.c      TkFindStateString, TkpGetString, TkpGetChar,
 	* generic/tkIntDecls.h  which are all not supposed to be modified by
diff --git a/doc/option.n b/doc/option.n
index 93e0bdb..083e05e 100644
--- a/doc/option.n
+++ b/doc/option.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: option.n,v 1.9 2008/09/23 13:36:45 dkf Exp $
+'\" RCS: @(#) $Id: option.n,v 1.10 2009/12/25 18:21:30 dkf Exp $
 '\" 
 .so man.macros
 .TH option n "" Tk "Tk Built-In Commands"
@@ -28,7 +28,8 @@ database or to retrieve options from the database.  The \fBadd\fR
 form of the command adds a new option to the database.
 \fIPattern\fR contains
 the option being specified, and consists of names and/or classes
-separated by asterisks or dots, in the usual X format.  \fIValue\fR
+separated by asterisks or dots, in the usual X format (see \fBPATTERN
+FORMAT\fR).  \fIValue\fR
 contains a text string to associate with \fIpattern\fR;  this is the
 value that will be returned in calls to \fBTk_GetOption\fR or by
 invocations of the \fBoption get\fR command.  If \fIpriority\fR
@@ -79,17 +80,43 @@ the X server, or user-specific startup files.
 Level 80.  Used for options specified interactively after the application
 starts running.  If \fIpriority\fR is not specified, it defaults to
 this level.
-.LP
+.PP
 Any of the above keywords may be abbreviated.  In addition, priorities
 may be specified numerically using integers between 0 and 100,
 inclusive.  The numeric form is probably a bad idea except for new priority
 levels other than the ones given above.
+.SH "PATTERN FORMAT"
+.PP
+Patterns consist of a sequence of words separated by either periods,
+.QW . ,
+or asterisks
+.QW * .
+The overall pattern may also be optionally preceded by an asterisk.
+.PP
+Each word in the pattern conventionally starts with either an upper-case
+letter (in which case it denotes the class of either a widget or an option) or
+any other character, when it denotes the name of a widget or option. The last
+word in the pattern always indicates the option; the preceding ones constrain
+which widgets that option will be looked for in.
+.PP
+When two words are separated by a period, the latter widget must be a direct
+child of the former (or the option must apply to only the indicated widgets).
+When two words are separated by an asterisk, any depth of widgets may lie
+between the former and latter widgets (and the option applies to all widgets
+that are children of the former widget).
+.PP
+If the overall pattern is preceded by an asterisk, then the overall pattern
+applies anywhere it can throughout the whole widget hierarchy. Otherwise the
+first word of the pattern is matched against the name and class of the
+.QW \fB.\fR
+\fBtoplevel\fR, which are usually set by options to \fBwish\fR.
 .SH EXAMPLES
 .PP
 Instruct every button in the application to have red text on it unless
-explicitly overridden:
+explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR
+class (note that on some platforms the option is ignored):
 .CS
-\fBoption add\fR *button.foreground red startupFile
+\fBoption add\fR *Button.foreground red startupFile
 .CE
 .PP
 Allow users to control what happens in an entry widget when the Return
@@ -100,6 +127,8 @@ entry .e
 bind .e <Return> [\fBoption get\fR .e returnCommand Command]
 \fBoption add\fR *.e.returnCommand bell widgetDefault
 .CE
+.SH "SEE ALSO"
+options(n), wish(1)
 .SH KEYWORDS
 database, option, priority, retrieve
 '\" Local Variables: