Documentation improvements, all minor.

1 files changed, 115 insertions, 124 deletions

diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n
index 1c70d67..b9599ad 100644
--- a/doc/ttk_widget.n
+++ b/doc/ttk_widget.n
@@ -1,11 +1,11 @@
 '\"
 '\" Copyright (c) 2004 Joe English
-'\" 
+'\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: ttk_widget.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $
-'\" 
+'\"
+'\" RCS: @(#) $Id: ttk_widget.n,v 1.4 2007/10/22 14:33:13 dkf Exp $
+'\"
 .so man.macros
 .TH ttk_widget n 8.5 Tk "Tk Themed Widget"
 .BS
@@ -19,83 +19,71 @@ This manual describes common widget options and commands.
 .SH "STANDARD OPTIONS"
 The following options are supported by all Tk themed widgets:
 .OP \-class undefined undefined
-Specifies the window class.
-The class is used when querying the option database 
-for the window's other options, to determine the default
-bindtags for the window, and to select the widget's default
-layout and style.
-This is a read-only option: 
-it may only be specified when the window is created,
-and may not be changed with the \fBconfigure\fR widget command.
+Specifies the window class. The class is used when querying the option
+database for the window's other options, to determine the default bindtags for
+the window, and to select the widget's default layout and style. This is a
+read-only option: it may only be specified when the window is created, and may
+not be changed with the \fBconfigure\fR widget command.
 .OP \-cursor cursor Cursor
-Specifies the mouse cursor to be used for the widget.
-See \fBTk_GetCursor\fR and \fIcursors(n)\fR in the Tk reference manual
-for the legal values.
-If set to the empty string (the default),
-the cursor is inherited from the parent widget.
+Specifies the mouse cursor to be used for the widget. See \fBTk_GetCursor\fR
+and \fIcursors(n)\fR in the Tk reference manual for the legal values. If set
+to the empty string (the default), the cursor is inherited from the parent
+widget.
 .OP \-takefocus takeFocus TakeFocus
-Determines whether the window accepts the focus during keyboard traversal.  
-Either \fB0\fR, \fB1\fR, a command prefix (to which the widget path
-is appended, and which should return \fB0\fR or \fB1\fR), 
-or the empty string.
+Determines whether the window accepts the focus during keyboard traversal.
+Either \fB0\fR, \fB1\fR, a command prefix (to which the widget path is
+appended, and which should return \fB0\fR or \fB1\fR), or the empty string.
 See \fIoptions(n)\fR in the Tk reference manual for the full description.
 .OP \-style style Style
 May be used to specify a custom widget style.
 
 .SH "SCROLLABLE WIDGET OPTIONS"
 .PP
-The following options are supported by widgets that
-are controllable by a scrollbar.  
-See \fIscrollbar(n)\fR for more information
+The following options are supported by widgets that are controllable by a
+scrollbar. See \fIscrollbar(n)\fR for more information
 .OP \-xscrollcommand xScrollCommand ScrollCommand
 A command prefix, used to communicate with horizontal scrollbars.
 .br
-When the view in the widget's window changes, the widget will
-generate a Tcl command by concatenating the scroll command and
-two numbers.
-Each of the numbers is a fraction between 0 and 1 indicating
-a position in the document; 0 indicates the beginning,
-and 1 indicates the end.
-The first fraction indicates the first information in the widget
-that is visible in the window, and the second fraction indicates
-the information just after the last portion that is visible.
+When the view in the widget's window changes, the widget will generate a Tcl
+command by concatenating the scroll command and two numbers. Each of the
+numbers is a fraction between 0 and 1 indicating a position in the document; 0
+indicates the beginning, and 1 indicates the end. The first fraction indicates
+the first information in the widget that is visible in the window, and the
+second fraction indicates the information just after the last portion that is
+visible.
 .br
-Typically the \fBxScrollCommand\fR option consists of the path name 
-of a \fBscrollbar\fR widget followed by ``set'', e.g. ``.x.scrollbar set''.
-This will cause the scrollbar to be updated whenever the view in the 
-window changes.
+Typically the \fBxScrollCommand\fR option consists of the path name of a
+\fBscrollbar\fR widget followed by ``set'', e.g. ``.x.scrollbar set''. This
+will cause the scrollbar to be updated whenever the view in the window
+changes.
 .br
-If this option is set to the empty string (the default),
-then no command is be executed.
+If this option is set to the empty string (the default), then no command is be
+executed.
 .OP \-yscrollcommand yScrollCommand ScrollCommand
