Text widget documentation improvements

1 files changed, 105 insertions, 102 deletions

diff --git a/doc/text.n b/doc/text.n
index f2cc083..e9d6cdd 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -4,9 +4,9 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: text.n,v 1.43 2006/11/15 13:29:17 dkf Exp $
-'\" 
+'\"
+'\" RCS: @(#) $Id: text.n,v 1.44 2007/10/16 15:13:18 dkf Exp $
+'\"
 .so man.macros
 .TH text n 8.5 Tk "Tk Built-In Commands"
 .BS
@@ -36,8 +36,8 @@ inserted in the undo stack. Only meaningful when the \fB\-undo\fR
 option is true.
 .OP \-blockcursor blockCursor BlockCursor
 .VS 8.5
-Specifies a boolean that says whether the blinking insertion cursor 
-should be drawn as a character-sized rectangular block.  If false 
+Specifies a boolean that says whether the blinking insertion cursor
+should be drawn as a character-sized rectangular block.  If false
 (the default) a thin vertical line is used for the insertion cursor.
 .VE 8.5
 .OP \-endline endLine EndLine
@@ -114,21 +114,21 @@ following the tab character is positioned at the tab position, and
 at the tab position;  if there is no decimal point then the least
 significant digit of the number is positioned just to the left of the
 tab position;  if there is no number in the text then the text is
-right-justified at the tab position. 
+right-justified at the tab position.
 For example, \fB\-tabs {2c left 4c 6c center}\fR creates three
 tab stops at two-centimeter intervals;  the first two use left
-justification and the third uses center justification.  
+justification and the third uses center justification.
 If the list of tab stops does not have enough elements to cover all
 of the tabs in a text line, then Tk extrapolates new tab stops using
 the spacing and alignment from the last tab stop in the list.  Tab
-distances must be strictly positive, and must always increase from one 
+distances must be strictly positive, and must always increase from one
 tab stop to the next (if not, an error is thrown).
 The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR
 options in tags.
 If no \fB\-tabs\fR option is specified, or if it is specified as
 an empty list, then Tk uses default tabs spaced every eight
 (average size) characters.  To achieve a different standard spacing,
-for example every 4 characters, simply configure the widget with 
+for example every 4 characters, simply configure the widget with
 \fB\-tabs "[expr {4 * [font measure $font 0]}] left" -tabstyle wordprocessor\fR.
 .OP \-tabstyle tabStyle TabStyle
 Specifies how to interpret the relationship between tab stops on a line
@@ -379,8 +379,8 @@ lines are not wrapped, then these two methods of counting are equivalent.
 .TP
 ?\fIsubmodifier\fR? \fBlinestart\fR
 .VS 8.5
-Adjust the index to refer to the first index on the line.  If the 
-\fBdisplay\fR submodifier is given, this is the first index on the 
+Adjust the index to refer to the first index on the line.  If the
+\fBdisplay\fR submodifier is given, this is the first index on the
 display line, otherwise on the logical line.
 .VE 8.5
 .TP
@@ -415,8 +415,8 @@ refers to the next-to-last character in the text and
 ``\fBinsert wordstart \- 1 c\fR'' refers to the character just before
 the first one in the word containing the insertion cursor.  Modifiers
 are applied one by one in this left to right order, and after each step
-the resulting index is constrained to be a valid index in the text 
-widget.  So, for example, the index ``\fB1.0 -1c +1c\fR'' refers to the 
+the resulting index is constrained to be a valid index in the text
+widget.  So, for example, the index ``\fB1.0 -1c +1c\fR'' refers to the
 index ``\fB2.0\fR''.
 .PP
 Where modifiers result in index changes by display lines, display chars
@@ -452,7 +452,7 @@ widget commands.
 Tags serve three purposes in text widgets.
 First, they control the way information is displayed on the screen.
 By default, characters are displayed as determined by the
