* Merged 8.1 branch into the main trunk

15 files changed, 1164 insertions, 296 deletions

diff --git a/doc/3DBorder.3 b/doc/3DBorder.3
index ea1a629..2780bde 100644
--- a/doc/3DBorder.3
+++ b/doc/3DBorder.3
@@ -1,24 +1,32 @@
 '\"
 '\" Copyright (c) 1990-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: 3DBorder.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
+'\" RCS: @(#) $Id: 3DBorder.3,v 1.3 1999/04/16 01:51:07 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorder \- draw borders with three-dimensional appearance
+Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
+Tk_3DBorder
+\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
 Tk_3DBorder
 \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
 .sp
+Tk_3DBorder
+\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 void
 \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
 .sp
@@ -49,6 +57,10 @@ XColor *
 GC *
 \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
 .sp
+.VS 8.1
+\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_Free3DBorder(\fIborder\fB)\fR
 .SH ARGUMENTS
 .AS "Tk_3DBorder" borderWidth
@@ -57,10 +69,15 @@ Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window (for all procedures except \fBTk_Get3DBorder\fR,
 must be the window for which the border was allocated).
-.AP Tk_Uid colorName in
-Textual description of color corresponding to background (flat areas).
-Illuminated edges will be brighter than this and shadowed edges will
-be darker than this.
+.AP Tcl_Obj *objPtr in
+.VS 8.1
+Pointer to object whose value describes color corresponding to
+background (flat areas).  Illuminated edges will be brighter than
+this and shadowed edges will be darker than this.
+.AP char *colorName in
+Same as \fIobjPtr\fR except value is supplied as a string rather
+than an object.
+.VE
 .AP Drawable drawable in
 X token for window or pixmap;  indicates where graphics are to be drawn.
 Must either be the X window for \fItkwin\fR or a pixmap with the
@@ -129,22 +146,42 @@ Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
 .SH DESCRIPTION
 .PP
 These procedures provide facilities for drawing window borders in a
-way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
+way that produces a three-dimensional appearance.
+.VS 8.1
+\fBTk_Alloc3DBorderFromObj\fR
 allocates colors and Pixmaps needed to draw a border in the window
-given by the \fItkwin\fR argument.  The \fIcolorName\fR
-argument indicates what colors should be used in the border.
-\fIColorName\fR may be any value acceptable to \fBTk_GetColor\fR.
-The color indicated by \fIcolorName\fR will not actually be used in
+given by the \fItkwin\fR argument.  The value of \fIobjPtr\fR
+is a standard Tk color name that determines the border colors.
+The color indicated by \fIobjPtr\fR will not actually be used in
 the border;  it indicates the background color for the window
 (i.e. a color for flat surfaces).
 The illuminated portions of the border will appear brighter than indicated
-by \fIcolorName\fR, and the shadowed portions of the border will appear
-darker than \fIcolorName\fR.
+by \fIobjPtr\fR, and the shadowed portions of the border will appear
+darker than \fIobjPtr\fR.
 .PP
-\fBTk_Get3DBorder\fR returns a token that may be used in later calls
+\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
 to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
-for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
+for the border (e.g. a bogus color name was given)
 then NULL is returned and an error message is left in \fIinterp->result\fR.
+If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches
+information about the return value in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
+that the color is specified with a string instead of an object.  This
+prevents \fBTk_Get3DBorder\fR from caching the return value, so
+\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
+.PP
+\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
+the window and color name used to create the border.
+\fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must
+already have been created with a previous call to
+\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
 Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
 invoked to draw the border.
@@ -171,7 +208,7 @@ a groove or ridge around the exterior of the rectangle.
 \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
 that it first fills the rectangular area with the background color
 (one corresponding
-to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
+to the color used to create \fIborder\fR).  Then it calls
 \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
 the rectangular area.  The argument \fIrelief\fR indicates the desired
 effect (TK_RELIEF_FLAT means no border should be drawn; all that
@@ -228,21 +265,19 @@ bottom bevel should be drawn with 0 for both arguments.
 The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
 pixel and/or pixmap of \fItkwin\fR to produce a result compatible
 with \fIborder\fR.  For color displays, the resulting background will
-just be the color given by the \fIcolorName\fR argument passed to
-\fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
+just be the color specified when \fIborder\fR was created;  for monochrome
 displays, the resulting background
 will be a light stipple pattern, in order to distinguish the background from
 the illuminated portion of the border.
 .PP
 Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
-will return the \fIcolorName\fR string that was passed to
-\fBTk_Get3DBorder\fR to create the border.
+will return the color name that was used to create the border.
 .PP
 The procedure \fBTk_3DBorderColor\fR returns the XColor structure
 that will be used for flat surfaces drawn for its \fIborder\fR
 argument by procedures like \fBTk_Fill3DRectangle\fR.
-The return value corresponds to the \fIcolorName\fR passed to
-\fBTk_Get3DBorder\fR.
+The return value corresponds to the color name that was used to
+create the border.
 The XColor, and its associated pixel value, will remain allocated
 as long as \fIborder\fR exists.
 .PP
@@ -253,10 +288,18 @@ TK_3D_FLAT_GC returns the context used for flat surfaces,
 TK_3D_LIGHT_GC returns the context for light shadows,
 and TK_3D_DARK_GC returns the context for dark shadows.
 .PP
-When a border is no longer needed, \fBTk_Free3DBorder\fR should
-be called to release the resources associated with the border.
-There should be exactly one call to \fBTk_Free3DBorder\fR for
-each call to \fBTk_Get3DBorder\fR.
+.VS 8.1
+When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR
+or \fBTk_Free3DBorder\fR should
+be called to release the resources associated with it.
+For \fBTk_Free3DBorderFromObj\fR the border to release is specified
+with the window and color name used to create the
+border; for \fBTk_Free3DBorder\fR the border to release is specified
+with the Tk_3DBorder token for the border.
+There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or
+\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR
+or \fBTk_Get3DBorder\fR.
+.VE
 
 .SH KEYWORDS
-3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
+3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect
diff --git a/doc/ConfigWidg.3 b/doc/ConfigWidg.3
index 04daead..0b8b91b 100644
--- a/doc/ConfigWidg.3
+++ b/doc/ConfigWidg.3
@@ -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: ConfigWidg.3,v 1.2 1998/09/14 18:22:46 stanton Exp $
+'\" RCS: @(#) $Id: ConfigWidg.3,v 1.3 1999/04/16 01:51:07 stanton Exp $
 '\" 
 .so man.macros
 .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
@@ -26,10 +26,11 @@ int
 \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
 .sp
 int
+\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
 .sp
 \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
 .SH ARGUMENTS
-.AS Tk_ConfigSpec *widgRec
+.AS Tk_ConfigSpec *widgRec in/out
 .AP Tcl_Interp *interp in
 Interpreter to use for returning error messages.
 .AP Tk_Window tkwin in
diff --git a/doc/GetAnchor.3 b/doc/GetAnchor.3
index 5342ea5..b12d48f 100644
--- a/doc/GetAnchor.3
+++ b/doc/GetAnchor.3
@@ -1,21 +1,26 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetAnchor.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetAnchor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetAnchor 3 "" Tk "Tk Library Procedures"
+.TH Tk_GetAnchorFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
+Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
+int
+\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR
+.VE
+.sp
 int
 \fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR
 .sp
@@ -24,35 +29,52 @@ char *
 .SH ARGUMENTS
 .AS "Tk_Anchor" *anchorPtr
 .AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+Interpreter to use for error reporting, or NULL.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value contains name of anchor point: \fBn\fR, \fBne\fR,
+\fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR;
+internal rep will be modified to cache corresponding Tk_Anchor.
 .AP char *string in
-String containing name of anchor point: one of ``n'', ``ne'', ``e'', ``se'',
-``s'', ``sw'', ``w'', ``nw'', or ``center''.
+Same as \fIobjPtr\fR except description of anchor point is passed as
+a string.
+.VE
 .AP int *anchorPtr out
 Pointer to location in which to store anchor position corresponding to
-\fIstring\fR.
+\fIobjPtr\fR or \fIstring\fR.
 .AP Tk_Anchor anchor in
 Anchor position, e.g. \fBTCL_ANCHOR_CENTER\fR.
 .BE
 
 .SH DESCRIPTION
 .PP
-\fBTk_GetAnchor\fR places in \fI*anchorPtr\fR an anchor position
+.VS 8.1
+\fBTk_GetAnchorFromObj\fR places in \fI*anchorPtr\fR an anchor position
 (enumerated type \fBTk_Anchor\fR)
-corresponding to \fIstring\fR,  which will be one of
+corresponding to \fIobjPtr\fR's value.  The result will be one of
 \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, \fBTK_ANCHOR_E\fR, \fBTK_ANCHOR_SE\fR,
 \fBTK_ANCHOR_S\fR, \fBTK_ANCHOR_SW\fR, \fBTK_ANCHOR_W\fR, \fBTK_ANCHOR_NW\fR,
 or \fBTK_ANCHOR_CENTER\fR.
 Anchor positions are typically used for indicating a point on an object
-that will be used to position that object, e.g. \fBTK_ANCHOR_N\fR means
+that will be used to position the object, e.g. \fBTK_ANCHOR_N\fR means
 position the top center point of the object at a particular place.
 .PP
 Under normal circumstances the return value is \fBTCL_OK\fR and
 \fIinterp\fR is unused.
 If \fIstring\fR doesn't contain a valid anchor position
-or an abbreviation of one of these names, then an error message is
-stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and
-\fI*anchorPtr\fR is unmodified.
+or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,
+\fI*anchorPtr\fR is unmodified, and an error message is
+stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
+\fBTk_GetAnchorFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetAnchorFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetAnchor\fR is identical to \fBTk_GetAnchorFromObj\fR except
+that the description of the anchor is specified with a string instead
+of an object.  This prevents \fBTk_GetAnchor\fR from caching the
+return value, so \fBTk_GetAnchor\fR is less efficient than
+\fBTk_GetAnchorFromObj\fR.
+.VE
 .PP
 \fBTk_NameOfAnchor\fR is the logical inverse of \fBTk_GetAnchor\fR.
 Given an anchor position such as \fBTK_ANCHOR_N\fR it returns a
diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3
index 4321cce..28b5cb1 100644
--- a/doc/GetBitmap.3
+++ b/doc/GetBitmap.3
@@ -1,42 +1,61 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetBitmap.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetBitmap.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures"
+.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
+Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
 Pixmap
-\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
+\fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 int
-\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR
+\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
 .sp
-Tk_Uid
+char *
 \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
 .sp
 \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
 .sp
+.VS 8.1
+\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
 .SH ARGUMENTS
 .AS "unsigned long" *pixelPtr
 .AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+Interpreter to use for error reporting; if NULL then no error message
+is left after errors.
 .AP Tk_Window tkwin in
 Token for window in which the bitmap will be used.
-.AP Tk_Uid id in
-Description of bitmap;  see below for possible values.
-.AP Tk_Uid nameId in
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value describes desired bitmap; internal rep will be
+modified to cache pointer to corresponding Pixmap.
+.AP "CONST char" *info in
+Same as \fIobjPtr\fR except description of bitmap is passed as a string and
+resulting Pixmap isn't cached.
+.VE
+.AP "CONST char" *name in
 Name for new bitmap to be defined.
 .AP char *source in
 Data for bitmap, in standard bitmap format.
@@ -52,7 +71,8 @@ Pointer to word to fill in with \fIbitmap\fR's height.
 .AP Display *display in
 Display for which \fIbitmap\fR was allocated.
 .AP Pixmap bitmap in
-Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
+Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .BE
 
 .SH DESCRIPTION
@@ -62,11 +82,13 @@ being used by an application.  The procedures allow bitmaps to be
 re-used efficiently, thereby avoiding server overhead, and also
 allow bitmaps to be named with character strings.
 .PP
-\fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap.
-It returns a Pixmap identifier for a bitmap corresponding to the
-description.  It re-uses an existing bitmap, if possible, and
-creates a new one otherwise.  At present, \fIid\fR must have
-one of the following forms:
+.VS 8.1
+\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
+that matches the description in \fIobjPtr\fR and is suitable for use
+in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
+creates a new one otherwise.  \fIObjPtr\fR's value must have one
+of the following forms:
+.VE
 .TP 20
 \fB@\fIfileName\fR
 \fIFileName\fR must be the name of a file containing a bitmap
@@ -166,15 +188,35 @@ A face with ballon words.
 A triangle with an exclamation point.
 .RE
 .LP
-Under normal conditions, \fBTk_GetBitmap\fR
+.VS 8.1
+Under normal conditions, \fBTk_AllocBitmapFromObj\fR
 returns an identifier for the requested bitmap.  If an error
-occurs in creating the bitmap, such as when \fIid\fR refers
+occurs in creating the bitmap, such as when \fIobjPtr\fR refers
 to a non-existent file, then \fBNone\fR is returned and an error
-message is left in \fIinterp->result\fR.
+message is left in \fIinterp\fR's result if \fIinterp\fR isn't
+NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
+that the description of the bitmap is specified with a string instead
+of an object.  This prevents \fBTk_GetBitmap\fR from caching the
+return value, so \fBTk_GetBitmap\fR is less efficient than
+\fBTk_AllocBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given
+the window and description used to create the bitmap.
+\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap
+must already have been created with a previous call to
+\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
 \fBTk_DefineBitmap\fR associates a name with
 in-memory bitmap data so that the name can be used in later
-calls to \fBTk_GetBitmap\fR.  The \fInameId\fR
+calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The \fInameId\fR
 argument gives a name for the bitmap;  it must not previously
 have been used in a call to \fBTk_DefineBitmap\fR.
 The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
@@ -186,7 +228,8 @@ TCL_ERROR is returned and an error message is left in
 Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
 \fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
 a private copy of this memory, but uses the bytes pointed to
-by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
+by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .PP
 Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
 bitmap file directly into a C program and then referencing
@@ -196,36 +239,40 @@ which was created by the \fBbitmap\fR program and contains
 a stipple pattern.
 The following code uses \fBTk_DefineBitmap\fR to define a
 new bitmap named \fBfoo\fR:
+.VS
 .CS
 Pixmap bitmap;
 #include "stip.bitmap"
-Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
+Tk_DefineBitmap(interp, "foo", stip_bits,
 	stip_width, stip_height);
 \&...
-bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
+bitmap = Tk_GetBitmap(interp, tkwin, "foo");
 .CE
+.VE
 This code causes the bitmap file to be read
 at compile-time and incorporates the bitmap information into
 the program's executable image.  The same bitmap file could be
 read at run-time using \fBTk_GetBitmap\fR:
+.VS
 .CS
 Pixmap bitmap;
-bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
+bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
 .CE
+.VE
 The second form is a bit more flexible (the file could be modified
 after the program has been compiled, or a different string could be
 provided to read a different file), but it is a little slower and
 requires the bitmap file to exist separately from the program.
 .PP
-\fBTk_GetBitmap\fR maintains a
-database of all the bitmaps that are currently in use.
+Tk maintains a database of all the bitmaps that are currently in use.
 Whenever possible, it will return an existing bitmap rather
 than creating a new one.
+When a bitmap is no longer used, Tk will release it automatically.
 This approach can substantially reduce server overhead, so
-\fBTk_GetBitmap\fR should generally be used in preference to Xlib
-procedures like \fBXReadBitmapFile\fR.
+\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
+be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
 .PP
-The bitmaps returned by \fBTk_GetBitmap\fR
+The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
 are shared, so callers should never modify them.
 If a bitmap must be modified dynamically, then it should be
 created by calling Xlib procedures such as \fBXReadBitmapFile\fR
@@ -233,28 +280,33 @@ or \fBXCreatePixmap\fR directly.
 .PP
 The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
 \fBTk_GetBitmap\fR.
-Given an X Pixmap argument, it returns the \fIid\fR that was
+Given an X Pixmap argument, it returns the textual description that was
 passed to \fBTk_GetBitmap\fR when the bitmap was created.
 \fIBitmap\fR must have been the return value from a previous
-call to \fBTk_GetBitmap\fR.
+call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
 .PP
 \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
 argument in the words pointed to by the \fIwidthPtr\fR and
 \fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
-\fIbitmap\fR must have been created by \fBTk_GetBitmap\fR.
+\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .PP
-When a bitmap returned by \fBTk_GetBitmap\fR
-is no longer needed, \fBTk_FreeBitmap\fR should be called to release it.
-There should be exactly one call to \fBTk_FreeBitmap\fR for
-each call to \fBTk_GetBitmap\fR.
-When a bitmap is no longer in use anywhere (i.e. it has been freed as
-many times as it has been gotten) \fBTk_FreeBitmap\fR will release
-it to the X server and delete it from the database.
+.VS 8.1
+When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or
+\fBTk_FreeBitmap\fR should be called to release it.
+For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified
+with the same information used to create it; for
+\fBTk_FreeBitmap\fR the bitmap to release is specified
+with its Pixmap token.
+There should be exactly one call to \fBTk_FreeBitmapFromObj\fR
+or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.VE
 
 .SH BUGS
 In determining whether an existing bitmap can be used to satisfy
-a new request, \fBTk_GetBitmap\fR
-considers only the immediate value of its \fIid\fR argument.  For
+a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
+consider only the immediate value of the string description.  For
 example, when a file name is passed to \fBTk_GetBitmap\fR,
 \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
 bitmap created from the same file name:  it will not check to
diff --git a/doc/GetColor.3 b/doc/GetColor.3
index 4b551f2..d5abc78 100644
--- a/doc/GetColor.3
+++ b/doc/GetColor.3
@@ -1,32 +1,44 @@
 '\"
-'\" Copyright (c) 1990, 1991 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1990-1991 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetColor.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetColor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors
+Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
+.VS 8.1
 .sp
 XColor *
-\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR
+\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
 .sp
 XColor *
-\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR
+\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR
+.sp
+XColor *
+\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
+XColor *
+\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR
 .sp
 char *
 \fBTk_NameOfColor(\fIcolorPtr\fB)\fR
 .sp
 GC
-\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR)
+\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR
+.sp
+.VS 8.1
+\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 \fBTk_FreeColor(\fIcolorPtr\fB)\fR
 .SH ARGUMENTS
@@ -35,27 +47,39 @@ GC
 Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window in which color will be used.
-.AP Tk_Uid nameId in
-Textual description of desired color.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value describes desired color; internal rep will be
+modified to cache pointer to corresponding (XColor *).
+.AP char *name in
+Same as \fIobjPtr\fR except description of color is passed as a string and
+resulting (XColor *) isn't cached.
+.VE
 .AP XColor *prefPtr in
 Indicates red, green, and blue intensities of desired
 color.
 .AP XColor *colorPtr in
 Pointer to X color information.  Must have been allocated by previous
-call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed
-to \fBTk_NameOfColor\fR.
+call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or
+\fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR.
 .AP Drawable drawable in
 Drawable in which the result graphics context will be used.  Must have
 same screen and depth as the window for which the color was allocated.
 .BE
 
 .SH DESCRIPTION
+.VS 8.1
+.PP
+These procedures manage the colors being used by a Tk application.
+They allow colors to be shared whenever possible, so that colormap
+space is preserved, and they pick closest available colors when
+colormap space is exhausted.
 .PP
-The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures
-locate pixel values that may be used to render particular
-colors in the window given by \fItkwin\fR.  In \fBTk_GetColor\fR
-the desired color is specified with a Tk_Uid (\fInameId\fR), which
-may have any of the following forms:
+Given a textual description of a color, \fBTk_AllocColorFromObj\fR
+locates a pixel value that may be used to render the color
+in a particular window.  The desired color is specified with an
+object whose string value must have one of the following forms:
+.VE
 .TP 20
 \fIcolorname\fR
 Any of the valid textual names for a color defined in the
@@ -76,38 +100,56 @@ When fewer than 16 bits are provided for each color, they represent
 the most significant bits of the color.  For example, #3a7 is the
 same as #3000a0007000.
 .PP