-A command prefix, used to communicate with vertical scrollbars.
-See the description of \fB-xscrollcommand\fR above for details.
+A command prefix, used to communicate with vertical scrollbars. See the
+description of \fB\-xscrollcommand\fR above for details.
 
 .SH "LABEL OPTIONS"
-The following options are supported by labels, buttons,
-and other button-like widgets:
+The following options are supported by labels, buttons, and other button-like
+widgets:
 .OP \-text text Text
-Specifies a text string to be displayed inside the widget
-(unless overridden by \fB-textvariable\fR).
+Specifies a text string to be displayed inside the widget (unless overridden
+by \fB\-textvariable\fR).
 .OP \-textvariable textVariable Variable
-Specifies the name of variable whose value will be used
-in place of the \fB-text\fR resource.
+Specifies the name of variable whose value will be used in place of the
+\fB\-text\fR resource.
 .OP \-underline underline Underline
-If set, specifies the integer index (0-based) of a character to underline 
-in the text string.
-The underlined character is used for mnemonic activation.
+If set, specifies the integer index (0-based) of a character to underline in
+the text string. The underlined character is used for mnemonic activation.
 .OP \-image image Image
-Specifies an image to display.
-This is a list of 1 or more elements.
-The first element is the default image name.
-The rest of the list is a sequence of \fIstatespec / value\fR pairs
-as per \fBstyle map\fR, specifying different images to use when
-the widget is in a particular state or combination of states.
-All images in the list should have the same size.
+Specifies an image to display. This is a list of 1 or more elements. The first
+element is the default image name. The rest of the list is a sequence of
+\fIstatespec / value\fR pairs as per \fBstyle map\fR, specifying different
+images to use when the widget is in a particular state or combination of
+states. All images in the list should have the same size.
 .OP \-compound compound Compound
-Specifies how to display the image relative to the text,
-in the case both \fB-text\fR and \fB-image\fR are present.
-Valid values are: 
+Specifies how to display the image relative to the text, in the case both
+\fB\-text\fR and \fB\-image\fR are present. Valid values are:
 .RS
 .IP text
 Display text only.
@@ -112,123 +100,126 @@ Display image above, below, left of, or right of the text, respectively.
 The default; display the image if present, otherwise the text.
 .RE
 .OP \-width width Width
-If greater than zero, specifies how much space, in character widths, 
-to allocate for the text label.  
-If less than zero, specifies a minimum width.
-If zero or unspecified, the natural width of the text label is used.
+If greater than zero, specifies how much space, in character widths, to
+allocate for the text label. If less than zero, specifies a minimum width. If
+zero or unspecified, the natural width of the text label is used.
 
 .SH "COMPATIBILITY OPTIONS"
 .OP \-state state State
-May be set to \fBnormal\fR or \fBdisabled\fR
-to control the \fBdisabled\fR state bit.
-This is a ``write-only'' option: setting it changes the
-widget state, but the \fBstate\fR widget command does
-not affect the state option.
+May be set to \fBnormal\fR or \fBdisabled\fR to control the \fBdisabled\fR
+state bit. This is a ``write-only'' option: setting it changes the widget
+state, but the \fBstate\fR widget command does not affect the state option.
 
 .SH COMMANDS
 .TP
 \fIpathName \fBcget\fR \fIoption\fR
-Returns the current value of the configuration option given
-by \fIoption\fR.
+.
+Returns the current value of the configuration option given by \fIoption\fR.
 .TP
 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
-Query or modify the configuration options of the widget.
-If one or more \fIoption\-value\fR pairs are specified,
-then the command modifies the given widget option(s) 
-to have the given value(s); 
-in this case the command returns an empty string.
-If \fIoption\fR is specified with no \fIvalue\fR, 
-then the command returns a list describing the named option:
-the elements of the list are the 
-option name, database name, database class, default value, 
-and current value.
+.
+Query or modify the configuration options of the widget. If one or more
+\fIoption\-value\fR pairs are specified, then the command modifies the given
+widget option(s) to have the given value(s); in this case the command returns
+an empty string. If \fIoption\fR is specified with no \fIvalue\fR, then the
+command returns a list describing the named option: the elements of the list
+are the option name, database name, database class, default value, and current
+value.
 .\" Note: Ttk widgets don't use TK_OPTION_SYNONYM.
-If no \fIoption\fR is specified, returns a list describing all of
-the available options for \fIpathName\fR.
-.TP 
+If no \fIoption\fR is specified, returns a list describing all of the
+available options for \fIpathName\fR.
+.TP
 \fIpathName \fBinstate\fR \fIstatespec\fR ?\fIscript\fR?