-\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the
+\fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the
 text widget.
 However, display options may be associated with individual tags
 using the ``\fIpathName \fBtag configure\fR'' widget command.
@@ -482,7 +482,7 @@ option to give a 3-D appearance to the background for characters;
 it is ignored unless the \fB\-background\fR option
 has been set for the tag.
 .TP
-\fB\-elide \fIboolean\fR 
+\fB\-elide \fIboolean\fR
 \fIElide\fR specifies whether the data should
 be elided.  Elided data (characters, images, embedded windows, etc) is
 not displayed and takes no space on screen, but further on behaves just
@@ -598,11 +598,11 @@ If this option is specified as an empty string, it cancels
 the option, leaving it unspecified for the tag (the default).
 If the option is specified as a non-empty string that is
 an empty list, such as \fB\-tags\0{\0}\fR, then it requests
-default 8-character tabs as described for the \fBtags\fR
+default 8-character tabs as described for the \fB\-tags\fR
 widget option.
 .TP
 \fB\-tabstyle \fIstyle\fR
-\fIStyle\fR specifies either the \fItabular\fR or 
+\fIStyle\fR specifies either the \fItabular\fR or
 \fIwordprocessor\fR style of tabbing to use for the text widget.
 This option only applies to a display line if it applies to the
 first non-elided character on that display line.
@@ -640,7 +640,7 @@ Tcl command will be executed.
 Tag bindings can be used to give behaviors to ranges of characters;
 among other things, this allows hypertext-like
 features to be implemented.
-For details, see the description of the \fBtag bind\fR widget
+For details, see the description of the ``\fIpathName \fBtag bind\fR'' widget
 command below.
 .VS 8.5
 Tag bindings are shared between all peer widgets
@@ -702,7 +702,7 @@ until all mouse buttons have been released).
 Neither of these special marks may be deleted.
 .VS 8.5
 With the exception of
-these two special marks, all marks are shared between peer text 
+these two special marks, all marks are shared between peer text
 widgets, and may be manipulated on an equal basis from any peer.
 .VE 8.5
 .SH "EMBEDDED WINDOWS"
@@ -734,9 +734,9 @@ destroyed.
 .VE 8.5
 .PP
 When an embedded window is added to a text widget with the
-\fBwindow create\fR widget command, several configuration
+\fIpathName \fBwindow create\fR widget command, several configuration
 options may be associated with it.
-These options may be  modified later with the \fBwindow configure\fR
+These options may be  modified later with the \fIpathName \fBwindow configure\fR
 widget command.
 The following options are currently supported:
 .TP
@@ -812,11 +812,11 @@ unit's
 worth of index space
 in the text widget, and it may be referred to either by
 its position in the widget's index space, or the name it is assigned
-when the image is inserted into the text widget with \fBimage create\fR.
+when the image is inserted into the text widget with \fIpathName \fBimage create\fR.
 If the range of text containing the embedded image is deleted then
 that copy of the image is removed from the screen.
 .PP
-When an embedded image is added to a text widget with the \fBimage
+When an embedded image is added to a text widget with the \fIpathName \fBimage
 create\fR widget command, a name unique to this instance of the image
 is returned.  This name may then be used to refer to this image
 instance.  The name is taken to be the value of the \fB\-name\fR option
@@ -825,14 +825,14 @@ instance.  The name is taken to be the value of the \fB\-name\fR option
 in use in the text widget, then \fB#\fInn\fR is added to the end of the
 \fIimageName\fR, where \fInn\fR is an arbitrary integer.  This insures
 the \fIimageName\fR is unique.
-Once this name is assigned to this instance of the image, it does not 
+Once this name is assigned to this instance of the image, it does not
 change, even though the \fB\-image\fR or \fB\-name\fR values can be changed
-with \fBimage configure\fR.
+with \fIpathName \fBimage configure\fR.
 .PP
 When an embedded image is added to a text widget with the