-In \fBTk_GetColorByValue\fR, the desired color is indicated with
-the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure
-pointed to by \fIcolorPtr\fR.
-.PP
-If \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR is successful
-in allocating the desired color, then it returns a pointer to
+.VS 8.1
+\fBTk_AllocColorFromObj\fR returns a pointer to
 an XColor structure;  the structure indicates the exact intensities of
 the allocated color (which may differ slightly from those requested,
 depending on the limitations of the screen) and a pixel value
-that may be used to draw in the color.
-If the colormap for \fItkwin\fR is full, \fBTk_GetColor\fR
-and \fBTk_GetColorByValue\fR will use the closest existing color
-in the colormap.
-If \fBTk_GetColor\fR encounters an error while allocating
-the color (such as an unknown color name) then NULL is returned and
-an error message is stored in \fIinterp->result\fR;
-\fBTk_GetColorByValue\fR never returns an error.
+that may be used to draw with the color in \fItkwin\fR.
+If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown
+color name) then NULL is returned and an error message is stored in
+\fIinterp\fR's result if \fIinterp\fR isn't NULL.
+If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR
+will use the closest existing color in the colormap.
+\fBTk_AllocColorFromObj\fR caches information about
+the return value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR.
+.PP
+\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except
+that the description of the color is specified with a string instead
+of an object.  This prevents \fBTk_GetColor\fR from caching the
+return value, so \fBTk_GetColor\fR is less efficient than
+\fBTk_AllocColorFromObj\fR.
+.PP
+\fBTk_GetColorFromObj\fR returns the token for an existing color, given
+the window and description used to create the color.
+\fBTk_GetColorFromObj\fR doesn't actually create the color; the color
+must already have been created with a previous call to
+\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
-\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database
+\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that
+the desired color is indicated with the \fIred\fR, \fIgreen\fR, and
+\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR.
+.PP
+This package maintains a database
 of all the colors currently in use.
-If the same \fInameId\fR is requested multiple times from
-\fBTk_GetColor\fR (e.g. by different windows), or if the
+If the same color is requested multiple times from
+\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different
+windows), or if the 
 same intensities are requested multiple times from
 \fBTk_GetColorByValue\fR, then existing pixel values will
 be re-used.  Re-using an existing pixel avoids any interaction
-with the X server, which makes the allocation much more
-efficient.  For this reason, you should generally use
-\fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
-instead of Xlib procedures like \fBXAllocColor\fR,
-\fBXAllocNamedColor\fR, or \fBXParseColor\fR.
+with the window server, which makes the allocation much more
+efficient.  These procedures also provide a portable interface that
+works across all platforms.  For this reason, you should generally use
+\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR
+instead of lower level procedures like \fBXAllocColor\fR.
 .PP
-Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
+Since different calls to this package
 may return the same shared
 pixel value, callers should never change the color of a pixel
 returned by the procedures.
@@ -116,15 +158,16 @@ If you need to change a color value dynamically, you should use
 .PP
 The procedure \fBTk_NameOfColor\fR is roughly the inverse of
 \fBTk_GetColor\fR.  If its \fIcolorPtr\fR argument was created
-by \fBTk_GetColor\fR, then the return value is the \fInameId\fR
-string that was passed to \fBTk_GetColor\fR to create the
+by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value
+is the string that was used to create the
 color.  If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR,
 or by any other mechanism, then the return value is a string
 that could be passed to \fBTk_GetColor\fR to return the same
 color.  Note:  the string returned by \fBTk_NameOfColor\fR is
-only guaranteed to persist until the next call to \fBTk_NameOfColor\fR.
+only guaranteed to persist until the next call to
+\fBTk_NameOfColor\fR.
 .PP
-\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR
+\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR
 field is the pixel allocated for \fIcolorPtr\fR and whose other fields
 all have default values.
 This provides an easy way to do basic drawing with a color.
@@ -132,15 +175,16 @@ The graphics context is cached with the color and will exist only as
 long as \fIcolorPtr\fR exists;  it is freed when the last reference
 to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR.
 .PP
-When a pixel value returned by \fBTk_GetColor\fR or
-\fBTk_GetColorByValue\fR is no longer
-needed, \fBTk_FreeColor\fR should be called to release the color.
-There should be exactly one call to \fBTk_FreeColor\fR for
-each call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR.
-When a pixel value is no longer in
-use anywhere (i.e. it has been freed as many times as it has been gotten)
-\fBTk_FreeColor\fR will release it to the X server and delete it from
-the database.
-
+.VS 8.1
+When a color is no longer needed \fBTk_FreeColorFromObj\fR or
+\fBTk_FreeColor\fR should be called to release it.
+For \fBTk_FreeColorFromObj\fR the color to release is specified
+with the same information used to create it; for
+\fBTk_FreeColor\fR the color to release is specified
+with a pointer to its XColor structure.
+There should be exactly one call to \fBTk_FreeColorFromObj\fR
+or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR,
+\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR.
+.VE
 .SH KEYWORDS
-color, intensity, pixel value
+color, intensity, object, pixel value
diff --git a/doc/GetCursor.3 b/doc/GetCursor.3
index dca27ad..55b9c58 100644
--- a/doc/GetCursor.3
+++ b/doc/GetCursor.3
@@ -1,23 +1,31 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetCursor.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
+'\" RCS: @(#) $Id: GetCursor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetCursor 3 4.1 Tk "Tk Library Procedures"
+.TH Tk_AllocCursorFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor \- maintain database of cursors
+Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj, Tk_FreeCursor \- maintain database of cursors
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
 Tk_Cursor
-\fBTk_GetCursor(\fIinterp, tkwin, nameId\fB)\fR
+\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_Cursor
+\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR
+.sp
+Tk_Cursor
+\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 Tk_Cursor
 \fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR
@@ -25,6 +33,10 @@ Tk_Cursor
 char *
 \fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR
 .sp
+.VS 8.1
+\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR
 .SH ARGUMENTS
 .AS "unsigned long" *pixelPtr
@@ -32,12 +44,18 @@ char *
 Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window in which the cursor will be used.
-.AP Tk_Uid nameId in
-Description of cursor;  see below for possible values.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+Description of cursor;  see below for possible values.  Internal rep will be
+modified to cache pointer to corresponding Tk_Cursor.
+.AP char *name in
+Same as \fIobjPtr\fR except description of cursor is passed as a string and
+resulting Tk_Cursor isn't cached.
+.VE
 .AP char *source in
-Data for cursor bitmap, in standard bitmap format.
+Data for cursor cursor, in standard cursor format.
 .AP char *mask in
-Data for mask bitmap, in standard bitmap format.
+Data for mask cursor, in standard cursor format.
 .AP "int" width in
 Width of \fIsource\fR and \fImask\fR.
 .AP "int" height in
@@ -53,7 +71,7 @@ Textual description of background color for cursor.
 .AP Display *display in
 Display for which \fIcursor\fR was allocated.
 .AP Tk_Cursor cursor in
-Opaque Tk identifier for cursor.  If passed to\fBTk_FreeCursor\fR, must
+Opaque Tk identifier for cursor.  If passed to \fBTk_FreeCursor\fR, must
 have been returned by some previous call to \fBTk_GetCursor\fR or
 \fBTk_GetCursorFromData\fR.
 .BE
@@ -63,18 +81,25 @@ have been returned by some previous call to \fBTk_GetCursor\fR or
 These procedures manage a collection of cursors
 being used by an application.  The procedures allow cursors to be
 re-used efficiently, thereby avoiding server overhead, and also
-allow cursors to be named with character strings (actually Tk_Uids).
+allow cursors to be named with character strings.
 .PP
-\fBTk_GetCursor\fR takes as argument a Tk_Uid describing a cursor,
-and returns an opaque Tk identifier for a cursor corresponding to the
-description. 
-It re-uses an existing cursor if possible and
-creates a new one otherwise.  \fINameId\fR must be a standard Tcl
+.VS 8.1
+\fBTk_AllocCursorFromObj\fR takes as argument an object describing a
+cursor, and returns an opaque Tk identifier for a cursor corresponding
+to the description.  It re-uses an existing cursor if possible and
+creates a new one otherwise.  \fBTk_AllocCursorFromObj\fR caches
+information about the return value in \fIobjPtr\fR, which speeds up
+future calls to procedures such as \fBTk_AllocCursorFromObj\fR and
+\fBTk_GetCursorFromObj\fR. If an error occurs in creating the cursor,
+such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR
+is returned and an error message will be stored in \fIinterp\fR's result
+if \fIinterp\fR isn't NULL.  \fIObjPtr\fR must contain a standard Tcl
 list with one of the following forms:
+.VE
 .TP
 \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]]
-\fIName\fR is the name of a cursor in the standard X cursor font,
-i.e., any of the names defined in \fBcursorfont.h\fR, without
+\fIName\fR is the name of a cursor in the standard X cursor cursor,
+i.e., any of the names defined in \fBcursorcursor.h\fR, without
 the \fBXC_\fR.  Some example values are \fBX_cursor\fR, \fBhand2\fR,
 or \fBleft_ptr\fR.  Appendix B of ``The X Window System''
 by Scheifler & Gettys has illustrations showing what each of these
@@ -86,9 +111,10 @@ will be no background color:  the background will be transparent.
 If no colors are specified, then the cursor
 will use black for its foreground color and white for its background
 color.
-
-The Macintosh version of Tk also supports all of the X cursors.
-Tk on the Mac will also accept any of the standard Mac cursors
+.RS
+.PP
+The Macintosh version of Tk supports all of the X cursors and
+will also accept any of the standard Mac cursors
 including \fBibeam\fR, \fBcrosshair\fR, \fBwatch\fR, \fBplus\fR, and
 \fBarrow\fR.  In addition, Tk will load Macintosh cursor resources of
 the types \fBcrsr\fR (color) and \fBCURS\fR (black and white) by the
@@ -96,11 +122,12 @@ name of the of the resource.  The application and all its open
 dynamic library's resource files will be searched for the named
 cursor.  If there are conflicts color cursors will always be loaded
 in preference to black and white cursors.
+.RE
 .TP
 \fB@\fIsourceName\0maskName\0fgColor\0bgColor\fR
 In this form, \fIsourceName\fR and \fImaskName\fR are the names of