-Test the widget's state.
-If \fIscript\fR is not specified, returns 1 if 
-the widget state matches \fIstatespec\fR and 0 otherwise.
-If \fIscript\fR is specified, equivalent to
+.
+Test the widget's state. If \fIscript\fR is not specified, returns 1 if the
+widget state matches \fIstatespec\fR and 0 otherwise.  If \fIscript\fR is
+specified, equivalent to
+.RS
 .CS
 if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR
 .CE
-.TP 
+.RE
+.TP
 \fIpathName \fBstate\fR ?\fIstateSpec\fR
-Modify or inquire widget state.
-If \fIstateSpec\fR is present, sets the widget state: 
-for each flag in \fIstateSpec\fR, sets the corresponding flag
-or clears it if prefixed by an exclamation point.
-Returns a new state spec indicating which flags were changed:
+.
+Modify or inquire widget state. If \fIstateSpec\fR is present, sets the widget
+state: for each flag in \fIstateSpec\fR, sets the corresponding flag or clears
+it if prefixed by an exclamation point. Returns a new state spec indicating
+which flags were changed:
+.RS
 .CS
 set changes [\fIpathName \fRstate \fIspec\fR]
 \fIpathName \fRstate $changes
 .CE
-will restore \fIpathName\fR to the original state.
-If \fIstateSpec\fR is not specified, 
-returns a list of the currently-enabled state flags.
+will restore \fIpathName\fR to the original state. If \fIstateSpec\fR is not
+specified, returns a list of the currently-enabled state flags.
+.RE
 .SH "WIDGET STATES"
-The widget state is a bitmap of independent state flags.
-Widget state flags include:
+The widget state is a bitmap of independent state flags. Widget state flags
+include:
 .TP
 \fBactive\fR
-The mouse cursor is over the widget 
-and pressing a mouse button will cause some action to occur.
-(aka "prelight" (Gnome), "hot" (Windows), "hover").
+.
+The mouse cursor is over the widget and pressing a mouse button will cause
+some action to occur. (aka "prelight" (Gnome), "hot" (Windows), "hover").
 .TP
 \fBdisabled\fR
-Widget is disabled under program control 
-(aka "unavailable", "inactive") 
+.
+Widget is disabled under program control (aka "unavailable", "inactive")
 .TP
 \fBfocus\fR
-Widget has keyboard focus 
+.
+Widget has keyboard focus.
 .TP
 \fBpressed\fR
-Widget is being pressed (aka "armed" in Motif). 
+.
+Widget is being pressed (aka "armed" in Motif).
 .TP
 \fBselected\fR
-"On", "true", or "current" for things like checkbuttons and radiobuttons. 
+.
+The widget is "On", "true", or "current" (for things like checkbuttons and
+radiobuttons).
 .TP
 \fBbackground\fR
-Windows and the Mac have a notion of an "active" or foreground window.
-The \fBbackground\fR state is set for widgets in a background window,
-and cleared for those in the foreground window.
+.
+Windows and the Mac have a notion of an "active" or foreground window. The
+\fBbackground\fR state is set for widgets in a background window, and cleared
+for those in the foreground window.
 .TP
 \fBreadonly\fR
+.
 Widget should not allow user modification.
 .TP
 \fBalternate\fR
-A widget-specific alternate display format.
-For example, used for checkbuttons and radiobuttons 
-in the "tristate" or "mixed" state,
-and for buttons with \fB-default active\fR.
+.
+A widget-specific alternate display format. For example, used for checkbuttons
+and radiobuttons in the "tristate" or "mixed" state, and for buttons with
+\fB\-default active\fR.
 .TP
 \fBinvalid\fR
-The widget's value is invalid.
-(Potential uses: scale widget value out of bounds, 
-entry widget value failed validation.)
+.
+The widget's value is invalid. (Potential uses: scale widget value out of
+bounds, entry widget value failed validation.)
 .PP
-A \fIstate specification\fR or \fIstateSpec\fR is a list
-of state names, optionally prefixed with an exclamation point (!)
-indicating that the bit is off.
+A \fIstate specification\fR or \fIstateSpec\fR is a list of state names,
+optionally prefixed with an exclamation point (!) indicating that the bit is
+off.
 
 .SH EXAMPLES
 .CS
 set b [ttk::button .b]
 
 # Disable the widget:
-$b state disabled			
+$b state disabled
 
 # Invoke the widget only if it is currently pressed and enabled:
-$b instate {pressed !disabled} { .b invoke }	
+$b instate {pressed !disabled} { .b invoke }
 
 # Reenable widget:
-$b state !disabled			
+$b state !disabled
 .CE
 
 .SH "SEE ALSO"
 ttk_intro(n), style(n)
-
 .SH KEYWORDS
 state, configure, option