-\fBimage create\fR widget command, several configuration
+\fIpathName \fBimage create\fR widget command, several configuration
 options may be associated with it.
-These options may be modified later with the \fBimage configure\fR
+These options may be modified later with the \fIpathName \fBimage configure\fR
 widget command.
 The following options are currently supported:
 .TP
@@ -883,7 +883,7 @@ If the selection is claimed away by another application or by another
 window within this application, then the \fBsel\fR tag will be removed
 from all characters in the text.
 .IP [4]
-Whenever the \fBsel\fR tag range changes a virtual event 
+Whenever the \fBsel\fR tag range changes a virtual event
 \fB<<Selection>>\fR is generated.
 .PP
 The \fBsel\fR tag is automatically defined when a text widget is
@@ -897,7 +897,7 @@ other.
 .VS 8.5
 Also the
 \fB\-inactiveselectionbackground\fR option for the text widget is used
-instead of \fB-selectbackground\fR when the text widget does not have
+instead of \fB\-selectbackground\fR when the text widget does not have
 the focus.  This allows programmatic control over the visualization of
 the \fBsel\fR tag for foreground and background windows, or to have
 \fBsel\fR not shown at all (when \fB\-inactiveselectionbackground\fR is
@@ -917,8 +917,8 @@ this point whenever the text widget has the input focus.
 The text widget can keep track of changes to the content of the widget
 by means of the modified flag. Inserting or deleting text will set
 this flag. The flag can be queried, set and cleared programmatically
-as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual 
-event is generated. See the \fBedit modified\fR widget command for 
+as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual
+event is generated. See the \fIpathName \fBedit modified\fR widget command for
 more details.
 .SH "THE UNDO MECHANISM"
 .PP
@@ -947,7 +947,7 @@ automatically to the appropriate state.  This automatic coupling
 does not work when the modified flag has been set by the user, until
 the flag has been reset again.
 .PP
-See below for the \fBedit\fR widget command that controls the undo
+See below for the \fIpathName \fBedit\fR widget command that controls the undo
 mechanism.
 .SH "PEER WIDGETS"
 .PP
@@ -970,12 +970,12 @@ the \fBsel\fR tag may be set and configured (in its display style)
 differently for each peer.  Second, each peer has its own \fBinsert\fR
 and \fBcurrent\fR mark positions (but all other marks are shared).
 Third, embedded windows, which are arbitrary other widgets, cannot be
-shared between peers.  This means the \fB-window\fR option of embedded
+shared between peers.  This means the \fB\-window\fR option of embedded
 windows is independently set for each peer (it is advisable to use
-the \fB-create\fR script capabilities to allow each peer to create its
+the \fB\-create\fR script capabilities to allow each peer to create its
 own embedded windows as needed).  Fourth, all of the configuration
-options of each peer (e.g. \fB-font\fR, etc) can be set independently,
-with the exception of \fB-undo\fR, \fB-maxUndo\fR, \fB-autoSeparators\fR
+options of each peer (e.g. \fB\-font\fR, etc) can be set independently,
+with the exception of \fB\-undo\fR, \fB\-maxUndo\fR, \fB\-autoSeparators\fR
 (i.e. all undo, redo and modified state issues are shared).
 .PP
 Finally any single peer need not contain all lines from the underlying
@@ -993,18 +993,18 @@ end lines).  Note that a peer which does not contain all of the
 underlying data store still has indices numbered from "1.0" to "end".
 It is simply that those indices reflect a subset of the total data, and
 data outside the contained range is not accessible to the peer.  This
-means that the command \fB$peer index end\fR may return quite different
-values in different peers.  Similarly, commands like \fB$peer tag
+means that the command \fIpeerName \fBindex end\fR may return quite different
+values in different peers.  Similarly, commands like \fIpeerName \fBtag
 ranges\fR will not return index ranges outside that which is meaningful
