From 462bdd414eaf42d777fc25c16423c42ebfb7ff97 Mon Sep 17 00:00:00 2001 From: "jan.nijtmans" Date: Sun, 1 Sep 2024 20:35:00 +0000 Subject: [PATCH] Backport documentation improvements from 8.7/9.0 --- doc/3DBorder.3 | 49 ++++++++++++++++++++++--------------------------- doc/GetColor.3 | 21 ++++++++++++--------- doc/GetCursor.3 | 23 ++++++++++++++--------- doc/GetRelief.3 | 11 +++++------ 4 files changed, 53 insertions(+), 51 deletions(-) diff --git a/doc/3DBorder.3 b/doc/3DBorder.3 index de036456c5..122a8ea2ea 100644 --- a/doc/3DBorder.3 +++ b/doc/3DBorder.3 @@ -13,49 +13,43 @@ Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectang .SH SYNOPSIS .nf \fB#include \fR -.sp + Tk_3DBorder -\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR +\fBTk_Alloc3DBorderFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_3DBorder -\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR +\fBTk_Get3DBorder\fR(\fIinterp, tkwin, colorName\fR) .sp Tk_3DBorder -\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_Get3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp -void -\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +\fBTk_Draw3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp -void -\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR +\fBTk_Fill3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp -void -\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +\fBTk_Draw3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp -void -\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR +\fBTk_Fill3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp -void -\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR +\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fR) .sp -void -\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR +\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fR) .sp -void -\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR +\fBTk_SetBackgroundFromBorder\fR(\fItkwin, border\fR) .sp const char * -\fBTk_NameOf3DBorder(\fIborder\fB)\fR +\fBTk_NameOf3DBorder\fR(\fIborder\fR) .sp XColor * -\fBTk_3DBorderColor(\fIborder\fB)\fR +\fBTk_3DBorderColor\fR(\fIborder\fR) .sp GC * -\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR +\fBTk_3DBorderGC\fR(\fItkwin, border, which\fR) .sp -\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_Free3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp -\fBTk_Free3DBorder(\fIborder\fB)\fR +\fBTk_Free3DBorder\fR(\fIborder\fR) +.fi .SH ARGUMENTS .AS "Tk_3DBorder" borderWidth .AP Tcl_Interp *interp in @@ -67,7 +61,7 @@ must be the window for which the border was allocated). Pointer to value 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 const char *colorName in +.AP "const char" *colorName in Same as \fIobjPtr\fR except value is supplied as a string rather than a value. .AP Drawable drawable in @@ -192,8 +186,8 @@ which of several three-dimensional effects is desired: \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. -\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be -a groove or ridge around the exterior of the rectangle. +\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should +appear to be a groove or ridge around the exterior of the rectangle. .PP \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except that it first fills the rectangular area with the background color @@ -291,4 +285,5 @@ 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. .SH KEYWORDS -3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect +3D, background, border, color, depressed, illumination, value, polygon, +raised, shadow, three-dimensional effect diff --git a/doc/GetColor.3 b/doc/GetColor.3 index 0905d4e429..4dce903767 100644 --- a/doc/GetColor.3 +++ b/doc/GetColor.3 @@ -15,26 +15,27 @@ Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_Na \fB#include \fR .sp XColor * -\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR +\fBTk_AllocColorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp XColor * -\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR +\fBTk_GetColor\fR(\fIinterp, tkwin, name\fR) .sp XColor * -\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_GetColorFromObj\fR(\fItkwin, objPtr\fR) .sp XColor * -\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR +\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fR) .sp const char * -\fBTk_NameOfColor(\fIcolorPtr\fB)\fR +\fBTk_NameOfColor\fR(\fIcolorPtr\fR) .sp GC -\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR +\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR) .sp -\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_FreeColorFromObj\fR(\fItkwin, objPtr\fR) .sp -\fBTk_FreeColor(\fIcolorPtr\fB)\fR +\fBTk_FreeColor\fR(\fIcolorPtr\fR) +.fi .SH ARGUMENTS .AS "Tcl_Interp" *colorPtr .AP Tcl_Interp *interp in @@ -44,7 +45,7 @@ Token for window in which color will be used. .AP Tcl_Obj *objPtr in/out String value describes desired color; internal rep will be modified to cache pointer to corresponding (XColor *). -.AP const char *name in +.AP "const char" *name in Same as \fIobjPtr\fR except description of color is passed as a string and resulting (XColor *) is not cached. .AP XColor *prefPtr in @@ -71,6 +72,7 @@ in a particular window. The desired color is specified with a value whose string value must have one of the following forms: .TP 20 \fIcolorname\fR +. Any of the valid textual names for a color defined in the server's color database file, such as \fBred\fR or \fBPeachPuff\fR. .TP 20 @@ -81,6 +83,7 @@ server's color database file, such as \fBred\fR or \fBPeachPuff\fR. \fB#\fIRRRGGGBBB\fR .TP 20 \fB#\fIRRRRGGGGBBBB\fR +. A numeric specification of the red, green, and blue intensities to use to display the color. Each \fIR\fR, \fIG\fR, or \fIB\fR represents a single hexadecimal digit. The four forms permit diff --git a/doc/GetCursor.3 b/doc/GetCursor.3 index fdf773b78b..1428fb72ea 100644 --- a/doc/GetCursor.3 +++ b/doc/GetCursor.3 @@ -15,23 +15,24 @@ Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursorFromData, \fB#include \fR .sp Tk_Cursor -\fBTk_AllocCursorFromObj(\fIinterp, tkwin, objPtr\fB)\fR +\fBTk_AllocCursorFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_Cursor -\fBTk_GetCursor(\fIinterp, tkwin, name\fB)\fR +\fBTk_GetCursor\fR(\fIinterp, tkwin, name\fR) .sp Tk_Cursor -\fBTk_GetCursorFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_GetCursorFromObj\fR(\fItkwin, objPtr\fR) .sp Tk_Cursor -\fBTk_GetCursorFromData(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fB)\fR +\fBTk_GetCursorFromData\fR(\fIinterp, tkwin, source, mask, width, height, xHot, yHot, fg, bg\fR) .sp const char * -\fBTk_NameOfCursor(\fIdisplay, cursor\fB)\fR +\fBTk_NameOfCursor\fR(\fIdisplay, cursor\fR) .sp -\fBTk_FreeCursorFromObj(\fItkwin, objPtr\fB)\fR +\fBTk_FreeCursorFromObj\fR(\fItkwin, objPtr\fR) .sp -\fBTk_FreeCursor(\fIdisplay, cursor\fB)\fR +\fBTk_FreeCursor\fR(\fIdisplay, cursor\fR) +.fi .SH ARGUMENTS .AS "unsigned long" *pixelPtr .AP Tcl_Interp *interp in @@ -41,7 +42,7 @@ Token for window in which the cursor will be used. .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 const char *name in +.AP "const char" *name in Same as \fIobjPtr\fR except description of cursor is passed as a string and resulting Tk_Cursor is not cached. .AP "const char" *source in @@ -87,6 +88,7 @@ if \fIinterp\fR is not NULL. \fIObjPtr\fR must contain a standard Tcl list with one of the following forms: .TP \fIname\fR\0[\fIfgColor\fR\0[\fIbgColor\fR]] +. \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, @@ -115,6 +117,7 @@ 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 cursors for the cursor's source bits and mask. Each file must be in standard X11 cursor format. @@ -124,12 +127,14 @@ cursor, in any of the forms acceptable to \fBTk_GetColor\fR. This form of the command will not work on Macintosh or Windows computers. .TP \fB@\fIsourceName\0fgColor\fR +. This form is similar to the one above, except that the source is 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. .TP \fB@\fIsourceName\fR +. This form only works on Windows, and will load a Windows system cursor (\fB.ani\fR or \fB.cur\fR) from the file specified in \fIsourceName\fR. @@ -196,7 +201,7 @@ 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 giving the X identifier for the cursor. -Note: the string returned by \fBTk_NameOfCursor\fR is +Note that the string returned by \fBTk_NameOfCursor\fR is 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. diff --git a/doc/GetRelief.3 b/doc/GetRelief.3 index 59796629c4..d9ecb13c86 100644 --- a/doc/GetRelief.3 +++ b/doc/GetRelief.3 @@ -15,13 +15,14 @@ Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief \- translate between strings \fB#include \fR .sp int -\fBTk_GetReliefFromObj(\fIinterp, objPtr, reliefPtr\fB)\fR +\fBTk_GetReliefFromObj\fR(\fIinterp, objPtr, reliefPtr\fR) .sp int -\fBTk_GetRelief(\fIinterp, name, reliefPtr\fB)\fR +\fBTk_GetRelief\fR(\fIinterp, name, reliefPtr\fR) .sp const char * -\fBTk_NameOfRelief(\fIrelief\fB)\fR +\fBTk_NameOfRelief\fR(\fIrelief\fR) +.fi .SH ARGUMENTS .AS "Tcl_Interp" *reliefPtr .AP Tcl_Interp *interp in @@ -37,14 +38,12 @@ or .QW \fBsunken\fR (or any unique abbreviation thereof on input); the internal rep will be modified to cache corresponding relief value. -.AP char *string in +.AP "const char" *name in Same as \fIobjPtr\fR except description of relief is passed as a string. .AP int *reliefPtr out Pointer to location in which to store relief value corresponding to \fIobjPtr\fR or \fIname\fR. -.AP "const char" *name -Name of the relief. .AP int relief in Relief value (one of \fBTK_RELIEF_FLAT\fR, \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR,