Backport of documentation fixes

1 files changed, 35 insertions, 42 deletions

diff --git a/doc/canvas.n b/doc/canvas.n
index c8ead38..3371596 100644
--- a/doc/canvas.n
+++ b/doc/canvas.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: canvas.n,v 1.13 2002/08/08 04:54:01 hobbs Exp $
+'\" RCS: @(#) $Id: canvas.n,v 1.13.2.1 2004/10/28 10:19:29 dkf Exp $
 '\"
 .so man.macros
 .TH canvas n 8.3 Tk "Tk Built-In Commands"
@@ -39,14 +39,14 @@ be constrained within the scroll region.
 .OP \-height height Height
 Specifies a desired window height that the canvas widget should request from
 its geometry manager.  The value may be specified in any
-of the forms described in the COORDINATES section below.
+of the forms described in the \fBCOORDINATES\fR section below.
 .OP \-scrollregion scrollRegion ScrollRegion
 Specifies a list with four coordinates describing the left, top, right, and
 bottom coordinates of a rectangular region.
 This region is used for scrolling purposes and is considered to be
 the boundary of the information in the canvas.
 Each of the coordinates may be specified
-in any of the forms given in the COORDINATES section below.
+in any of the forms given in the \fBCOORDINATES\fR section below.
 .OP \-state state State
 Modifies the default state of the canvas where \fIstate\fR may be set to
 one of: \fBnormal\fR, \fBdisabled\fR, or \fBhidden\fR. Individual canvas
@@ -60,7 +60,7 @@ the appearence when the state is disabled.  Canvas items which are
 .OP \-width width width
 Specifies a desired window width that the canvas widget should request from
 its geometry manager.  The value may be specified in any
-of the forms described in the COORDINATES section below.
+of the forms described in the \fBCOORDINATES\fR section below.
 .OP \-xscrollincrement xScrollIncrement ScrollIncrement
 Specifies an increment for horizontal scrolling, in any of the usual forms
 permitted for screen distances.  If the value of this option is greater
@@ -106,7 +106,6 @@ so that the command is invoked whenever button 1 is pressed with
 the mouse cursor over an item.
 This means that items in a canvas can have behaviors defined by
 the Tcl scripts bound to them.
-
 .SH "DISPLAY LIST"
 .PP
 The items in a canvas are ordered for purposes of display,
@@ -125,12 +124,11 @@ window systems require them always to be drawn on top of other items.
 In addition, the stacking order of window items
 is not affected by any of the canvas widget commands; you must use
 the \fBraise\fR and \fBlower\fR Tk commands instead.
-
 .SH "ITEM IDS AND TAGS"
 .PP
 Items in a canvas widget may be named in either of two ways:
 by id or by tag.
-Each item has a unique identifying number which is assigned to
+Each item has a unique identifying number, which is assigned to
 that item when it is created.  The id of an item never changes
 and id numbers are never re-used within the lifetime of a
 canvas widget.
@@ -166,7 +164,7 @@ an argument specifies either an id that selects a single
 item or a tag that selects zero or more items.
 .PP
 \fItagOrId\fR may contain a logical expressions of
-tags by using operators: '&&', '||', '^' '!', and parenthezised
+tags by using operators: '&&', '||', '^' '!', and parenthesized
 subexpressions.  For example:
 .CS
       .c find withtag {(a&&!b)||(!a&&b)}
@@ -184,7 +182,6 @@ the command to use the first (lowest) of these items in
 the display list that is suitable for the command.
 Exceptions are noted in the widget command descriptions
 below.
-
 .SH "COORDINATES"
 .PP
 All coordinates related to canvases are stored as floating-point
@@ -203,7 +200,6 @@ Coordinates can be specified either as an even number of parameters,
 or as a single list parameter containing an even number of x and y
 coordinate values.
 .VE
-
 .SH TRANSFORMATIONS
 .PP
 Normally the origin of the canvas coordinate system is at the