-to the peer.  The configuration options \fB-startline\fR and
-\fB-endline\fR may be used to control how much of the underlying data is
+to the peer.  The configuration options \fB\-startline\fR and
+\fB\-endline\fR may be used to control how much of the underlying data is
 contained in any given text widget.
 .PP
 Note that peers are really peers.  Deleting the 'original' text widget
 will not cause any other peers to be deleted, or otherwise affected.
 .PP
-See below for the \fBpeer\fR widget command that controls the creation
-of peer widgets.
+See below for the \fIpathName \fBpeer\fR widget command that controls the
+creation of peer widgets.
 .VE 8.5
 .SH "WIDGET COMMAND"
 .PP
@@ -1065,7 +1065,7 @@ command.
 .TP
 \fIpathName \fBcount\fR \fI?options\fR? \fIindex1 index2\fR
 Counts the number of relevant things between the two indices.
-If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number 
+If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number
 (and this holds for each of the possible options).
 The actual items which are counted depend on the
 options given.  The result is a list of integers, one for the result of
@@ -1080,37 +1080,37 @@ information is recalculated.  This currently only has any effect for the
 widget's current cached value for each line).  The count options are
 interpreted as follows:
 .RS
-.IP \fB\-chars\fR 
+.IP \fB\-chars\fR
 count all characters, whether elided or not.  Do not count
 embedded windows or images.
-.IP \fB\-displaychars\fR 
+.IP \fB\-displaychars\fR
 count all non-elided characters.
-.IP \fB\-displayindices\fR 
+.IP \fB\-displayindices\fR
 count all non-elided characters, windows and images.
-.IP \fB\-displaylines\fR 
+.IP \fB\-displaylines\fR
 count all display lines (i.e. counting one for each
 time a line wraps) from the line of the first index up to, but not
 including the display line of the second index.  Therefore if they are
 both on the same display line, zero will be returned.  By definition
 displaylines are visible and therefore this only counts portions of
 actual visible lines.
-.IP \fB\-indices\fR 
+.IP \fB\-indices\fR
 count all characters and embedded windows or images (i.e.
 everything which counts in text-widget index space), whether they are
 elided or not.
-.IP \fB\-lines\fR 
+.IP \fB\-lines\fR
 count all logical lines (irrespective of wrapping) from
 the line of the first index up to, but not including the line of the
 second index.  Therefore if they are both on the same line, zero will be
 returned.  Logical lines are counted whether they are currently visible
 (non-elided) or not.
-.IP \fB\-xpixels\fR 
+.IP \fB\-xpixels\fR
 count the number of horizontal pixels from the first
 pixel of the first index to (but not including) the first pixel of the
 second index.  To count the total desired width of the text widget
 (assuming wrapping is not enabled), first find the longest line and then
 use '.text count \-xpixels "${line}.0" "${line}.0 lineend"'.
-.IP \fB\-ypixels\fR 
+.IP \fB\-ypixels\fR
 count the number of vertical pixels from the first pixel
 of the first index to (but not including) the first pixel of the second
 index.  If both indices are on the same display line, zero will be
@@ -1118,9 +1118,9 @@ returned.  To count the total number of vertical pixels in the text
 widget, use '.text count \-ypixels 1.0 end', and to ensure this is up to
 date, use '.text count \-update \-ypixels 1.0 end'.
 .PP
-The command returns a positive or negative integer corresponding to the 
+The command returns a positive or negative integer corresponding to the
 number of items counted between the two indices.  One such integer is
-returned for each counting option given, so a list is returned if more 
+returned for each counting option given, so a list is returned if more
 than one option was supplied.  For example '.text count \-xpixels
 \-ypixels 1.3 4.5' is perfectly valid and will return a list of two
 elements.
@@ -1141,11 +1141,13 @@ There is a single debugging switch shared by all text widgets:  turning
 debugging on or off in any widget turns it on or off for all widgets.
 For widgets with large amounts of text, the consistency checks may
 cause a noticeable slow-down.
