bug#13490: toolkit, toolkit, who's got the toolkit?

["Drew Adams" <drew.adams@oracle.com>]

OK, let's play "Button, button, who's got the button?".

I'm using MS Windows.  Dunno whether that means that no toolkit is
used.  Where do I find that information?  How does an Emacs user even
know what Emacs means by a "toolkit"?

There is no `toolkit' index entry in the Elisp manual.  Searching
it for "toolkit" shows only one mention of a particular platform
in this regard, in `Defining Menus':

  "(1) It is required for menus which do not use a toolkit, e.g.,
   under MS-DOS."

"Toolkit" is mentioned _all over_ the Elisp manual, without once
saying what it means.  And without once listing which platforms have
toolkits (aside from mentioning that MS-DOS does not), or how to tell
whether your Emacs uses a toolkit.

IOW, all of those references to "toolkit" in the Elisp manual are
essentially incomprehensible, meaningless - might as well be talking
about a "frobglith" or a "plunop".

I'm guessing that no toolkit is used on Windows.  I'm guessing that,
because searching the manual finds places where it speaks of X Window,
GTK+, Lucid, and Motif toolkits (but without any index entries for
these and no references for them outside the manual), but there is
no mention of an MS Windows toolkit.  And I happen to know that MS
Windows does not use any of X Window, Lucid, etc.  (Some Emacs users
might not know that.)

That's just a wild guess on my part, though - the doc is no real
help here, AFAICT.  The doc freely says things like "On toolkits
that support menu titles...", without, again, saying anything about
what those toolkits are or how to tell whether you have one.

The Emacs manual is unfortunately just as bad: "for menu bars when
toolkit menus are not used...", "when Emacs is built on X with no
toolkit support...", "when Emacs is built with a suitable GUI
toolkit...", "Emacs does this when built with GTK, LessTif, and Motif
toolkits...", "If Emacs is compiled to use an X toolkit...", "If Emacs
is compiled on the X Window System without X toolkit support...", "In
non-X-toolkit versions of Emacs...".

And so on - there are many, many more, just as vague and unhelpful.

How to know about any of that?  Why on earth would we refer Emacs
_users_ to the Emacs build process to find out whether and which
toolkits might be used and therefore whether some feature being
presented is in fact supported?

And again, just as in the Elisp manual, there no index entries in
the Emacs manual for these particular toolkits (or for "toolkit"),
and no outside references for them.

Please fix these doc problems.  Define terms; index things;
reference information available outside the manual.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-31 on ODIEONE
Bzr revision: 111388 rudalics@gmx.at-20121231113513-subz2dazg6yjukzh
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'