Documentation tweaks to make index entries more informative.

19 files changed, 35 insertions, 20 deletions

diff --git a/doc/button.n b/doc/button.n
index d4f1af3..f201dc4 100644
--- a/doc/button.n
+++ b/doc/button.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-button \- Create and manipulate button widgets
+button \- Create and manipulate 'button' action widgets
 .SH SYNOPSIS
 \fBbutton\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/canvas.n b/doc/canvas.n
index 9eb0ec0..f69a3df 100644
--- a/doc/canvas.n
+++ b/doc/canvas.n
@@ -11,7 +11,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-canvas \- Create and manipulate canvas widgets
+canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets
 .SH SYNOPSIS
 \fBcanvas\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/checkbutton.n b/doc/checkbutton.n
index 4d06c68..eca0b72 100644
--- a/doc/checkbutton.n
+++ b/doc/checkbutton.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-checkbutton \- Create and manipulate checkbutton widgets
+checkbutton \- Create and manipulate 'checkbutton' boolean selection widgets
 .SH SYNOPSIS
 \fBcheckbutton\fI pathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/dialog.n b/doc/dialog.n
index bd40321..5b760f1 100644
--- a/doc/dialog.n
+++ b/doc/dialog.n
@@ -17,6 +17,7 @@ tk_dialog \- Create modal dialog and wait for response
 .SH DESCRIPTION
 .PP
 This procedure is part of the Tk script library.
+It is largely \fIdeprecated\fR by the \fBtk_messageBox\fR.
 Its arguments describe a dialog box:
 .TP
 \fIwindow\fR
diff --git a/doc/entry.n b/doc/entry.n
index b115268..868dc1d 100644
--- a/doc/entry.n
+++ b/doc/entry.n
@@ -11,7 +11,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-entry \- Create and manipulate entry widgets
+entry \- Create and manipulate 'entry' one-line text entry widgets
 .SH SYNOPSIS
 \fBentry\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/frame.n b/doc/frame.n
index 6bf4a1b..d6e2202 100644
--- a/doc/frame.n
+++ b/doc/frame.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-frame \- Create and manipulate frame widgets
+frame \- Create and manipulate 'frame' simple container widgets
 .SH SYNOPSIS
 \fBframe\fR \fIpathName\fR ?\fIoptions\fR?
 .SO
diff --git a/doc/label.n b/doc/label.n
index e445ebb..a0db8c0 100644
--- a/doc/label.n
+++ b/doc/label.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-label \- Create and manipulate label widgets
+label \- Create and manipulate 'label' non-interactive text or image widgets
 .SH SYNOPSIS
 \fBlabel\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/labelframe.n b/doc/labelframe.n
index 2bb865d..8f989fe 100644
--- a/doc/labelframe.n
+++ b/doc/labelframe.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-labelframe \- Create and manipulate labelframe widgets
+labelframe \- Create and manipulate 'labelframe' labelled container widgets
 .SH SYNOPSIS
 \fBlabelframe\fR \fIpathName\fR ?\fIoptions\fR?
 .SO
diff --git a/doc/listbox.n b/doc/listbox.n
index 709b702..a7fddfc 100644
--- a/doc/listbox.n
+++ b/doc/listbox.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-listbox \- Create and manipulate listbox widgets
+listbox \- Create and manipulate 'listbox' item list widgets
 .SH SYNOPSIS
 \fBlistbox\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/menu.n b/doc/menu.n
index c6f74dc..b026844 100644
--- a/doc/menu.n
+++ b/doc/menu.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-menu, tk_menuSetFocus \- Create and manipulate menu widgets
+menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars
 .SH SYNOPSIS
 .nf
 \fBmenu\fR \fIpathName \fR?\fIoptions\fR?
@@ -73,6 +73,9 @@ library.
 .PP
 The \fBmenu\fR command creates a new top-level window (given
 by the \fIpathName\fR argument) and makes it into a menu widget.
+That menu widget can either be used as a pop-up window or applied to a
+\fBtoplevel\fR (with its \fB\-menu\fR option) to make it into the menubar for
+that toplevel.
 Additional
 options, described above, may be specified on the command line
 or in the option database
diff --git a/doc/menubutton.n b/doc/menubutton.n
index c8b0958..6b723ff 100644
--- a/doc/menubutton.n
+++ b/doc/menubutton.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-menubutton \- Create and manipulate menubutton widgets
+menubutton \- Create and manipulate 'menubutton' pop-up menu indicator widgets
 .SH SYNOPSIS
 \fBmenubutton\fR \fIpathName \fR?\fIoptions\fR?
 .SO
@@ -93,13 +93,19 @@ the menu before releasing the mouse button, the button release
 causes the underlying menu entry to be invoked.  When the button
 is released, the menu is unposted.
 .PP
-Menubuttons are typically organized into groups called menu bars
+Menubuttons are used to construct a \fBtk_optionMenu\fR, which is the
+preferred mechanism for allowing a user to select one item from a list
+on Mac OS X.
+.PP
+Menubuttons were also typically organized into groups called menu bars
 that allow scanning:
 if the mouse button is pressed over one menubutton (causing it
 to post its menu) and the mouse is moved over another menubutton
 in the same menu bar without releasing the mouse button, then the
 menu of the first menubutton is unposted and the menu of the
 new menubutton is posted instead.