+.RS
 .PP
 When debugging is turned on, the drawing routines of the text widget
 set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR
 to the lists of indices that are redrawn.  The values of these variables
 are tested by Tk's test suite.
+.RE
 .TP
 \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR?
 Delete a range of characters from the text.
@@ -1294,10 +1296,10 @@ If the specified range contains embedded windows, no information
 about them is included in the returned string.
 If multiple index pairs are given, multiple ranges of text will be returned
 in a list.  Invalid ranges will not be represented with empty strings in
-the list.  The ranges are returned in the order passed to \fBget\fR.
+the list.  The ranges are returned in the order passed to \fIpathName \fBget\fR.
 .VS 8.5
 If the \fB\-displaychars\fR option is given, then, within each range,
-only those characters which are not elided will be returned.  This may 
+only those characters which are not elided will be returned.  This may
 have the effect that some of the returned ranges are empty strings.
 .VE 8.5
 .TP
@@ -1366,7 +1368,7 @@ tag names;  the new characters will receive all of the tags in
 this list and no others, regardless of the tags present around
 the insertion point.
 If multiple \fIchars\fR\-\fItagList\fR argument pairs are present,
-they produce the same effect as if a separate \fBinsert\fR widget
+they produce the same effect as if a separate \fIpathName \fBinsert\fR widget
 command had been issued for each pair, in order.
 The last \fItagList\fR argument may be omitted.
 .TP
@@ -1398,9 +1400,9 @@ This can still return a mark at the same position if
 there are multiple marks at the same index.
 These semantics mean that the \fBmark next\fR operation can be used to
 step through all the marks in a text widget in the same order
-as the mark information returned by the \fBdump\fR operation.
+as the mark information returned by the \fIpathName \fBdump\fR operation.
 If a mark has been set to the special \fBend\fR index,
-then it appears to be \fIafter\fR \fBend\fR with respect to the \fBmark next\fR operation.
+then it appears to be \fIafter\fR \fBend\fR with respect to the \fIpathName \fBmark next\fR operation.
 An empty string is returned if there are no marks after \fIindex\fR.
 .TP
 \fIpathName \fBmark previous \fIindex\fR
@@ -1411,9 +1413,9 @@ If \fIindex\fR is the name of a mark, then the search for
 the next mark begins immediately before that mark.
 This can still return a mark at the same position if
 there are multiple marks at the same index.
-These semantics mean that the \fBmark previous\fR operation can be used to
+These semantics mean that the \fIpathName \fBmark previous\fR operation can be used to
 step through all the marks in a text widget in the reverse order
-as the mark information returned by the \fBdump\fR operation.
+as the mark information returned by the \fIpathName \fBdump\fR operation.
 An empty string is returned if there are no marks before \fIindex\fR.
 .TP
 \fIpathName \fBmark set \fImarkName index\fR
@@ -1449,7 +1451,7 @@ itself).  The order within this list is undefined.
 .RE
 .TP
 \fIpathName \fBreplace\fR \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR?
-Replaces the range of characters between \fIindex1\fR and \fIindex2\fR 
+Replaces the range of characters between \fIindex1\fR and \fIindex2\fR
 with the given characters and tags.  See the section on \fIpathName
 \fBinsert\fR for an explanation of the handling of the \fItagList...\fR
 arguments, and the section on \fIpathName
@@ -1470,14 +1472,14 @@ two forms, depending on \fIoption\fR:
 .TP
 \fIpathName \fBscan mark \fIx y\fR
 Records \fIx\fR and \fIy\fR and the current view in the text window,
-for use in conjunction with later \fBscan dragto\fR commands.
+for use in conjunction with later \fIpathName \fBscan dragto\fR commands.
 Typically this command is associated with a mouse button press in
 the widget.  It returns an empty string.
 .TP
 \fIpathName \fBscan dragto \fIx y\fR
 This command computes the difference between its \fIx\fR and \fIy\fR
 arguments and the \fIx\fR and \fIy\fR arguments to the last