-files describing bitmaps for the cursor's source bits and mask.
-Each file must be in standard X11 or X10 bitmap format.
+files describing cursors for the cursor's source bits and mask.
+Each file must be in standard X11 or X10 cursor format.
 \fIFgColor\fR and \fIbgColor\fR 
 indicate the colors to use for the
 cursor, in any of the forms acceptable to \fBTk_GetColor\fR.  This
@@ -112,10 +139,27 @@ used as mask also.  This means that the cursor's background is
 transparent.  This form of the command will not work on Macintosh
 or Windows computers.
 .PP
+.VS 8.1
+\fBTk_GetCursor\fR is identical to \fBTk_AllocCursorFromObj\fR except
+that the description of the cursor is specified with a string instead
+of an object.  This prevents \fBTk_GetCursor\fR from caching the
+return value, so \fBTk_GetCursor\fR is less efficient than
+\fBTk_AllocCursorFromObj\fR.
+.PP
+\fBTk_GetCursorFromObj\fR returns the token for an existing cursor, given
+the window and description used to create the cursor.
+\fBTk_GetCursorFromObj\fR doesn't actually create the cursor; the cursor
+must already have been created with a previous call to
+\fBTk_AllocCursorFromObj\fR or \fBTk_GetCursor\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetCursorFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
+.PP
 \fBTk_GetCursorFromData\fR allows cursors to be created from
-in-memory descriptions of their source and mask bitmaps.  \fISource\fR
-points to standard bitmap data for the cursor's source bits, and
-\fImask\fR points to standard bitmap data describing
+in-memory descriptions of their source and mask cursors.  \fISource\fR
+points to standard cursor data for the cursor's source bits, and
+\fImask\fR points to standard cursor data describing
 which pixels of \fIsource\fR are to be drawn and which are to be
 considered transparent.  \fIWidth\fR and \fIheight\fR give the
 dimensions of the cursor, \fIxHot\fR and \fIyHot\fR indicate the
@@ -135,24 +179,26 @@ cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
 	source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
 .CE
 .PP
-Under normal conditions, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR
+Under normal conditions \fBTk_GetCursorFromData\fR
 will return an identifier for the requested cursor.  If an error
-occurs in creating the cursor, such as when \fInameId\fR refers
-to a non-existent file, then \fBNone\fR is returned and an error
-message will be stored in \fIinterp->result\fR.
+occurs in creating the cursor then \fBNone\fR is returned and an error
+message will be stored in \fIinterp\fR's result.
 .PP
-\fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR maintain a
+\fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, and
+\fBTk_GetCursorFromData\fR maintain a
 database of all the cursors they have created.  Whenever possible,
-a call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR will
+a call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR, or
+\fBTk_GetCursorFromData\fR will
 return an existing cursor rather than creating a new one.  This
 approach can substantially reduce server overhead, so the Tk
 procedures should generally be used in preference to Xlib procedures
 like \fBXCreateFontCursor\fR or \fBXCreatePixmapCursor\fR, which
-create a new cursor on each call.
+create a new cursor on each call.  The Tk procedures are also more
+portable than the lower-level X procedures.
 .PP
 The procedure \fBTk_NameOfCursor\fR is roughly the inverse of
 \fBTk_GetCursor\fR.  If its \fIcursor\fR argument was created
-by \fBTk_GetCursor\fR, then the return value is the \fInameId\fR
+by \fBTk_GetCursor\fR, then the return value is the \fIname\fR
 argument that was passed to \fBTk_GetCursor\fR to create the
 cursor.  If \fIcursor\fR was created by a call to \fBTk_GetCursorFromData\fR,
 or by any other mechanism, then the return value is a hexadecimal string
@@ -162,17 +208,24 @@ only guaranteed to persist until the next call to
 \fBTk_NameOfCursor\fR.  Also, this call is not portable except for
 cursors returned by \fBTk_GetCursor\fR.
 .PP
-When a cursor returned by \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR
-is no longer needed, \fBTk_FreeCursor\fR should be called to release it.
+.VS 8.1
+When a cursor returned by \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+or \fBTk_GetCursorFromData\fR
+is no longer needed, \fBTk_FreeCursorFromObj\fR or
+\fBTk_FreeCursor\fR should be called to release it.
+For \fBTk_FreeCursorFromObj\fR the cursor to release is specified
+with the same information used to create it; for
+\fBTk_FreeCursor\fR the cursor to release is specified
+with its Tk_Cursor token.
 There should be exactly one call to \fBTk_FreeCursor\fR for
-each call to \fBTk_GetCursor\fR or \fBTk_GetCursorFromData\fR.
-When a cursor is no longer in use anywhere (i.e. it has been freed as
-many times as it has been gotten) \fBTk_FreeCursor\fR will release
-it to the X server and remove it from the database.
+each call to \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+or \fBTk_GetCursorFromData\fR.
+.VE
 
 .SH BUGS
 In determining whether an existing cursor can be used to satisfy
-a new request, \fBTk_GetCursor\fR and \fBTk_GetCursorFromData\fR
+a new request, \fBTk_AllocCursorFromObj\fR, \fBTk_GetCursor\fR,
+and \fBTk_GetCursorFromData\fR
 consider only the immediate values of their arguments.  For
 example, when a file name is passed to \fBTk_GetCursor\fR,
 \fBTk_GetCursor\fR will assume it is safe to re-use an existing
diff --git a/doc/GetFont.3 b/doc/GetFont.3
index 8971913..f052935 100644
--- a/doc/GetFont.3
+++ b/doc/GetFont.3
@@ -1,74 +1,122 @@
 '\"
 '\" Copyright (c) 1990-1992 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetFont.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
+'\" RCS: @(#) $Id: GetFont.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetFont 3 "" Tk "Tk Library Procedures"
+.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts
+Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
 Tk_Font 
-\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
+\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_Font 
+\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR 
+.sp
+Tk_Font 
+\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 char *
 \fBTk_NameOfFont(\fItkfont\fB)\fR
 .sp
+.VS 8.1
+Tk_Font 
+\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 void
 \fBTk_FreeFont(\fItkfont\fB)\fR
 
 .SH ARGUMENTS
 .AS "const char" *tkfont
 .AP "Tcl_Interp" *interp in
-Interpreter to use for error reporting.
+Interpreter to use for error reporting.  If NULL, then no error
+messages are left after errors.
 .AP Tk_Window tkwin in
-Token for window on the display in which font will be used.
+Token for window in which font will be used.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+Gives name or description of font.  See documentation
+for the \fBfont\fR command for details on acceptable formats.
+Internal rep will be modified to cache corresponding Tk_Font.
 .AP "const char" *string in
-Name or description of desired font.  See documentation for the \fBfont\fR 
-command for details on acceptable formats.
+Same as \fIobjPtr\fR except description of font is passed as a string and
+resulting Tk_Font isn't cached.
+.VE
 .AP Tk_Font tkfont in
 Opaque font token.
 .BE
 .SH DESCRIPTION
 .PP
-\fBTk_GetFont\fR finds the font indicated by \fIstring\fR and returns a
-token that represents the font.  The return value can be used in subsequent
-calls to procedures such as \fBTk_FontMetrics\fR, \fBTk_MeasureChars\fR, and
-\fBTk_FreeFont\fR.  The token returned by \fBTk_GetFont\fR will remain
-valid until \fBTk_FreeFont\fR is called to release it.  \fIString\fR can
-be either a symbolic name or a font description; see the documentation for
-the \fBfont\fR command for a description of the valid formats.  If
-\fBTk_GetFont\fR is unsuccessful (because, for example, \fIstring\fR was
-not a valid font specification) then it returns \fBNULL\fR and stores an
-error message in \fIinterp->result\fR.
+.VS 8.1
+\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and
+returns a token that represents the font.  The return value can be used
+in subsequent calls to procedures such as \fBTk_FontMetrics\fR,
+\fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR.  The Tk_Font token
+will remain valid until
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. 
+\fIObjPtr\fR can contain either a symbolic name or a font description; see
+the documentation for the \fBfont\fR command for a description of the
+valid formats.  If \fBTk_AllocFontFromObj\fR is unsuccessful (because,
+for example, \fIobjPtr\fR did not contain a valid font specification) then it
+returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result
+if \fIinterp\fR isn't NULL.  \fBTk_AllocFontFromObj\fR caches
+information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR.
+.PP
+\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except
+that the description of the font is specified with a string instead
+of an object.  This prevents \fBTk_GetFont\fR from caching the
+matching Tk_Font, so \fBTk_GetFont\fR is less efficient than
+\fBTk_AllocFontFromObj\fR.
+.PP
+\fBTk_GetFontFromObj\fR returns the token for an existing font, given
+the window and description used to create the font.
+\fBTk_GetFontFromObj\fR doesn't actually create the font; the font
+must already have been created with a previous call to
+\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
-\fBTk_GetFont\fR maintains a database of all fonts it has allocated.  If
-the same \fIstring\fR is requested multiple times (e.g. by different
-windows or for different purposes), then additional calls for the same
-\fIstring\fR will be handled without involving the platform-specific
-graphics server.
+\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain
+a database of all fonts they have allocated.  If
+the same font is requested multiple times (e.g. by different
+windows or for different purposes), then a single Tk_Font will be
+shared for all uses.  The underlying resources will be freed automatically
+when no-one is using the font anymore.
 .PP
 The procedure \fBTk_NameOfFont\fR is roughly the inverse of
 \fBTk_GetFont\fR.  Given a \fItkfont\fR that was created by
-\fBTk_GetFont\fR, the return value is the \fIstring\fR argument that was
+\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is
+the \fIstring\fR argument that was
 passed to \fBTk_GetFont\fR to create the font.  The string returned by
 \fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR
 is deleted.  The caller must not modify this string.
 .PP
-When a font returned by \fBTk_GetFont\fR is no longer needed,
-\fBTk_FreeFont\fR should be called to release it.  There should be
-exactly one call to \fBTk_FreeFont\fR for each call to \fBTk_GetFont\fR.
-When a font is no longer in use anywhere (i.e. it has been freed as many
-times as it has been gotten) \fBTk_FreeFont\fR will release any
-platform-specific storage and delete it from the database.  
+.VS 8.1
+When a font is no longer needed,
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to
+release it.  For \fBTk_FreeFontFromObj\fR the font to release is specified
+with the same information used to create it; for
+\fBTk_FreeFont\fR the font to release is specified
+with its Tk_Font token.  There should be
+exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR
+for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.
+.VE
 
 .SH KEYWORDS
 font