@@ -217,7 +213,16 @@ system relative to the window coordinate system.
 .PP
 Individual items may be moved or scaled using widget commands
 described below, but they may not be rotated.
-
+.PP
+Note that the default origin of the canvas's visible area is
+coincident with the origin for the whole window as that makes bindings
+using the mouse position easier to work with; you only need to use the
+\fBcanvasx\fR and \fBcanvasy\fR widget commands if you adjust the
+origin of the visible area.  However, this also means that any focus
+ring (as controlled by the \fB\-highlightthickness\fR option) and
+window border (as controlled by the \fB\-borderwidth\fR option) must
+be taken into account before you get to the visible area of the
+canvas.
 .SH "INDICES"
 .PP
 Text items support the notion of an \fIindex\fR for identifying
@@ -236,7 +241,7 @@ Note that it is possible to refer to the character just after
 the last one in the text item;  this is necessary for such
 tasks as inserting new text at the end of the item.
 Lines and Polygons don't support the insertion cursor
-and the selection. Their indixes are supposed to be even
+and the selection. Their indices are supposed to be even
 always, because coordinates always appear in pairs.
 .TP 10
 \fInumber\fR
@@ -249,7 +254,7 @@ A number less than 0 is treated as if it were zero, and a
 number greater than the length of the text item is treated
 as if it were equal to the length of the text item. For
 polygons, numbers less than 0 or greater then the length
-of the coordinate list will be adjusted by adding or substracting
+of the coordinate list will be adjusted by adding or subtracting
 the length until the result is between zero and the length,
 inclusive.
 .TP 10
@@ -277,15 +282,14 @@ system of the canvas.
 If \fIx\fR and \fIy\fR lie outside the coordinates covered by the
 text item, then they refer to the first or last character in the
 line that is closest to the given point.
-
 .SH "DASH PATTERNS"
 .PP
-Many items support the notion of an dash pattern for outlines.
+Many items support the notion of a dash pattern for outlines.
 .PP
 The first possible syntax is a list of integers. Each element
 represents the number of pixels of a line segment. Only the odd
 segments are drawn using the "outline" color. The other segments
-are drawn transparant.
+are drawn transparent.
 .PP
 The second possible syntax is a character list containing only
 5 possible characters \fB[.,-_ ]\fR. The space can be used
@@ -299,7 +303,7 @@ occur as the first position in the string. Some examples:
     -dash ,	= -dash {4 4}
 .PP
 The main difference of this syntax with the previous is that it
-it shape-conserving. This means that all values in the dash
+is shape-conserving. This means that all values in the dash
 list will be multiplied by the line width before display. This
 assures that "." will always be displayed as a dot and "-"
 always as a dash regardless of the line width.
@@ -309,7 +313,6 @@ pattern will be displayed as the closest dash pattern that is available.
 For example, on Windows only the first 4 of the above examples are
 available.  The last 2 examples will be displayed identically to the first
 one.
-
 .SH "WIDGET COMMAND"
 .PP
 The \fBcanvas\fR command creates a new Tcl command whose
@@ -613,7 +616,7 @@ operations (in display list order).
 For each of the items given by \fItagOrId\fR, if the item supports
 text or coordinate, insertion then \fIstring\fR is inserted into the item's
 text just before the character, or coordinate, whose index is \fIbeforeThis\fR.
-Text items interpret \fIbeforethis\fR as an index to a  character,
+Text items interpret \fIbeforeThis\fR as an index to a  character,
 line and polygon items interpret it as an index to a coordinate (an x,y pair).
 For lines and polygons the \fIstring\fR must be a valid coordinate
 sequence.
@@ -1006,7 +1009,6 @@ If \fInumber\fR is negative then higher information becomes
 visible;  if it is positive then lower information
 becomes visible.
 .RE
-
 .SH "OVERVIEW OF ITEM TYPES"
 .PP
 The sections below describe the various types of items supported
