(cherrypick): documentation escape sequence typo

1 files changed, 56 insertions, 75 deletions

diff --git a/doc/SetOptions.3 b/doc/SetOptions.3
index 2eb3b88..7163214 100644
--- a/doc/SetOptions.3
+++ b/doc/SetOptions.3
@@ -14,30 +14,31 @@ Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_Fr
 \fB#include <tk.h>\fR
 .sp
 Tk_OptionTable
-\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
+\fBTk_CreateOptionTable\fR(\fIinterp, templatePtr\fR)
 .sp
-\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
+\fBTk_DeleteOptionTable\fR(\fIoptionTable\fR)
 .sp
 int
-\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
+\fBTk_InitOptions\fR(\fIinterp, recordPtr, optionTable, tkwin\fR)
 .sp
 int
-\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
+\fBTk_SetOptions\fR(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fR)
 .sp
-\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
+\fBTk_FreeSavedOptions\fR(\fIsavedPtr\fR)
 .sp
-\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
+\fBTk_RestoreSavedOptions\fR(\fIsavedPtr\fR)
 .sp
 Tcl_Obj *
-\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+\fBTk_GetOptionValue\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR)
 .sp
 Tcl_Obj *
-\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
+\fBTk_GetOptionInfo\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR)
 .sp
-\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
+\fBTk_FreeConfigOptions\fR(\fIrecordPtr, optionTable, tkwin\fR)
 .sp
 int
 \fBTk_Offset(\fItype, field\fB)\fR
+.fi
 .SH ARGUMENTS
 .AS Tk_SavedOptions "*const objv[]" in/out
 .AP Tcl_Interp *interp in
@@ -101,7 +102,7 @@ practice the object may not actually be a widget.  The term
 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
+Note that 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 in \fBtkButton.c\fR.
 Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
@@ -310,8 +311,7 @@ greater than or equal to zero.
 .PP
 The \fIflags\fR field consists of one or more bits ORed together. The
 following flags are supported:
-.TP
-\fBTK_OPTION_NULL_OK\fR
+.IP \fBTK_OPTION_NULL_OK\fR
 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, a zero value, or \fBNone\fR, depending on the type of the option.
@@ -322,13 +322,13 @@ feature to be turned off entirely, e.g. set a cursor value to
 Not all option types support the \fBTK_OPTION_NULL_OK\fR
 flag; for those that do, there is an explicit indication of that fact
 in the descriptions below.
-.TP
-\fBTK_OPTION_DONT_SET_DEFAULT\fR
+.IP \fBTK_OPTION_DONT_SET_DEFAULT\fR
 If this bit is set for an option then no default value will be set in
 \fBTk_InitOptions\fR for this option. Neither the option database, nor any
 system default value, nor \fIoptionTable\fR are used to give a default
 value to this option. Instead it is assumed that the caller has already
 supplied a default value in the widget code.
+.RS
 .PP
 The \fItype\fR field of each Tk_OptionSpec structure determines
 how to parse the value of that configuration option. The
@@ -338,37 +338,34 @@ 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
+.RE
+.IP \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
+.IP \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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_BOOLEAN\fR
+.IP \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
+\fBno\fR.  The internal form is an integer with value 0 or 1.  Note that if
+the \fIobjOffset\fR field is not used, information about the original
+value of this option will be lost.
+.IP \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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_COLOR\fR
+.IP \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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_CURSOR\fR
+.IP \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.
@@ -376,19 +373,16 @@ 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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_CUSTOM\fR
+.IP \fBTK_OPTION_CUSTOM\fR
 This option allows applications to define new option types.  The
 clientData field of the entry points to a structure defining the new
 option type.  See the section \fBCUSTOM OPTION TYPES\fR below for details.
-.TP
-\fBTK_OPTION_DOUBLE\fR
+.IP \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.  This option type supports the \fBTK_OPTION_NULL_OK\fR
 flag; if a NULL value is set, the internal representation is set to zero.
-.TP
-\fBTK_OPTION_END\fR
+.IP \fBTK_OPTION_END\fR
 Marks the end of the template.  There must be a Tk_OptionSpec structure
 with \fItype\fR \fBTK_OPTION_END\fR at the end of each template.  If the
 \fIclientData\fR field of this structure is not NULL, then it points to
@@ -396,48 +390,41 @@ an additional array of Tk_OptionSpec's, which is itself terminated by
 another \fBTK_OPTION_END\fR entry.  Templates may be chained arbitrarily
 deeply.  This feature allows common options to be shared by several
 widget classes.