diff --git a/doc/GetJustify.3 b/doc/GetJustify.3
index 6b12be1..68dced7 100644
--- a/doc/GetJustify.3
+++ b/doc/GetJustify.3
@@ -1,22 +1,26 @@
 '\"
 '\" Copyright (c) 1990-1994 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetJustify.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
+'\" RCS: @(#) $Id: GetJustify.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetJustify 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_GetJustifyFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
+Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
-Tk_Justify
+.VS 8.1
+int
+\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR
+.sp
+int
 \fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR
 .sp
 char *
@@ -24,21 +28,30 @@ char *
 .SH ARGUMENTS
 .AS "Tk_Justify" *justifyPtr
 .AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+Interpreter to use for error reporting, or NULL.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value contains name of justification style (\fBleft\fR, \fBright\fR, or
+\fBcenter\fR).  The
+internal rep will be modified to cache corresponding justify value.
 .AP char *string in
-String containing name of justification style (``left'', ``right'', or
-``center'').
+Same as \fIobjPtr\fR except description of justification style is passed as
+a string.
+.VE
 .AP int *justifyPtr out
 Pointer to location in which to store justify value corresponding to
-\fIstring\fR.
+\fIobjPtr\fR or \fIstring\fR.
 .AP Tk_Justify justify in
 Justification style (one of the values listed below).
 .BE
 
 .SH DESCRIPTION
 .PP
-\fBTk_GetJustify\fR places in \fI*justifyPtr\fR the justify value
-corresponding to \fIstring\fR.  This value will be one of the following:
+.VS 8.1
+\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value
+corresponding to \fIobjPtr\fR's value.
+.VE
+This value will be one of the following:
 .TP
 \fBTK_JUSTIFY_LEFT\fR
 Means that the text on each line should start at the left edge of
@@ -52,12 +65,23 @@ the line;  as a result, the left edges of lines may be ragged.
 Means that the text on each line should be centered;  as a result,
 both the left and right edges of lines may be ragged.
 .PP
+.VS 8.1
 Under normal circumstances the return value is \fBTCL_OK\fR and
 \fIinterp\fR is unused.
-If \fIstring\fR doesn't contain a valid justification style
-or an abbreviation of one of these names, then an error message is
-stored in \fIinterp->result\fR, \fBTCL_ERROR\fR is returned, and
-\fI*justifyPtr\fR is unmodified.
+If \fIobjPtr\fR doesn't contain a valid justification style
+or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,
+\fI*justifyPtr\fR is unmodified, and an error message is
+stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
+\fBTk_GetJustifyFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetJustifyFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetJustify\fR is identical to \fBTk_GetJustifyFromObj\fR except
+that the description of the justification is specified with a string instead
+of an object.  This prevents \fBTk_GetJustify\fR from caching the
+return value, so \fBTk_GetJustify\fR is less efficient than
+\fBTk_GetJustifyFromObj\fR.
+.VE
 .PP
 \fBTk_NameOfJustify\fR is the logical inverse of \fBTk_GetJustify\fR.
 Given a justify value it returns a statically-allocated string
diff --git a/doc/GetPixels.3 b/doc/GetPixels.3
index 6c271a7..3df2985 100644
--- a/doc/GetPixels.3
+++ b/doc/GetPixels.3
@@ -1,24 +1,34 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetPixels.3,v 1.2 1998/09/14 18:22:50 stanton Exp $
+'\" RCS: @(#) $Id: GetPixels.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetPixels 3 "" Tk "Tk Library Procedures"
+.TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetPixels, Tk_GetScreenMM \- translate between strings and screen units
+Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
+int
+\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR
+.VE
+.sp
 int
 \fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR
 .sp
+.VS 8.1
+int
+\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
+.VE
+.sp
 int
 \fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR
 .SH ARGUMENTS
@@ -27,9 +37,15 @@ int
 Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Window whose screen geometry determines the conversion between absolute
-units and pixels. 
+units and pixels.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value specifies a distance on the screen;
+internal rep will be modified to cache converted distance.
 .AP char *string in
-String that specifies a distance on the screen.
+Same as \fIobjPtr\fR except specification of distance is passed as
+a string.
+.VE
 .AP int *intPtr out
 Pointer to location in which to store converted distance in pixels.
 .AP double *doublePtr out
@@ -38,10 +54,16 @@ Pointer to location in which to store converted distance in millimeters.
 
 .SH DESCRIPTION
 .PP
-These two procedures take as argument a specification of distance on
-the screen (\fIstring\fR) and compute the corresponding distance
-either in integer pixels or floating-point millimeters.
-In either case, \fIstring\fR specifies a screen distance as a
+These procedures take as argument a specification of distance on
+.VS 8.1
+the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
+.VE
+corresponding distance either in integer pixels or floating-point millimeters.
+In either case,
+.VS 8.1
+\fIobjPtr\fR or \fIstring\fR
+.VE
+specifies a screen distance as a
 floating-point number followed by one of the following characters
 that indicates units:
 .TP
@@ -61,16 +83,29 @@ The number specifies a distance in millimeters on the screen.
 The number specifies a distance in printer's points (1/72 inch)
 on the screen.
 .PP
-\fBTk_GetPixels\fR converts \fIstring\fR to the nearest even
-number of pixels and stores that value at \fI*intPtr\fR.
-\fBTk_GetScreenMM\fR converts \fIstring\fR to millimeters and
-stores the double-precision floating-point result at \fI*doublePtr\fR.
-.PP
-Both procedures return \fBTCL_OK\fR under normal circumstances.
-If an error occurs (e.g. \fIstring\fR contains a number followed
+.VS 8.1
+\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
+nearest even number of pixels and stores that value at \fI*intPtr\fR.
+It returns \fBTCL_OK\fR under normal circumstances.
+If an error occurs (e.g. \fIobjPtr\fR contains a number followed
 by a character that isn't one of the ones above) then
 \fBTCL_ERROR\fR is returned and an error message is left
-in \fIinterp->result\fR.
+in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
+\fBTk_GetPixelsFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except
+that the screen distance is specified with a string instead
+of an object.  This prevents \fBTk_GetPixels\fR from caching the
+return value, so \fBTk_GetAnchor\fR is less efficient than
+\fBTk_GetPixelsFromObj\fR.
+.PP
+\fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to
+\fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except
+that they convert the screen distance to millimeters and
+store a double-precision floating-point result at \fI*doublePtr\fR.
+.VE
 
 .SH KEYWORDS
 centimeters, convert, inches, millimeters, pixels, points, screen units
diff --git a/doc/GetRelief.3 b/doc/GetRelief.3
index 20d2933..a85280e 100644
--- a/doc/GetRelief.3
+++ b/doc/GetRelief.3
@@ -1,21 +1,26 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetRelief.3,v 1.2 1998/09/14 18:22:51 stanton Exp $
+'\" RCS: @(#) $Id: GetRelief.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetRelief 3 "" Tk "Tk Library Procedures"
+.TH Tk_GetReliefFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
+Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings and relief values
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
+int
+\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR
+.VE
+.sp
 int
 \fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR
 .sp
@@ -25,12 +30,18 @@ char *
 .AS "Tcl_Interp" *reliefPtr
 .AP Tcl_Interp *interp in
 Interpreter to use for error reporting.
-.AP char *name in
-String containing relief name (one of ``flat'', ``groove'',
-``raised'', ``ridge'', ``solid'', or ``sunken'').
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value contains name of relief (one of \fBflat\fR, \fBgroove\fR,
+\fBraised\fR, \fBridge\fR, \fBsolid\fR, or \fBsunken\fR);
+internal rep will be modified to cache corresponding relief value.
+.AP char *string in
+Same as \fIobjPtr\fR except description of relief is passed as
+a string.
+.VE
 .AP int *reliefPtr out
 Pointer to location in which to store relief value corresponding to
-\fIname\fR.
+\fIobjPtr\fR or \fIname\fR.
 .AP int relief in
 Relief value (one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN,
 TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE).
@@ -38,20 +49,31 @@ TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE).
 
 .SH DESCRIPTION
 .PP
-\fBTk_GetRelief\fR places in \fI*reliefPtr\fR the relief value
-corresponding to \fIname\fR.  This value will be one of
+.VS 8.1
+\fBTk_GetReliefFromObj\fR places in \fI*reliefPtr\fR the relief value
+corresponding to the value of \fIobjPtr\fR.  This value will be one of
 TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN,
 TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE.
 Under normal circumstances the return value is TCL_OK and
 \fIinterp\fR is unused.
-If \fIname\fR doesn't contain one of the valid relief names
-or an abbreviation of one of them, then an error message
-is stored in \fIinterp->result\fR,
-TCL_ERROR is returned, and \fI*reliefPtr\fR is unmodified.
+If \fIobjPtr\fR doesn't contain one of the valid relief names
+or an abbreviation of one of them, then TCL_ERROR is returned,
+\fI*reliefPtr\fR is unmodified, and an error message
+is stored in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
+\fBTk_GetReliefFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to
+\fBTk_GetReliefFromObj\fR with the same \fIobjPtr\fR.
+.PP
+\fBTk_GetRelief\fR is identical to \fBTk_GetReliefFromObj\fR except
+that the description of the relief is specified with a string instead
+of an object.  This prevents \fBTk_GetRelief\fR from caching the
+return value, so \fBTk_GetRelief\fR is less efficient than
+\fBTk_GetReliefFromObj\fR.
+.VE
 .PP
 \fBTk_NameOfRelief\fR is the logical inverse of \fBTk_GetRelief\fR.
-Given a relief value it returns the corresponding string (``flat'',
-``raised'', ``sunken'', ``groove'', ``solid'', or ``ridge'').
+Given a relief value it returns the corresponding string (\fBflat\fR,
+\fBraised\fR, \fBsunken\fR, \fBgroove\fR, \fBsolid\fR, or \fBridge\fR).
 If \fIrelief\fR isn't a legal relief value, then ``unknown relief''
 is returned.
 
diff --git a/doc/MeasureChar.3 b/doc/MeasureChar.3
index 53baf88..2df934c 100644
--- a/doc/MeasureChar.3
+++ b/doc/MeasureChar.3
@@ -4,10 +4,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: MeasureChar.3,v 1.2 1998/09/14 18:22:52 stanton Exp $
+'\" RCS: @(#) $Id: MeasureChar.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_MeasureChars 3 "" Tk "Tk Library Procedures"
+.TH Tk_MeasureChars 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
 Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
@@ -16,16 +16,16 @@ Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to me
 \fB#include <tk.h>\fR
 .sp
 int
-\fBTk_MeasureChars(\fItkfont, string, maxChars, maxPixels, flags, lengthPtr\fB)\fR
+\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
 .sp
 int
-\fBTk_TextWidth(\fItkfont, string, numChars\fB)\fR
+\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
 .sp
 void
-\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numChars, x, y\fB)\fR
+\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
 .sp
 void