@@ -1022,7 +1024,6 @@ in the descriptions below.
 At present, text, line and polygon items provide this support.
 For lines and polygons the indexing facility is used to manipulate
 the coordinates of the item.
-
 .SH "COMMON ITEM OPTIONS"
 .PP
 Many items share a common set of options.  These options are
@@ -1044,7 +1045,7 @@ See "DASH PATTERNS" for more information.
 The starting \fIoffset\fR in pixels into the pattern provided by the
 \fB\-dash\fR option.  \fB\-dashoffset\fR is ignored if there is no
 \fB-dash\fR pattern.  The \fIoffset\fR may have any of the forms described
-in the COORDINATES section above.
+in the \fBCOORDINATES\fR section above.
 .TP
 \fB\-fill \fIcolor\fR
 .TP
@@ -1054,7 +1055,7 @@ in the COORDINATES section above.
 Specifies the color to be used to fill item's area.
 in its normal, active, and disabled states,
 \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
-If \fIcolor\fR is an empty string (the default), then
+If \fIcolor\fR is an empty string (the default),
 then the item will not be filled.
 For the line item, it specifies the color of the line drawn.
 For the text item, it specifies the foreground color of the text.
@@ -1102,7 +1103,7 @@ in a solid fashion.
 \fB\-activestipple \fIbitmap\fR
 .TP
 \fB\-disabledstipple \fIbitmap\fR
-This option specifies stipple patterns that should be used to fill the
+This option specifies stipple patterns that should be used to fill
 the item in its normal, active and disabled states.
 \fIbitmap\fR specifies the stipple pattern to use, in any of the
 forms accepted by \fBTk_GetBitmap\fR.
@@ -1129,13 +1130,12 @@ existing tags for the item.  \fITagList\fR may be an empty list.
 \fB\-disabledwidth \fIoutlineWidth\fR
 Specifies the width of the outline to be drawn around
 the item's region, in its normal, active and disabled states.
-\fIoutlineWidth\fR may be in any of the forms described in the COORDINATES
-section above.
+\fIoutlineWidth\fR may be in any of the forms described in the
+\fBCOORDINATES\fR section above.
 If the \fB\-outline\fR option has been specified as an empty string then
 this option has no effect.  This option defaults to 1.0.
 For arcs, wide outlines will be drawn centered on the edges of the
 arc's region.
-
 .SH "ARC ITEMS"
 .PP
 Items of type \fBarc\fR appear on the display as arc-shaped regions.
@@ -1208,7 +1208,6 @@ connecting the two end points of the perimeter section.
 If \fItype\fR is \fBarc\fR then the arc's region consists of
 a section of the perimeter alone.
 In this last case the \fB\-fill\fR option is ignored.
-
 .SH "BITMAP ITEMS"
 .PP
 Items of type \fBbitmap\fR appear on the display as images with
@@ -1273,7 +1272,6 @@ Specifies the color to use for each of the bitmap's '1' valued pixels
 in its normal, active and disabled states.
 \fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR and
 defaults to \fBblack\fR.
-
 .SH "IMAGE ITEMS"
 .PP
 Items of type \fBimage\fR are used to display images on a
@@ -1317,7 +1315,6 @@ Specifies the name of the images to display in the item in is normal,
 active and disabled states.
 This image must have been created previously with the
 \fBimage create\fR command.
-
 .SH "LINE ITEMS"
 .PP
 Items of type \fBline\fR appear on the display as one or more connected
@@ -1371,7 +1368,7 @@ This option defaults to \fBnone\fR.
 This option indicates how to draw arrowheads.
 The \fIshape\fR argument must be a list with three elements, each
 specifying a distance in any of the forms described in
-the COORDINATES section above.
+the \fBCOORDINATES\fR section above.
 The first element of the list gives the distance along the line
 from the neck of the arrowhead to its tip.
 The second element gives the distance along the line from the