-\fBscan mark\fR command for the widget.
+\fIpathName \fBscan mark\fR command for the widget.
 It then adjusts the view by 10 times the difference in coordinates.
 This command is typically associated
 with mouse motion events in the widget, to produce the effect of
@@ -1521,17 +1523,17 @@ the text using the rules for regular expressions (see the \fBregexp\fR
 command for details).
 .VS 8.5
 The default matching automatically passes
-both the \fB\-lineanchor\fR and \fB\-linestop\fR options 
+both the \fB\-lineanchor\fR and \fB\-linestop\fR options
 to the regexp engine (unless \fB\-nolinestop\fR is used), so that
-\fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR 
+\fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR
 sequences will never match the newline character \fI\en\fR.
 .VE 8.5
 .TP
 \fB\-nolinestop\fR
 .VS 8.5
-This allows \fI.\fR and \fI[^\fR sequences to match the newline 
+This allows \fI.\fR and \fI[^\fR sequences to match the newline
 character \fI\en\fR, which they will otherwise not do (see the \fBregexp\fR
-command for details). This option is only meaningful if \fB\-regexp\fR 
+command for details). This option is only meaningful if \fB\-regexp\fR
 is also given, and an error will be thrown otherwise.  For example,
 to match the entire text, use 'search \-nolinestop \-regexp ".*" 1.0'.
 .VE 8.5
@@ -1551,20 +1553,20 @@ number of characters matched.  In either case, the range \fImatchIdx\fR to
 \fB\-all\fR
 .VS 8.5
 Find all matches in the given range and return a list of the indices of
-the first character of each match.  If a \fB\-count\fI varName\fR switch is 
-given, then \fBvarName\fR is also set to a list containing one element 
+the first character of each match.  If a \fB\-count\fI varName\fR switch is
+given, then \fIvarName\fR is also set to a list containing one element
 for each successful match.  Note that, even for exact searches, the
 elements of this list may be different, if there are embedded images,
 windows or hidden text.  Searches with \fB\-all\fR behave very
 similarly to the Tcl command \fBregexp \-all\fR, in that overlapping
 matches are not normally returned.  For example, applying an
-\fB\-all\fR search 
+\fB\-all\fR search
 of the pattern '\\w+' against 'hello there' will just match twice, once
 for each word, and matching 'Z[a\-z]+Z' against 'ZooZooZoo' will just
 match once.
 .VE 8.5
 .TP
-\fB\-overlap\fR 
+\fB\-overlap\fR
 .VS 8.5
 When performing \fB\-all\fR searches, the normal behaviour is that
 matches which overlap an already-found match will not be returned.  This
@@ -1572,11 +1574,11 @@ switch changes that behaviour so that all matches which are not totally
 enclosed within another match are returned.  For example, applying an
 \fB\-overlap\fR search of the pattern '\\w+' against 'hello there' will
 just match twice (i.e. no different to just \fB\-all\fR),
-but matching 'Z[a\-z]+Z' against 'ZooZooZoo' will now match twice.  
+but matching 'Z[a\-z]+Z' against 'ZooZooZoo' will now match twice.
 An error will be thrown if this switch is used without \fB\-all\fR.
 .VE 8.5
 .TP
-\fB\-strictlimits\fR 
+\fB\-strictlimits\fR
 .VS 8.5
 When performing any search, the normal behaviour is that
 the start and stop limits are checked with respect to the
@@ -1593,7 +1595,7 @@ searched.
 This switch has no effect except to terminate the list of switches:
 the next argument will be treated as \fIpattern\fR even if it starts
 with \fB\-\fR.
-.LP
+.PP
 .VS 8.5
 The matching range may be within a single line of text, or run across
 multiple lines (if parts of the pattern can match a new-line).  For
@@ -1609,10 +1611,10 @@ If \fIstopIndex\fR is omitted, the entire text will be searched:
 when the beginning or end of the text is reached, the search
 continues at the other end until the starting location is reached
 again;  if \fIstopIndex\fR is specified, no wrap-around will occur.
-This means that, for example, if the search is \fB\-forwards\fR 
-but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, 
+This means that, for example, if the search is \fB\-forwards\fR
+but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR,
 nothing will ever be found.  See \fBKNOWN BUGS\fR below for a number of
-minor limitations of the \fBsearch\fR command.
+minor limitations of the \fIpathName \fBsearch\fR command.
 .RE
 .TP
 \fIpathName \fBsee \fIindex\fR
@@ -1669,7 +1671,7 @@ defined for \fItagName\fR.
 .RS
 .PP
 The only events for which bindings may be specified are those related
-to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, 
+to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR,
 \fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events.
 Event bindings for a text widget use the \fBcurrent\fR mark described
 under \fBMARKS\fR above.  An \fBEnter\fR event triggers for a tag when the tag
@@ -1705,11 +1707,11 @@ for the window as a whole.
 \fIpathName \fBtag cget\fR \fItagName option\fR
 This command returns the current value of the option named \fIoption\fR
 associated with the tag given by \fItagName\fR.
-\fIOption\fR may have any of the values accepted by the \fBtag configure\fR
-widget command.
+\fIOption\fR may have any of the values accepted by the \fIpathName \fBtag
+configure\fR widget command.
 .TP
 \fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
-This command is similar to the \fBconfigure\fR widget command except
+This command is similar to the \fIpathName \fBconfigure\fR widget command except
 that it modifies options associated with the tag given by \fItagName\fR
 instead of modifying options for the overall text widget.
 If no \fIoption\fR is specified, the command returns a list describing
@@ -1927,7 +1929,7 @@ appears at the top of the top line of the window.
 pixel of the first character in the text, 0.33 indicates the pixel that is
 one-third the way through the text; and so on.
 .VS 8.5
-Values close to 1 will 
+Values close to 1 will
 indicate values close to the last pixel in the text (1 actually refers
 to one pixel beyond the last pixel), but in such cases the widget will
 never scroll beyond the last pixel, and so a value of 1 will effectively
@@ -1972,9 +1974,9 @@ it will be positioned at the bottom of the window.
 .IP [4]
 Otherwise, \fIindex\fR will be centered in the window.
 .LP
-The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget
-command (\fBsee\fR handles both x- and y-motion to make a location
-visible, whereas \fB\-pickplace\fR only handles motion in y).
+The \fB\-pickplace\fR option has been obsoleted by the \fIpathName \fBsee\fR widget
+command (\fIpathName \fBsee\fR handles both x- and y-motion to make a location
+visible, whereas the \fB\-pickplace\fR mode only handles motion in y).
 .RE
 .TP
 \fIpathName \fByview \fInumber\fR
@@ -2067,7 +2069,7 @@ and also extends the selection to that point.
 .IP [14]
 End and Control-e move the insertion cursor to the
 end of the display line and clear any selection in the widget.
-Shift-End moves the cursor to the end of the display line and extends 
+Shift-End moves the cursor to the end of the display line and extends
 the selection to that point.
 .IP [15]
 Control-Home and Meta-< move the insertion cursor to the beginning of
@@ -2132,7 +2134,7 @@ Control-x deletes whatever is selected in the text widget
 after copying it to the clipboard.
 .IP [31]
 Control-t reverses the order of the two characters to the right of
-the insertion cursor. 
+the insertion cursor.
 .IP [32]
 Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is
 true) undoes the last edit action if the \fB\-undo\fR option is true.