-\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstChar, lastChar\fB)\fR
+\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
 .sp
 .SH ARGUMENTS
 .AS "const char" firstChar
@@ -37,9 +37,11 @@ Text to be measured or displayed.  Need not be null terminated.  Any
 non-printing meta-characters in the string (such as tabs, newlines, and
 other control characters) will be measured or displayed in a
 platform-dependent manner.  
-.AP int maxChars in
-The maximum number of characters to consider when measuring \fIstring\fR.
-Must be greater than or equal to 0.
+.VS 8.1
+.AP int numBytes in
+The maximum number of bytes to consider when measuring or drawing
+\fIstring\fR.  Must be greater than or equal to 0.
+.VE 8.1
 .AP int maxPixels in
 If \fImaxPixels\fR is greater than 0, it specifies the longest permissible
 line length in pixels.  Characters from \fIstring\fR are processed only
@@ -59,9 +61,6 @@ letter will still be returned.
 .AP int *lengthPtr out
 Filled with the number of pixels occupied by the number of characters
 returned as the result of \fBTk_MeasureChars\fR.
-.AP int numChars in
-The total number of characters to measure or draw from \fIstring\fR.  Must
-be greater than or equal to 0.
 .AP Display *display in
 Display on which to draw.
 .AP Drawable drawable in
@@ -72,13 +71,15 @@ must be the same as the \fItkfont\fR.
 .AP int "x, y" in
 Coordinates at which to place the left edge of the baseline when displaying
 \fIstring\fR.  
-.AP int firstChar in
-The index of the first character to underline in the \fIstring\fR.  
-Underlining begins at the left edge of this character.
-.AP int lastChar in
-The index of the last character up to which the underline will 
-be drawn.  The character specified by \fIlastChar\fR will not itself be
-underlined.
+.VS 8.1
+.AP int firstByte in
+The index of the first byte of the first character to underline in the
+\fIstring\fR.  Underlining begins at the left edge of this character.
+.AP int lastByte in
+The index of the first byte of the last character up to which the
+underline will be drawn.  The character specified by \fIlastByte\fR
+will not itself be underlined.
+.VE 8.1
 .BE
 
 .SH DESCRIPTION
@@ -88,7 +89,13 @@ single-line, strings.  To measure and display single-font, multi-line,
 justified text, refer to the documentation for \fBTk_ComputeTextLayout\fR.
 There is no programming interface in the core of Tk that supports
 multi-font, multi-line text; support for that behavior must be built on
-top of simpler layers.
+top of simpler layers.  
+.VS 8.1
+Note that the interfaces described here are
+byte-oriented not character-oriented, so index values coming from Tcl
+scripts need to be converted to byte offsets using the
+\fBTcl_UtfAtIndex\fR and related routines.
+.VE 8.1
 .PP
 A glyph is the displayable picture of a letter, number, or some other
 symbol.  Not all character codes in a given font have a glyph.
@@ -103,10 +110,10 @@ newlines/returns into multi-line text.
 .PP
 \fBTk_MeasureChars\fR is used both to compute the length of a given
 string and to compute how many characters from a string fit in a given
-amount of space.  The return value is the number of characters from
+amount of space.  The return value is the number of bytes from
 \fIstring\fR that fit in the space specified by \fImaxPixels\fR subject to
 the conditions described by \fIflags\fR.  If all characters fit, the return
-value will be \fImaxChars\fR.  \fI*lengthPtr\fR is filled with the computed
+value will be \fInumBytes\fR.  \fI*lengthPtr\fR is filled with the computed
 width, in pixels, of the portion of the string that was measured.  For
 example, if the return value is 5, then \fI*lengthPtr\fR is filled with the
 distance between the left edge of \fIstring\fR[0] and the right edge of