+\fIThis use is deprecated\fR in favor of setting a \fBmenu\fR directly as a
+menubar; see the \fBtoplevel\fR's \fB\-menu\fR option for how to do that.
 .PP
 There are several interactions between menubuttons and menus;  see
 the \fBmenu\fR manual entry for information on various menu configurations,
@@ -118,12 +124,14 @@ determine the exact behavior of the command.  The following
 commands are possible for menubutton widgets:
 .TP
 \fIpathName \fBcget \fIoption\fR
+.
 Returns the current value of the configuration option given
 by \fIoption\fR.
 \fIOption\fR may have any of the values accepted by the \fBmenubutton\fR
 command.
 .TP
 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
+.
 Query or modify the configuration options of the widget.
 If no \fIoption\fR is specified, returns a list describing all of
 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
diff --git a/doc/message.n b/doc/message.n
index 61be2f0..7fb4d04 100644
--- a/doc/message.n
+++ b/doc/message.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-message \- Create and manipulate message widgets
+message \- Create and manipulate 'message' non-interactive text widgets
 .SH SYNOPSIS
 \fBmessage\fR \fIpathName \fR?\fIoptions\fR?
 .SO
@@ -74,7 +74,8 @@ there must not exist a window named \fIpathName\fR, but
 \fIpathName\fR's parent must exist.
 .PP
 A message is a widget that displays a textual string.  A message
-widget has three special features.  First, it breaks up
+widget has three special features that differentiate it from a
+\fBlabel\fR widget.  First, it breaks up
 its string into lines in order to produce a given aspect ratio
 for the window.  The line breaks are chosen at word boundaries
 wherever possible (if not even a single word would fit on a
@@ -112,12 +113,14 @@ determine the exact behavior of the command.  The following
 commands are possible for message widgets:
 .TP
 \fIpathName \fBcget \fIoption\fR
+.
 Returns the current value of the configuration option given
 by \fIoption\fR.
 \fIOption\fR may have any of the values accepted by the \fBmessage\fR
 command.
 .TP
 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
+.
 Query or modify the configuration options of the widget.
 If no \fIoption\fR is specified, returns a list describing all of
 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
diff --git a/doc/panedwindow.n b/doc/panedwindow.n
index 17d5730..6ece441 100644
--- a/doc/panedwindow.n
+++ b/doc/panedwindow.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-panedwindow \- Create and manipulate panedwindow widgets
+panedwindow \- Create and manipulate 'panedwindow' split container widgets
 .SH SYNOPSIS
 \fBpanedwindow\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/radiobutton.n b/doc/radiobutton.n
index 983b43e..9334449 100644
--- a/doc/radiobutton.n
+++ b/doc/radiobutton.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-radiobutton \- Create and manipulate radiobutton widgets
+radiobutton \- Create and manipulate 'radiobutton' pick-one widgets
 .SH SYNOPSIS
 \fBradiobutton\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/scale.n b/doc/scale.n
index c8e722a..ac58837 100644
--- a/doc/scale.n
+++ b/doc/scale.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-scale \- Create and manipulate scale widgets
+scale \- Create and manipulate 'scale' value-controlled slider widgets
 .SH SYNOPSIS
 \fBscale\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/scrollbar.n b/doc/scrollbar.n
index 74fb977..d808f29 100644
--- a/doc/scrollbar.n
+++ b/doc/scrollbar.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-scrollbar \- Create and manipulate scrollbar widgets
+scrollbar \- Create and manipulate 'scrollbar' scrolling control and indicator widgets
 .SH SYNOPSIS
 \fBscrollbar\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/spinbox.n b/doc/spinbox.n
index e88aea6..dde234b 100644
--- a/doc/spinbox.n
+++ b/doc/spinbox.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-spinbox \- Create and manipulate spinbox widgets
+spinbox \- Create and manipulate 'spinbox' value spinner widgets
 .SH SYNOPSIS
 \fBspinbox\fR \fIpathName \fR?\fIoptions\fR?
 .SO
diff --git a/doc/text.n b/doc/text.n
index da16f9a..dcf5a75 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note: do not modify the .SH NAME line immediately below!
 .SH NAME
-text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widgets
+text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate 'text' hypertext editing widgets
 .SH SYNOPSIS
 .nf
 \fBtext\fR \fIpathName \fR?\fIoptions\fR?
diff --git a/doc/toplevel.n b/doc/toplevel.n
index 7d5b53c..6301318 100644
--- a/doc/toplevel.n
+++ b/doc/toplevel.n
@@ -10,7 +10,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-toplevel \- Create and manipulate toplevel widgets
+toplevel \- Create and manipulate 'toplevel' main and popup window widgets
 .SH SYNOPSIS
 \fBtoplevel\fR \fIpathName \fR?\fIoptions\fR?
 .SO