More documentation improvements

1 files changed, 53 insertions, 47 deletions

diff --git a/doc/wm.n b/doc/wm.n
index 93b8011..fb5467e 100644
--- a/doc/wm.n
+++ b/doc/wm.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: wm.n,v 1.35 2007/10/29 16:04:14 dkf Exp $
+'\" RCS: @(#) $Id: wm.n,v 1.36 2007/10/30 21:29:59 dkf Exp $
 '\" 
 .so man.macros
 .TH wm n 8.5 Tk "Tk Built-In Commands"
@@ -54,42 +54,51 @@ with a window. The first form returns a list of the platform specific
 flags and their values. The second form returns the value for the
 specific option. The third form sets one or more of the values. The
 values are as follows:
-.PP
-On Windows, the following attributes may be set.
 .RS
+.PP
+All platforms support the following attributes (though X11 users
+should see the notes below):
 .TP
-\fB\-disabled\fR
-Specifies whether the window is in a disabled state.
-.TP
-\fB\-toolwindow\fR
-Specifies a toolwindow style window (as defined in the MSDN).
+\fB\-fullscreen\fR
+Places the window in a mode that takes up the entire screen, has no
+borders, and covers the general use area (i.e. Start menu and taskbar on
+Windows, dock and menubar on OSX, general window decorations on X11).
 .TP
 \fB\-topmost\fR
 Specifies whether this is a topmost window (displays above all other windows).
-.VS 8.5
+.PP
+On Windows, the following attributes may be set.
 .TP
 \fB\-alpha\fR
+.VS 8.5
 Specifies the alpha transparency level of the toplevel.
 It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR
 (opaque).  Values outside that range will be constrained.  This is
 supported on Windows 2000/XP+.  Where not supported, the \fB\-alpha\fR
 value remains at \fB1.0\fR.
+.VE 8.5
+.TP
+\fB\-disabled\fR
+Specifies whether the window is in a disabled state.
+.TP
+\fB\-toolwindow\fR
+Specifies a toolwindow style window (as defined in the MSDN).
 .TP
 \fB\-transparentcolor\fR
+.VS 8.5
 Specifies the transparent color index of the toplevel.  It takes any color
 value accepted by \fBTk_GetColor\fR.  If the empty string is specified
 (default), no transparent color is used.  This is supported on Windows
 2000/XP+.  Where not supported, the \fB\-transparentcolor\fR value remains
 at \fB{}\fR.
-.TP
-\fB\-fullscreen\fR
-Places the window in a mode that takes up the entire screen, has no
-borders, and covers the Start menu and taskbar.
-.RE
 .VE 8.5
 .PP
 On Mac OS X, the following attributes may be set.
-.RS
+.TP
+\fB\-alpha\fR
+Specifies the alpha transparency level of the window.
+It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque),
+values outside that range will be constrained.
 .TP
 \fB\-modified\fR
 Specifies the modification state of the window (determines whether the
@@ -100,50 +109,27 @@ proxy icon is draggable).
 Specifies the path of the file referenced as the window proxy icon (which
 can be dragged and dropped in lieu of the file's finder icon).
 .TP
-\fB\-alpha\fR
-Specifies the alpha transparency level of the window.
-It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque),
-values outside that range will be constrained.
-.TP
-\fB\-topmost\fR
-Specifies whether this is a topmost window (displays above all other windows).
-.TP
 \fB\-transparent\fR
 Makes the window content area transparent and turns off the window shadow. For
 the transparency to be effecive, the toplevel background needs to be set to a
 color with some alpha, e.g.
 .QW systemTransparent .
-.TP
-\fB\-fullscreen\fR
-Places the window in a mode that takes up the entire main screen and hides
-the dock and menu bar.
-.RE
 .PP
 On X11, the following attributes may be set.
 These are not supported by all window managers,
 and will have no effect under older WMs.
 .\" See http://www.freedesktop.org/Standards/wm-spec
-.RS
-.TP
-\fB\-topmost\fR
-Requests that this window should be kept above
-all other windows that do not also have the \fB\-topmost\fR
-attribute set.
 .TP
 \fB\-zoomed\fR
 Requests that the window should be maximized.
 This is the same as \fBwm state zoomed\fR on Windows and Mac OS X.
-.TP
-\fB\-fullscreen\fR
-Requests that the window should fill the entire screen 
-and have no window decorations.
-.RE
 .PP
 On X11, changes to window attributes are performed asynchronously.
 Querying the value of an attribute returns the current state,
 which will not be the same as the value most recently set
 if the window manager has not yet processed the request
 or if it does not support the attribute.
