>>>>> "David" == David Kastrup
David> I seem to have a spectacularly bad command of language:
David> what I asked for was to document the return value of
David> make-glyph, maybe a two-line change. A wish that has
David> seemingly not made it into the multi-hundred line change.
Yeah, I noticed that. I've been planning to take a look at this.
`make-glyph' returns a glyph object, and to me, the docs do say that:
"Create a new glyph of type TYPE.
A glyph in XEmacs does NOT refer to a single unit of textual display (the
XEmacs term for this is \"rune\"), but rather is an object encapsulating
a graphical element, such as an image or widget (an element such as a
button or text field; \"widget\" is the term for this under X Windows,
and it's called a \"control\" under MS Windows). This graphical element
could appear in a buffer, a margin, a gutter, or a toolbar, or as a mouse
pointer or an icon, for example.
Creating a glyph using `make-glyph' does not specify *where* the glyph
will be used, but it does specify *what* the glyph will look like. In
particular, SPEC-LIST is used to specify this, and it's used to
initialize the glyph's `image' property, which is an image
specifier. (Note that \"image\" as used in the context of a glyph's
`image' property or in the terms \"image specifier\", \"image
instantiator\", or \"image instance\" does not refer to what people
normally think of as an image (which in XEmacs is called a
\"pixmap\"), but to any graphical element -- a pixmap, a widget, or
even a block of text, when used in the places that call for a glyph.)
Since they don't for you, David, could you tell me what kind of wording
would help you?
Would it be enough if the first line said "Create and return a new glyph
object of type TYPE"?