@@ -2148,7 +2150,8 @@ take place.
 .PP
 The behavior of texts can be changed by defining new bindings for
 individual widgets or by redefining the class bindings.
-.SH "ISSUES CONCERNING CHARS AND INDICES"
+.SH "KNOWN ISSUES"
+.SS "ISSUES CONCERNING CHARS AND INDICES"
 .VS 8.5
 .PP
 Before Tk 8.5, the widget used the string "chars" to refer to index
@@ -2159,9 +2162,9 @@ index modifiers "+N chars" and "\-N chars" continue to refer to indices.
 One must use any of the full forms "+N any chars" or "\-N any chars" etc
 to refer to actual character indices.  This confusion may be fixed in a
 future release by making the widget correctly interpret "+N chars" as a
-synonym for "+N any chars".  
+synonym for "+N any chars".
 .VE 8.5
-.SH "PERFORMANCE ISSUES"
+.SS "PERFORMANCE ISSUES"
 .PP
 Text widgets should run efficiently under a variety
 of conditions.  The text widget uses about 2-3 bytes of
@@ -2194,10 +2197,10 @@ especially if they have many marks and tags within them.
 The display line with the insert cursor is redrawn each time the
 cursor blinks, which causes a steady stream of graphics traffic.
 Set the \fBinsertOffTime\fR attribute to 0 avoid this.