+.RE
 .TP
 \fBwm client \fIwindow\fR ?\fIname\fR?
 If \fIname\fR is specified, this command stores \fIname\fR (which
@@ -161,6 +147,8 @@ If \fIname\fR is specified as an empty string, the command deletes the
 This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR
 property, which provides information to the window managers about
 windows that have private colormaps.
+.RS
+.PP
 If \fIwindowList\fR is not specified, the command returns a list
 whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR
 property.
@@ -170,6 +158,7 @@ property with the given windows and returns an empty string.
 The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a
 list of the internal windows within \fIwindow\fR whose colormaps differ
 from their parents.
+.PP
 The order of the windows in the property indicates a priority order:
 the window manager will attempt to install as many colormaps as possible
 from the head of this list when \fIwindow\fR gets the colormap focus.
@@ -182,6 +171,7 @@ whose colormaps differ from their parents, followed by the top-level
 itself;  the order of the internal windows is undefined.
 See the ICCCM documentation for more information on the
 \fBWM_COLORMAP_WINDOWS\fR property.
+.RE
 .TP
 \fBwm command \fIwindow\fR ?\fIvalue\fR?
 If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's
@@ -209,6 +199,8 @@ to the command, then it specifies the focus model for \fIwindow\fR.
 In this case the command returns an empty string.  If no additional
 argument is supplied, then the command returns the current focus
 model for \fIwindow\fR.
+.RS
+.PP
 An \fBactive\fR focus model means that \fIwindow\fR will claim the
 input focus for itself or its descendants, even at times when
 the focus is currently in some other application.  \fBPassive\fR means that
@@ -218,6 +210,7 @@ once the focus has been given to \fIwindow\fR or one of its descendants,
 the application may re-assign the focus among \fIwindow\fR's descendants.
 The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command
 assumes a passive model of focusing.
+.RE
 .TP
 \fBwm forget \fIwindow\fR
 The \fIwindow\fR will be unmapped from the screen and will no longer
@@ -246,7 +239,10 @@ may be omitted.  \fIWidth\fR and \fIheight\fR are positive integers
 specifying the desired dimensions of \fIwindow\fR.  If \fIwindow\fR
 is gridded (see \fBGRIDDED GEOMETRY MANAGEMENT\fR below) then the dimensions
 are specified in grid units;  otherwise they are specified in pixel
-units.  \fIX\fR and \fIy\fR specify the desired location of
+units.
+.RS
+.PP
+\fIX\fR and \fIy\fR specify the desired location of
 \fIwindow\fR on the screen, in pixels.
 If \fIx\fR is preceded by \fB+\fR, it specifies
 the number of pixels between the left edge of the screen and the left
@@ -258,10 +254,12 @@ number of pixels between the top of the screen and the top
 of \fIwindow\fR's border;  if \fIy\fR is preceded by \fB\-\fR then
 it specifies the number of pixels between the bottom of \fIwindow\fR's
 border and the bottom of the screen.
+.PP
 If \fInewGeometry\fR is specified as an empty string then any
 existing user-specified geometry for \fIwindow\fR is cancelled, and
 the window will revert to the size requested internally by its
 widgets.
+.RE
 .TP
 \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR?
 This command indicates that \fIwindow\fR is to be managed as a
@@ -278,20 +276,25 @@ that are non-negative integers.
 Tk will pass this information to the window manager;  during
 manual resizing, the window manager will restrict the window's size
 to one of these acceptable sizes.
+.RS
+.PP
 Furthermore, during manual resizing the window manager will display
 the window's current size in terms of grid units rather than pixels.
 If \fIbaseWidth\fR etc. are all specified as empty strings, then
 \fIwindow\fR will no longer be managed as a gridded window.  If
 \fIbaseWidth\fR etc. are specified then the return value is an
 empty string.
+.PP
 Otherwise the return value is a Tcl list containing
 four elements corresponding to the current \fIbaseWidth\fR,
 \fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR;  if
 \fIwindow\fR is not currently gridded, then an empty string
 is returned.
+.PP
 Note: this command should not be needed very often, since the
 \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option
 provide easier access to the same functionality.
+.RE
 .TP
 \fBwm group \fIwindow\fR ?\fIpathName\fR?
 If \fIpathName\fR is specified, it gives the path name for the leader of
@@ -315,7 +318,9 @@ Otherwise it returns the name of
 the current icon bitmap associated with \fIwindow\fR, or an empty
 string if \fIwindow\fR has no icon bitmap.  On the Windows operating
 system, an additional flag is supported: 
-\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?.  
+.RS
+.TP
+\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?
 If the \fB\-default\fR
 flag is given, the icon is applied to all toplevel windows (existing
 and future) to which no other specific icon has yet been applied.
@@ -326,6 +331,7 @@ file for which the shell has assigned an icon.  Tcl will
 first test if the file contains an icon, then if it has an assigned
 icon, and finally, if that fails, test for
 a bitmap.
+.RE
 .TP
 \fBwm iconify \fIwindow\fR
 Arrange for \fIwindow\fR to be iconified.  It \fIwindow\fR has not
@@ -358,7 +364,6 @@ as specified with the \fBwm title\fR command).
 .VS 8.5
 .TP
 \fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR?
-.RS
 Sets the titlebar icon for \fIwindow\fR based on the named photo images.
 If \fB\-default\fR is specified, this is applied to all future created
 toplevels as well.  The data in the images is taken as a snapshot at the
@@ -366,6 +371,7 @@ time of invocation.  If the images are later changed, this is not
 reflected to the titlebar icons.  Multiple images are accepted to allow
 different images sizes (e.g., 16x16 and 32x32) to be provided. The window
 manager may scale provided icons to an appropriate size.
+.RS
 .PP
 On Windows, the images are packed into a Windows icon structure.
 This will override an ico specified to \fBwm iconbitmap\fR, and
@@ -535,16 +541,16 @@ no source has been specified yet.  Most window managers interpret
 .QW "no source"
 as equivalent to \fBprogram\fR.
 .TP
-\fBwm stackorder \fIwindow\fR ?\fIisabove|isbelow window\fR?
-The stackorder command returns a list of toplevel windows
+\fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR?
+The \fBstackorder\fR command returns a list of toplevel windows
 in stacking order, from lowest to highest. When a single toplevel
 window is passed, the returned list recursively includes all of the
 window's children that are toplevels. Only those toplevels
 that are currently mapped to the screen are returned.
-The stackorder command can also be used to determine if one
+The \fBstackorder\fR command can also be used to determine if one
 toplevel is positioned above or below a second toplevel.
-When two window arguments separated by either \fIisabove\fR or
-\fIisbelow\fR are passed, a boolean result indicates whether
+When two window arguments separated by either \fBisabove\fR or
+\fBisbelow\fR are passed, a boolean result indicates whether
 or not the first window is currently above or below the second
 window in the stacking order.
 .TP