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

[Drew Adams]

> > 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"?
> 
> Why do you need to know?  That's a serious question.  What practical
> importance for you is in these issues?

Did I not make it clear that the doc refers to specific behaviors, features,
etc. that affect users and that it says are available only in particular
contexts, i.e., with or without particular toolkits.

That doc, since it has brought up the qualification, needs to make clear what it
means, what those contexts are, how to tell whether you are in one or not.

> > I'm guessing that no toolkit is used on Windows.
> 
> No, that's not true.  The native Windows build uses the "Windows API
> toolkit" (a name I just invented).

A good example, then, of how incomplete and confusing the doc is.  I made my
best guess, based on the reasons I mentioned.  And I'm probably a bit more
knowledgable about Emacs generally than many Emacs users.  If my guess is that
wrong, imagine the confusion of some other users.

> A toolkit is a collection of system APIs that allow to create and
> display menus, tool bars, scroll bars, and some other frame
> decorations.  When Emacs "does not use a toolkit", it draws all of
> these itself, using its own code and graphics.

Thanks, but please don't just tell this bug thread.  If that's what users need
to understand about toolkits, please put it in the manual, so that the existing
references there to "toolkits" are elucidated.

Help users understand whether a given thing is available to them, based on its
dependence on the presence or absence of particular toolkits.

> > 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?
> 
> Users who build their Emacs on Unix have this in the help text of the
> configure script: --with-x-toolkit=KIT    use an X toolkit (KIT one
> of: yes or gtk, gtk2, gtk3, lucid or athena, motif, no)

So what?  Users who are Emacs maintainers might also know.  Users in Spokane who
take swimming lessons and wear orange jumpsuits might also know.

The target of the Elisp manual is not just users who build their own Emacs on
Unix.  The target is any Emacs user who might code with Emacs Lisp.  The target
of the Emacs manual is all Emacs users.

> There's also some guidance in INSTALL, search for "toolkit".

Emacs users are the target.  Not just Emacs installers.

And the features that the manual describes, telling users that their
availability depends on whether they have this or that toolkit, are features for
general Emacs _users_.  They are not just features for Emacs
installers/builders.

Saying that this is covered in INSTALL is a copout that perhaps reveals
something about how this doc bug came into being.

Perhaps you are not against fixing the bug and are not just trying to justify
the status quo, which would be good.  But if you do intend the reasons you give
as justification for keeping the status quo and not only as historical
background on how we got here, then we disagree that the status quo is
justified. 

> Windows users have no choice but to use the "Windows API toolkit", so
> there's nothing to decide here and therefore nothing to explain wrt
> the build process.

Not about the build process, no.  About the features that are being described as
depending on toolkit availability.

This is about the doc of such features - that is where the manuals start
drooling about toolkits.  Perhaps that drooling is altogether inappropriate, and
all such text mentioning toolkits should simply be removed.  I cannot judge
that.

In any case, the doc that does mention toolkits, without connecting the dots, is
unhelpful, confusing, and misleading.  Users should not be left scratching their
heads wondering "What's this toolkit stuff, and how do I know whether it applies
to me or not, and what do I do about it?"

> (And pleas don't pounce on me this time: the above is just to explain
> to you what is meant here.  I'm not interested in starting a
> discussion whether this is or isn't enough docs,

Fine, you're trying to help me understand a little about toolkits.  Thank you
for that.

My purpose in filing the bug is to ask that Emacs users generally be informed
about toolkits, if toolkits are in fact relevant to the doc and to users, or
that mention of toolkits be removed from the doc, if not.

> nor am I saying that what's already documented is enough.)

Good.  But see previous.  I don't know whether toolkits need to be mentioned at
all in the doc.  I know only that they _are_ mentioned - all over the place, and
that without some connecting information (relating why they are mentioned in the
places that they are) the doc is not enough.

IOW, I'm not sure whether we need more doc or less doc wrt toolkits.  I am sure
that what mention there is of toolkits is not adequate.

Thanks for taking the time to add to the background for the question here.