-.SH "KNOWN BUGS"
+.SS "KNOWN BUGS"
 .VS 8.5
 .PP
-The \fBsearch \-regexp\fR sub-command attempts to perform sophisticated
+The \fIpathName \fBsearch \-regexp\fR sub-command attempts to perform sophisticated
 regexp matching across multiple lines in an efficient fashion (since Tk
 8.5), examining each line individually, and then in small groups of lines,
 whether searching forwards or backwards.  Under certain conditions the
@@ -2214,9 +2217,9 @@ returns the incorrect code and adding a second extra line would actually
 match, the text widget will return the wrong result.  In practice this is
 a rare problem, but it can occur, for example:
 .CS
- pack [text .t]
- .t insert 1.0 "aaaa\\nbbbb\\ncccc\\nbbbb\\naaaa\\n" 
- .t search \-regexp \-\- {(a+|b+\\nc+\\nb+)+\\na+} 1.0
+pack [text .t]
+\.t insert 1.0 "aaaa\\nbbbb\\ncccc\\nbbbb\\naaaa\\n"
+\.t search \-regexp \-\- {(a+|b+\\nc+\\nb+)+\\na+} 1.0
 .CE
 will not find a match when one exists of 19
 characters starting from the first 'b'.
@@ -2224,20 +2227,20 @@ characters starting from the first 'b'.
 Whenever one possible match is fully enclosed in another, the search
 command will attempt to ensure only the larger match is returned.
 When performing backwards regexp searches it is possible that Tcl
-will not always achieve this, in the case where a match is preceded by 
+will not always achieve this, in the case where a match is preceded by
 one or more short, non-overlapping matches, all of which are preceded
 by a large match which actually encompasses all of them.  The search
 algorithm used by the widget does not look back arbitrarily far for a
 possible match which might cover large portions of the widget.
 For example:
 .CS
- pack [text .t] 
- .t insert 1.0 "aaaa\\nbbbb\\nbbbb\\nbbbb\\nbbbb\\n"
- .t search \-regexp \-backward \-\- {b+\\n|a+\\n(b+\\n)+} end 
+pack [text .t]
+\.t insert 1.0 "aaaa\\nbbbb\\nbbbb\\nbbbb\\nbbbb\\n"
+\.t search \-regexp \-backward \-\- {b+\\n|a+\\n(b+\\n)+} end
 .CE
-matches at '5.0' when a true greedy match would match at '1.0'.  
-Similarly if we add \fB\-all\fR to this case, it matches at 
-all of '5.0', '4.0', '3.0' and '1.0', 
+matches at '5.0' when a true greedy match would match at '1.0'.
+Similarly if we add \fB\-all\fR to this case, it matches at
+all of '5.0', '4.0', '3.0' and '1.0',
 when really it should only match at '1.0' since that match
 encloses all the others.
 .VE 8.5