-.TP
-\fBTK_OPTION_FONT\fR
+.IP \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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_INT\fR
+.IP \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
+specify octal or hexadecimal numbers, respectively).  The internal form is
+a C \fBint\fR value.
+.IP \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
+.IP \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 is not
-used then information about the original value of this option will be lost.
+\fBTk_GetPixelsFromObj\fR.  Note that if the \fIobjOffset\fR field is not
+used, information about the original value of this option will be lost.
 See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details.  This option
 type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the
-internal representation is set to zero.
-.TP
-\fBTK_OPTION_RELIEF\fR
+internal representation is set to INT_MIN.
+.IP \fBTK_OPTION_RELIEF\fR
 The value must be standard relief such as \fBraised\fR.
 The internal form is an integer relief value such as
 \fBTK_RELIEF_RAISED\fR.  This option type supports the \fBTK_OPTION_NULL_OK\fR
 flag; if a NULL value is set, the internal representation is set to
 \fBTK_RELIEF_NULL\fR.
-.TP
-\fBTK_OPTION_STRING\fR
+.IP \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 \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fBTK_OPTION_STRING_TABLE\fR
+.IP \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
@@ -446,15 +433,13 @@ into the table of the matching string, like the return value
 from \fBTcl_GetStringFromObj\fR.  This option type supports the
 \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal
 representation is set to -1.
-.TP
-\fBTK_OPTION_SYNONYM\fR
+.IP \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 string 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
+.IP \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
@@ -504,8 +489,8 @@ the option is retrieved.  In most cases it is convenient to use the
 \fIinternalOffset\fR 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 \fBTK_OPTION_PIXELS\fR options.
+the object whenever it is needed).  Note that the problem of losing
+information on retrievals exists only for \fBTK_OPTION_PIXELS\fR 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.
@@ -513,6 +498,10 @@ To implement a new type of option, you can use \fBTK_OPTION_STRING\fR 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.
+.PP
+Ttk widgets do not support the \fIinternalOffset\fR machinery.
+Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that
+the \fIobjOffset\fR field must be used.
 .SH "CUSTOM OPTION TYPES"
 .PP
 Applications can extend the built-in configuration types with
@@ -521,7 +510,7 @@ free, and restore saved copies of the type and creating a structure
 pointing to those procedures:
 .CS
 typedef struct Tk_ObjCustomOption {
-    const char *\fname\fR;
+    const char *\fIname\fR;
     Tk_CustomOptionSetProc *\fIsetProc\fR;
     Tk_CustomOptionGetProc *\fIgetProc\fR;
     Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
@@ -570,18 +559,14 @@ The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to
 convert a Tcl_Obj into an internal representation and store the
 resulting value in the widget record.  The arguments are:
 .RS
-.TP
-\fIclientData\fR
+.IP \fIclientData\fR
 A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
 structure.
-.TP
-\fIinterp\fR
+.IP \fIinterp\fR
 A pointer to a Tcl interpreter, used for error reporting.
-.TP
-\fITkwin\fR
+.IP \fITkwin\fR
 A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
-.TP
-\fIvaluePtr\fR
+.IP \fIvaluePtr\fR
 A pointer to a reference to a Tcl_Obj describing the new value for the
 option; it could have been specified explicitly in the call to
 \fBTk_SetOptions\fR or it could come from the option database or a
@@ -591,22 +576,18 @@ pointer referenced by \fIvaluePtr\fR is the pointer that will be
 stored at the objOffset for the option.  \fISetProc\fR may modify the
 value if necessary; for example, \fIsetProc\fR may change the value to
 NULL to support the \fBTK_OPTION_NULL_OK\fR flag.
-.TP
-\fIrecordPtr\fR
+.IP \fIrecordPtr\fR
 A pointer to the start of the widget record to modify.
-.TP
-\fIinternalOffset\fR
+.IP \fIinternalOffset\fR
 Offset in bytes from the start of the widget record to the location
 where the internal representation of the option value is to be placed.
-.TP
-\fIsaveInternalPtr\fR
+.IP \fIsaveInternalPtr\fR
 A pointer to storage allocated in a Tk_SavedOptions structure for the
 internal representation of the original option value.  Before setting
 the option to its new value, \fIsetProc\fR should set the value
 referenced by \fIsaveInternalPtr\fR to the original value of the
 option in order to support \fBTk_RestoreSavedOptions\fR.
-.TP
-\fIflags\fR
+.IP \fIflags\fR
 A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the
 option
 .RE