diff --git a/doc/SetOptions.3 b/doc/SetOptions.3
new file mode 100644
index 0000000..4a6a1a4
--- /dev/null
+++ b/doc/SetOptions.3
@@ -0,0 +1,502 @@
+'\"
+'\" Copyright (c) 1998 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: SetOptions.3,v 1.2 1999/04/16 01:51:08 stanton Exp $
+'\" 
+.so man.macros
+.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue,  Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Tk_OptionTable
+\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
+.sp
+\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
+.sp
+int
+\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
+.sp
+int
+\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
+.sp
+\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
+.sp
+\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
+.sp
+Tcl_Obj *
+\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+.sp
+Tcl_Obj *
+\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+.sp
+\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
+.sp
+int
+\fBTk_Offset(\fItype, field\fB)\fR
+.SH ARGUMENTS
+.AS Tk_SavedOptions "*CONST objv[]" in/out
+.AP Tcl_Interp *interp in
+A Tcl interpreter.  Most procedures use this only for returning error
+messages; if it is NULL then no error messages are returned.  For
+\fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the
+interpreter in which the option table will be used.
+.AP Tk_OptionSpec *templatePtr in
+Points to an array of static information that describes the configuration
+options that are supported.  Used to build a Tk_OptionTable.  The information
+pointed to by this argument must exist for the lifetime of the Tk_OptionTable.
+.AP Tk_OptionTable optionTable in
+Token for an option table.  Must have been returned by a previous call
+to \fBTk_CreateOptionTable\fR.
+.AP char *recordPtr in/out
+Points to structure in which values of configuration options are stored;
+fields of this record are modified by procedures such as \fBTk_SetOptions\fR
+and read by procedures such as \fBTk_GetOptionValue\fR.
+.AP Tk_Window tkwin in
+For options such as TK_OPTION_COLOR, this argument indicates
+the window in which the option will be used.  If \fIoptionTable\fR uses
+no window-dependent options, then a NULL value may be supplied for
+this argument.
+.AP int objc in
+Number of values in \fIobjv\fR.
+.AP Tcl_Obj "*CONST objv[]" in
+Command-line arguments for setting configuring options.
+.AP Tk_SavedOptions *savePtr out
+If not NULL, the structure pointed to by this argument is filled
+in with the old values of any options that were modified and old
+values are restored automatically if an error occurs in \fBTk_SetOptions\fR.
+.AP int *maskPtr out
+If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the
+bit-wise OR of the \fItypeMask\fR fields for the options that
+were modified.
+.AP Tk_SavedOptions *savedPtr in/out
+Points to a structure previously filled in by \fBTk_SetOptions\fR with
+old values of modified options.
+.AP Tcl_Obj *namePtr in
+The value of this object is the name of a particular option.  If NULL
+is passed to \fBTk_GetOptionInfo\fR then information is returned for
+all options.  Must not be NULL when \fBTk_GetOptionValue\fR is called.
+.AP "type name" type in
+The name of the type of a record.
+.AP "field name" field in
+The name of a field in records of type \fItype\fR.
+.BE
+.SH DESCRIPTION
+.PP
+These procedures handle most of the details of parsing configuration
+options such as those for Tk widgets.  Given a description of what
+options are supported, these procedures handle all the details of
+parsing options and storing their values into a C structure associated
+with the widget or object. The procedures were designed primarily for
+widgets in Tk, but they can also be used for other kinds of objects that
+have configuration options.  In the rest of this manual page ``widget'' will
+be used to refer to the object whose options are being managed; in
+practice the object may not actually be a widget.  The term ``widget
+record'' is used to refer to the C-level structure in
+which information about a particular widget or object is stored.
+.PP
+Note: the easiest way to learn how to use these procedures is to
+look at a working example.  In Tk, the simplest example is the code
+that implements the button family of widgets, which is an \fBtkButton.c\fR.
+Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
+.PP
+In order to use these procedures, the code that implements the widget
+must contain a static array of Tk_OptionSpec structures. This is a
+template that describes the various options supported by that class of
+widget; there is a separate template for each kind of widget.  The
+template contains information such as the name of each option, its type,
+its default value, and where the value of the option is stored in the
+widget record.  See TEMPLATES below for more detail.
+.PP
+In order to process configuration options efficiently, the static
+template must be augmented with additional information that is available
+only at runtime.  The procedure \fBTk_CreateOptionTable\fR creates this
+dynamic information from the template and returns a Tk_OptionTable token
+that describes both the static and dynamic information.  All of the
+other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable
+token as argument.  Typically, \fBTk_CreateOptionTable\fR is called the
+first time that a widget of a particular class is created and the
+resulting Tk_OptionTable is used in the future for all widgets of that
+class.  A Tk_OptionTable may be used only in a single interpreter, given
+by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR.  When an
+option table is no longer needed \fBTk_DeleteOptionTable\fR should be
+called to free all of its resources.  All of the option tables
+for a Tcl interpreter are freed automatically if the interpreter is deleted.
+.PP
+\fBTk_InitOptions\fR is invoked when a new widget is created to set
+the default values for all of the widget's configuration options.
+\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR)
+and a pointer to a widget record (\fIrecordPtr\fR), which is the C
+structure that holds information about this widget. \fBTk_InitOptions\fR
+uses the information in the option table to
+choose an appropriate default for each option, then it stores the default
+value directly into the widget record, overwriting any information that
+was already present in the widget record.  \fBTk_InitOptions\fR normally
+returns TCL_OK.  If an error occurred while setting the default values
+(e.g., because a default value was erroneous) then TCL_ERROR is returned
+and an error message is left in \fIinterp\fR's result if \fIinterp\fR
+isn't NULL.
+.PP
+\fBTk_SetOptions\fR is invoked to modify configuration options based
+on information specified in a Tcl command.  The command might be one that
+creates a new widget, or a command that modifies options on an existing
+widget.  The \fIobjc\fR and \fIobjv\fR arguments describe the
+values of the arguments from the Tcl command.  \fIObjv\fR must contain
+an even number of objects: the first object of each pair gives the name of
+an option and the second object gives the new value for that option.
+\fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that
+the new value of the option conforms to the type in \fIoptionTable\fR,
+and stores the value of the option into the widget record given by
+\fIrecordPtr\fR.  \fBTk_SetOptions\fR normally returns TCL_OK.  If
+an error occurred (such as an unknown option name or an illegal option
+value) then TCL_ERROR is returned and an error message is left in
+\fIinterp\fR's result if \fIinterp\fR isn't NULL.
+.PP
+\fBTk_SetOptions\fR has two additional features.  First, if the
+\fImaskPtr\fR argument isn't NULL then it points to an integer
+value that is filled in with information about the options that were
+modified.  For each option in the template passed to
+\fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field.  The
+bits of this field are defined by the code that implements the widget;
+for example, each bit might correspond to a particular configuration option.
+Alternatively, bits might be used functionally.  For example, one bit might
+be used for redisplay: all options that affect the widget's display, such
+that changing the option requires the widget to be redisplayed, might have
+that bit set.  Another bit might indicate that the geometry of the widget
+must be recomputed, and so on.  \fBTk_SetOptions\fR OR's together the
+\fItypeMask\fR fields from all the options that were modified and returns
+this value at *\fImaskPtr\fR; the caller can then use this information
+to optimize itself so that, for example, it doesn't redisplay the widget
+if the modified options don't affect the widget's appearance.
+.PP
+The second additional feature of \fBTk_SetOptions\fR has to do with error
+recovery.  If an error occurs while processing configuration options, this
+feature makes it possible to restore all the configuration options to their
+previous values.  Errors can occur either while processing options in
+\fBTk_SetOptions\fR or later in the caller.  In many cases the caller does
+additional processing after \fBTk_SetOptions\fR returns; for example, it
+might use an option value to set a trace on a variable and may detect
+an error if the variable is an array instead of a scalar.  Error recovery
+is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument
+to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized
+Tk_SavedOptions structure on the caller's stack.  \fBTk_SetOptions\fR
+overwrites the structure pointed to by \fIsavePtr\fR with information
+about the old values of any options modified by the procedure.
+If \fBTk_SetOptions\fR returns successfully, the
+caller uses the structure in one of two ways.  If the caller completes
+its processing of the new options without any errors, then it must pass
+the structure to \fBTk_FreeSavedOptions\fR so that the old values can be
+freed.  If the caller detects an error in its processing of the new
+options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR,
+which will copy the old values back into the widget record and free
+the new values.
+If \fBTk_SetOptions\fR detects an error then it automatically restores
+any options that had already been modified and leaves *\fIsavePtr\fR in
+an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or
+\fBTk_RestoreSavedOptions\fR.
+If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then
+\fBTk_SetOptions\fR frees each old option value immediately when it sets a new
+value for the option.  In this case, if an error occurs in the third
+option, the old values for the first two options cannot be restored.
+.PP
+\fBTk_GetOptionValue\fR returns the current value of a configuration option
+for a particular widget.  The \fInamePtr\fR argument contains the name of
+an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR
+to lookup the option and extract its value from the widget record
+pointed to by \fIrecordPtr\fR, then it returns an object containing
+that value.  If an error occurs (e.g., because \fInamePtr\fR contains an
+unknown option name) then NULL is returned and an error message is left
+in \fIinterp\fR's result unless \fIinterp\fR is NULL.
+.PP
+\fBTk_GetOptionInfo\fR returns information about configuration options in
+a form suitable for \fBconfigure\fR widget commands.  If the \fInamePtr\fR
+argument is not NULL, it points to an object that gives the name of a
+configuration option; \fBTk_GetOptionInfo\fR returns an object containing
+a list with five elements, which are the name of the option, the name and
+class used for the option in the option database, the default value for
+the option, and the current value for the option.  If the \fInamePtr\fR
+argument is NULL, then \fBTk_GetOptionInfo\fR returns information about
+all options in the form of a list of lists; each sublist describes one
+option.  Synonym options are handled differently depending on whether
+\fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for
+each synonym option has only two elements, which are the name of the
+option and the name of the other option that it refers to; if \fInamePtr\fR
+is non-NULL and names a synonym option then the object returned
+is the five-element list
+for the other option that the synonym refers to.  If an error occurs
+(e.g., because \fInamePtr\fR contains an unknown option name) then NULL
+is returned and an error message is left in \fIinterp\fR's result unless
+\fIinterp\fR is NULL.
+.PP
+\fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted.
+It frees all of the resources associated with any of the configuration
+options defined in \fIrecordPtr\fR by \fIoptionTable\fR.
+.PP
+The \fBTk_Offset\fR macro is provided as a safe way of generating the
+\fIobjOffset\fR and \fIinternalOffset\fR values for entries in
+Tk_OptionSpec structures.  It takes two arguments: the name of a type
+of record, and the name of a field in that record. It returns the byte
+offset of the named field in records of the given type.
+
+.SH "TEMPLATES"
+.PP
+The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR
+via its \fItemplatePtr\fR argument describes the configuration options
+supported by a particular class of widgets.  Each structure specifies
+one configuration option and has the following fields:
+.CS
+typedef struct {
+	Tk_OptionType \fItype\fR;
+	char *\fIoptionName\fR;
+	char *\fIdbName\fR;
+	char *\fIdbClass\fR;
+	char *\fIdefValue\fR;
+	int \fIobjOffset\fR;
+	int \fIinternalOffset\fR;
+	int \fIflags\fR;
+	ClientData \fIclientData\fR;
+	int \fItypeMask\fR;
+} Tk_OptionSpec;
+.CE
+The \fItype\fR field indicates what kind of configuration option this is
+(e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for
+an integer value).  \fIType\fR determines how the
+value of the option is parsed (more on this below).
+The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR;
+it is the name used for the option in Tcl commands and passed to
+procedures via the \fIobjc\fR or \fInamePtr\fR arguments.
+The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR
+to look up a default value for this option in the option database; if
+\fIdbName\fR is NULL then the option database is not used by
+\fBTk_InitOptions\fR for this option.  The \fIdefValue\fR field
+specifies a default value for this configuration option if no
+value is specified in the option database.  The \fIobjOffset\fR and
+\fIinternalOffset\fR fields indicate where to store the value of this
+option in widget records (more on this below); values for the \fIobjOffset\fR
+and \fIinternalOffset\fR fields should always be generated with the
+\fBTk_Offset\fR macro.
+The \fIflags\fR field contains additional information
+to control the processing of this configuration option (see below
+for details).
+\fIClientData\fR provides additional type-specific data needed
+by certain types.  For instance, for TK_OPTION_COLOR types,
+\fIclientData\fR is a string giving the default value to use on
+monochrome displays.  See the descriptions of the different types
+below for details.
+The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to
+return information about which options were modified; see the description
+of \fBTk_SetOptions\fR above for details.
+.PP
+When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an
+option into the widget record, they can do it in either of two ways.
+If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than
+or equal to zero, then the value of the option is stored as a
+(Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR.
+If the \fIinternalOffset\fR field of the Tk_OptionSpec is
+greater than or equal to zero, then the value of the option is stored
+in a type-specific internal form at the location in the widget record
+given by \fIinternalOffset\fR.  For example, if the option's type is
+TK_OPTION_INT then the internal form is an integer.  If the
+\fIobjOffset\fR or \fIinternalOffset\fR field is negative then the
+value is not stored in that form.  At least one of the offsets must be
+greater than or equal to zero.
+.PP
+The \fIflags\fR field consists of one or more bits ORed together.  At
+present only a single flag is supported: TK_OPTION_NULL_OK.  If
+this bit is set for an option then an empty string will be accepted as
+the value for the option and the resulting internal form will be a
+NULL pointer or \fBNone\fR, depending on the type of the option.
+If the flag is not set then empty strings will result
+in errors.
+TK_OPTION_NULL_OK is typically used to allow a
+feature to be turned off entirely, e.g. set a cursor value to
+\fBNone\fR so that a window simply inherits its parent's cursor.
+Not all option types support the TK_OPTION_NULL_OK
+flag; for those that do, there is an explicit indication of that fact
+in the descriptions below.
+.PP
+The \fItype\fR field of each Tk_OptionSpec structure determines
+how to parse the value of that configuration option. The
+legal value for \fItype\fR, and the corresponding actions, are
+described below.  If the type requires a \fItkwin\fR value to be
+passed into procedures like \fBTk_SetOptions\fR, or if it uses
+the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated
+explicitly; if not mentioned, the type requires neither \fItkwin\fR
+nor \fIclientData\fR.
+.TP
+\fBTK_OPTION_ANCHOR\fR
+The value must be a standard anchor position such as \fBne\fR or
+\fBcenter\fR.  The internal form is a Tk_Anchor value like the ones
+returned by \fBTk_GetAnchorFromObj\fR.
+.TP
+\fBTK_OPTION_BITMAP\fR
+The value must be a standard Tk bitmap name. The internal form is a
+Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_BOOLEAN\fR
+The value must be a standard boolean value such as \fBtrue\fR or
+\fBno\fR.  The internal form is an integer with value 0 or 1.
+.TP
+\fBTK_OPTION_BORDER\fR
+The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
+The internal form is a Tk_3DBorder token like the ones returned
+by \fBTk_Alloc3DBorderFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_COLOR\fR
+The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
+The internal form is an (XColor *) token like the ones returned by
+\fBTk_AllocColorFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_CURSOR\fR
+The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR.
+The internal form is a Tk_Cursor token like the ones returned by
+\fBTk_AllocCursorFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and when the option is set the cursor
+for the window is changed by calling \fBXDefineCursor\fR.  This
+option type also supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_DOUBLE\fR
+The string value must be a floating-point number in
+the format accepted by \fBstrtol\fR.  The internal form is a C
+\fBdouble\fR value.
+.TP
+\fBTK_OPTION_END\fR
+Marks the end of the template.  There must be a Tk_OptionSpec structure
+with \fItype\fR TK_OPTION_END at the end of each template.  If the
+\fIclientData\fR field of this structure isn't NULL, then it points to
+an additional array of Tk_OptionSpec's, which is itself terminated by
+another TK_OPTION_END entry.  Templates may be chained arbitrarily
+deeply.  This feature allows common options to be shared by several
+widget classes.
+.TP
+\fBTK_OPTION_FONT\fR
+The value must be a standard font name such as \fBTimes 16\fR.
+The internal form is a Tk_Font handle like the ones returned by
+\fBTk_AllocFontFromObj\fR.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_INT\fR
+The string value must be an integer in the format accepted by
+\fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to
+specify octal or hexadecimal numbers, respectively).  The internal
+form is a C \fBint\fR value.
+.TP
+\fBTK_OPTION_JUSTIFY\fR
+The value must be a standard justification value such as \fBleft\fR.
+The internal form is a Tk_Justify like the values returned by
+\fBTk_GetJustifyFromObj\fR.
+.TP
+\fBTK_OPTION_PIXELS\fR
+The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR.
+The internal form is an integer value giving a
+distance in pixels, like the values returned by
+\fBTk_GetPixelsFromObj\fR.  Note: if the \fIobjOffset\fR field isn't
+used then information about the original value of this option will be lost.
+See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.
+.TP
+\fBTK_OPTION_RELIEF\fR
+The value must be standard relief such as \fBraised\fR.
+The internal form is an integer relief value such as
+TK_RELIEF_RAISED.
+.TP
+\fBTK_OPTION_STRING\fR
+The value may be any string.  The internal form is a (char *) pointer
+that points to a dynamically allocated copy of the value.
+This option type supports the TK_OPTION_NULL_OK flag.
+.TP
+\fBTK_OPTION_STRING_TABLE\fR
+For this type, \fIclientData\fR is a pointer to an array of strings
+suitable for passing to \fBTcl_GetIndexFromObj\fR.  The value must
+be one of the strings in the table, or a unique abbreviation of
+one of the strings.  The internal form is an integer giving the index
+into the table of the matching string, like the return value
+from \fBTcl_GetStringFromObj\fR. 
+.TP
+\fBTK_OPTION_SYNONYM\fR
+This type is used to provide alternative names for an option (for
+example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR).
+The \fBclientData\fR field is a (char *) pointer that gives
+the name of another option in the same table.  Whenever the
+synonym option is used, the information from the other option
+will be used instead.
+.TP
+\fBTK_OPTION_WINDOW\fR
+The value must be a window path name.  The internal form is a
+\fBTk_Window\fR token for the window.
+This option type requires \fItkwin\fR to be supplied to procedures
+such as \fBTk_SetOptions\fR (in order to identify the application),
+and it supports the TK_OPTION_NULL_OK flag.
+
+.SH "STORAGE MANAGEMENT ISSUES"
+.PP
+If a field of a widget record has its offset stored in the \fIobjOffset\fR
+or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the
+procedures described here will handle all of the storage allocation and
+resource management issues associated with the field.  When the value
+of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR
+will automatically free any resources associated with the old value, such as
+Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for
+TK_OPTION_STRING options.  For an option stored as an object using the
+\fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the
+object pointed to by the \fIobjv\fR value from the call to
+\fBTk_SetOptions\fR.  The reference count for this object is incremented
+when a pointer to it is stored in the widget record and decremented when
+the option is modified.  When the widget is deleted
+\fBTk_FreeConfigOptions\fR should be invoked; it will free the resources
+associated with all options and decrement reference counts for any
+objects.
+.PP
+However, the widget code is responsible for storing NULL or \fBNone\fR in
+all pointer and token fields before invoking \fBTk_InitOptions\fR.
+This is needed to allow proper cleanup in the rare case where
+an error occurs in \fBTk_InitOptions\fR.
+
+.SH "OBJOFFSET VS. INTERNALOFFSET"
+.PP
+In most cases it is simplest to use the \fIinternalOffset\fR field of
+a Tk_OptionSpec structure and not the \fIobjOffset\fR field.  This
+makes the internal form of the value immediately available to the
+widget code so the value doesn't have to be extracted from an object
+each time it is used.  However, there are two cases where the
+\fIobjOffset\fR field is useful.  The first case is for
+TK_OPTION_PIXELS options.  In this case, the internal form is
+an integer pixel value that is valid only for a particular screen.
+If the value of the option is retrieved, it will be returned as a simple
+number.  For example, after the command \fB.b configure \-borderwidth 2m\fR,
+the command \fB.b configure \-borderwidth\fR might return 7, which is the
+integer pixel value corresponding to \fB2m\fR.  Unfortunately, this loses
+the original screen-independent value.  Thus for TK_OPTION_PIXELS options
+it is better to use the \fIobjOffset\fR field.  In this case the original
+value of the option is retained in the object and can be returned when
+the option is retrieved.  In most cases it is convenient to use the
+\fIinternalOffset\fR field field as well, so that the integer value is
+immediately available for use in the widget code (alternatively,
+\fBTk_GetPixelsFromObj\fR can be used to extract the integer value from
+the object whenever it is needed).  Note: the problem of losing information
+on retrievals exists only for TK_OPTION_PIXELS options.
+.PP
+The second reason to use the \fIobjOffset\fR field is in order to
+implement new types of options not supported by these procedures.
+To implement a new type of option, use TK_OPTION_STRING as
+the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field
+but not the \fIinternalOffset\fR field.  Then, after calling
+\fBTk_SetOptions\fR, convert the object to internal form yourself.
+
+.SH KEYWORDS
+anchor, bitmap, boolean, border, color, configuration option,
+cursor, double, font, integer, justify,
+pixels, relief, screen distance, synonym
diff --git a/doc/TextLayout.3 b/doc/TextLayout.3
index 35eaf34..41b17af 100644
--- a/doc/TextLayout.3
+++ b/doc/TextLayout.3
@@ -4,10 +4,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: TextLayout.3,v 1.2 1998/09/14 18:22:54 stanton Exp $
+'\" RCS: @(#) $Id: TextLayout.3,v 1.3 1999/04/16 01:51:09 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_ComputeTextLayout 3 "" Tk "Tk Library Procedures"
+.TH Tk_ComputeTextLayout 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
 Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