@@ -1462,7 +1459,6 @@ The following standard options are supported by ovals:
 \-activewidth
 \-disabledwidth
 .CE
-
 .SH "POLYGON ITEMS"
 .PP
 Items of type \fBpolygon\fR appear as polygonal or curved filled regions
@@ -1520,7 +1516,7 @@ of the outline.
 If this option isn't specified then it defaults to \fBmiter\fR.
 .TP
 \fB\-smooth \fIboolean\fR
-\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR
+\fIBoolean\fR must have one of the forms accepted by \fBTk_GetBoolean\fR.
 It indicates whether or not the polygon should be drawn with a
 curved perimeter.
 If so, the outline of the polygon becomes a set of parabolic splines,
@@ -1542,7 +1538,6 @@ interior point is considered to be inside the item only if the item
 is filled or if it has neither a fill nor an outline.  If you would
 like an unfilled polygon whose interior points are not considered
 to be inside the polygon, use a line item instead.
-
 .SH "RECTANGLE ITEMS"
 .PP
 Items of type \fBrectangle\fR appear as rectangular regions on
@@ -1588,7 +1583,6 @@ The following standard options are supported by rectangles:
 \-activewidth
 \-disabledwidth
 .CE
-
 .SH "TEXT ITEMS"
 .PP
 A text item displays a string of characters on the screen in one
@@ -1658,7 +1652,7 @@ This option defaults to an empty string.
 .TP
 \fB\-width \fIlineLength\fR
 Specifies a maximum line length for the text, in any of the forms
-described in the COORDINATES section above.
+described in the \fBCOORDINATES\fR section above.
 If this option is zero (the default) the text is broken into
 lines only at newline characters.
 However, if this option is non-zero then any line that would
@@ -1666,7 +1660,6 @@ be longer than \fIlineLength\fR is broken just before a space
 character to make the line shorter than \fIlineLength\fR;  the
 space character is treated as if it were a newline
 character.
-
 .SH "WINDOW ITEMS"
 .PP
 Items of type \fBwindow\fR cause a particular window to be displayed
@@ -1704,14 +1697,14 @@ This option defaults to \fBcenter\fR.
 \fB\-height \fIpixels\fR
 Specifies the height to assign to the item's window.
 \fIPixels\fR may have any of the
-forms described in the COORDINATES section above.
+forms described in the \fBCOORDINATES\fR section above.
 If this option isn't specified, or if it is specified as an empty
 string, then the window is given whatever height it requests internally.
 .TP
 \fB\-width \fIpixels\fR
 Specifies the width to assign to the item's window.
 \fIPixels\fR may have any of the
-forms described in the COORDINATES section above.
+forms described in the \fBCOORDINATES\fR section above.
 If this option isn't specified, or if it is specified as an empty
 string, then the window is given whatever width it requests internally.
 .TP
@@ -1725,19 +1718,16 @@ Note:  due to restrictions in the ways that windows are managed, it is not
 possible to draw other graphical items (such as lines and images) on top
 of window items.  A window item always obscures any graphics that
 overlap it, regardless of their order in the display list.
-
 .SH "APPLICATION-DEFINED ITEM TYPES"
 .PP
 It is possible for individual applications to define new item
 types for canvas widgets using C code.
 See the documentation for \fBTk_CreateItemType\fR.
-
 .SH BINDINGS
 .PP
 In the current implementation, new canvases are not given any
 default behavior:  you'll have to execute explicit Tcl commands
 to give the canvas its behavior.
-
 .SH CREDITS
 .PP
 Tk's canvas widget is a blatant ripoff of ideas from Joel Bartlett's
@@ -1746,5 +1736,8 @@ environment and preceded canvases by a year or two.  Its simple
 mechanisms for placing and animating graphical objects inspired the
 functions of canvases.
 
+.SH "SEE ALSO"
+bind(n), font(n), image(n), scrollbar(n)
+
 .SH KEYWORDS
 canvas, widget