@@ -55,7 +55,10 @@ lifetime of the text layout.
 .AP int numChars in
 The number of characters to consider from \fIstring\fR.  If
 \fInumChars\fR is less than 0, then assumes \fIstring\fR is null
-terminated and uses \fBstrlen(\fIstring\fB)\fR.
+.VS 8.1
+terminated and uses \fBTcl_NumUtfChars\fR to determine the length of
+\fIstring\fR.
+.VE
 .AP int wrapLength in
 Longest permissible line length, in pixels.  Lines in \fIstring\fR will
 automatically be broken at word boundaries and wrapped when they reach
@@ -133,7 +136,14 @@ justified text.  To measure and display simple single-font, single-line
 strings, refer to the documentation for \fBTk_MeasureChars\fR.  There is
 no programming interface in the core of Tk that supports multi-font,
 multi-line text; support for that behavior must be built on top of
-simpler layers.
+simpler layers.  
+.VS 8.1
+Note that unlike the lower level text display routines, the functions
+described here all operate on character-oriented lengths and indices
+rather than byte-oriented values.  See the description of
+\fBTcl_UtfAtIndex\fR for more details on converting between character
+and byte offsets.
+.VE 8.1
 .PP
 The routines described here are built on top of the programming interface
 described in the \fBTk_MeasureChars\fR documentation.  Tab characters and
diff --git a/doc/messageBox.n b/doc/messageBox.n
index 927c120..d40dc17 100644
--- a/doc/messageBox.n
+++ b/doc/messageBox.n
@@ -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: messageBox.n,v 1.2 1998/09/14 18:22:58 stanton Exp $
+'\" RCS: @(#) $Id: messageBox.n,v 1.3 1999/04/16 01:51:09 stanton Exp $
 '\" 
 .so man.macros
 .TH tk_messageBox n 4.2 Tk "Tk Built-In Commands"
@@ -80,7 +80,7 @@ and \fBcancel\fR.
 .SH EXAMPLE
 .CS
 set answer [tk_messageBox \-message "Really quit?" \-type yesno \-icon question]
-case $answer {
+switch -- $answer {
     yes exit
     no {tk_messageBox \-message "I know you like this application!" \-type ok}
 }
diff --git a/doc/send.n b/doc/send.n
index 51ad739..7a74003 100644
--- a/doc/send.n
+++ b/doc/send.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: send.n,v 1.2 1998/09/14 18:23:00 stanton Exp $
+'\" RCS: @(#) $Id: send.n,v 1.3 1999/04/16 01:51:09 stanton Exp $
 '\" 
 .so man.macros
 .TH send n 4.0 Tk "Tk Built-In Commands"
@@ -70,8 +70,8 @@ command.
 
 .SH SECURITY
 .PP
-The \fBsend\fR command is potentially a serious security loophole,
-since any application that can connect to your X server can send
+The \fBsend\fR command is potentially a serious security loophole. On Unix,
+any application that can connect to your X server can send
 scripts to your applications.
 These incoming scripts can use Tcl to read and
 write your files and invoke subprocesses under your name.
@@ -87,6 +87,11 @@ list of enabled hosts is empty.
 This means that applications cannot connect to your server unless
 they use some other form of authorization
 such as that provide by \fBxauth\fR.
-
+.VS
+Under Windows, \fBsend\fR is currently disabled.  Most of the
+functionality is provided by the \fBdde\fR command instead.
+.VE
 .SH KEYWORDS
-application, name, remote execution, security, send
+.VS
+application, dde, name, remote execution, security, send
+.VE