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

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

> > > > 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.
> 
> But do you have specific cases where this prevented you from
> understanding the intended behavior?  Can you at least give one or 2
> examples of such places in the documentation?

Nearly every occurrence of it, IIRC.  It is not at all clear whether the given
behavior applies to the current user's context (platform etc.).  And it is not
at all clear how the user can find out whether it does.

> > 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.
> 
> Differences between the various toolkits is a vast subject, and gets
> more and more so as time passes and new toolkits and new versions are
> developed.  It might take a large document to describe the differences
> in any level of detail.  In the Emacs manuals, I think we should only
> describe the absolute minimum without which it would be unclear what
> the manual says.  That's why I ask about practical implications of
> this.

I agree: describe only what you need to describe, to enable users to understand
what you are trying to tell them.

It is the Emacs doc that throws "toolkit" in here, telling users IF you have a
toolkit (or if you have X, Y, or Z toolkit) THEN the behavior is THIS, not THAT.

The user cannot understand whether s?he has behavior THIS or THAT, without Emacs
providing info about whether and which toolkit the user has.  Or if it can, then
it should, and should just remove any mention of the toolkit.

It's one or the other - it's not fair to conditionalize things on something that
is unknown, not understood, and for which we give no info about how to find the
answer.

Naive question: Couldn't Emacs provide a way (at runtime, dynamically) for the
user to answer the question of whether and which toolkit s?he has?  That would
seem to be the best solution:

1. Ensure that the doc mentions toolkit only when it needs to (i.e., when that
is useful) - the principle you espoused above.

2. Add a brief description blurb somewhere saying what a toolkit is, and
preferably adding a link outside the manual to more information about that
topic.  IOW, do not go into details about toolkits, but give a brief
explanation/definition, just as you would do for "frobglith" or "plunop".

3. Give users an easy way (e.g. a command or variable) to tell what toolkit they
have (e.g., nil means no toolkit).

> > > 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.
> 
> Please tell how did that help you understand something in the manual
> you couldn't figure out before, and you will have gained one more
> person to agree with you on this.

It is #2 above.  It might not be the final text you choose for that, but it is
at least a start in that direction.

IOW, (1) IF we tell users that a given behavior depends on the toolkit THEN we
point to the doc section where we present, (3) what a toolkit is, and (2) how to
find out whether you have a toolkit and if so which toolkit you have.

> You referred to the Emacs build process, so I responded with
> toolkit-related information available for those who build Emacs.  If
> the build process is not relevant to your report, let's forget about
> this argument of yours.

I know next to nothing about toolkits.  You referred to the build process as a
way to know what toolkit you have.  IF that is the only way to know that THEN we
are leaving out letting non-builders know what toolkit they have.

Clearly, all users should have a quick, easy way to determine whether they have
a toolkit, and which.  That is, unless there is no need to mention toolkits at
all in the doc.  Currently knowledge of this is necessary to know about the
availability of multiple features and behaviors in Emacs.

> > The target of the Elisp manual is not just users who build 
> > their own Emacs on Unix.
> 
> In fact, describing the build process is not a goal of the ELisp
> manual at all, it only mentions that in an appendix in the context of
> describing the internal details of how certain things done during the
> build work.

We agree.

> > 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.
> 
> When the manuals mention toolkits, they say something like "with some
> toolkits, this will work so-and-so" or "depending on the toolkit, this
> function might return this-and-that value".  This basically means
> "don't rely on that behavior or that value, because they might vary".
> How would knowing what a "toolkit" is help clearing this intentionally
> vague description?

Sometimes that is what they say.  In that case, there is not a problem,
especially if you follow up with just what you said: THEREFORE, do not rely
on...

But in other cases we say that such and such a behavior is not available if you
have a toolkit, or if you do not have one, or if your toolkit is X, Y, or Z, or
not X, Y, or Z.

We should distinguish clearly between the two cases.  And for the former we
should explicitly give the point, not just the background reason: the point is
that you should not rely on this...  And for the latter we should point users to
the (new) manual section that tells them how to quickly, easily determine
whether they have a toolkit, and which.

> It was your argument to mention the build process.

No.  It is the _manual_ that sends users off scratching their heads about the
build process.  That's the point.  The closest the manual comes to helping users
understand anything at all about toolkits is to send them investingating how
Emacs gets built.  That's a big mistake, IMHO.

This is what I really said, "to mention the build process":

>>> 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?

> > Not about the build process, no.  About the features that 
> > are being described as depending on toolkit availability.
> 
> But the manuals do not tell which toolkit will do what in these cases.
> If they were, then the Windows behavior should have been described
> there, as well as exactly what each toolkit and what the non-toolkit
> version does in each of these circumstances.  If this is what you are
> asking for, then why not say that explicitly, instead of asking "what
> is a toolkit", a question whose answer, which I just gave, evidently
> didn't help you understand whatever you didn't before?

See (1), (2), (3), above.  And yes, we do tell users that certain behaviors are
available or not available only with a toolkit etc.  And yes, this is the main
problem I've raised: they cannot know what behavior to expect without
(apparently) knowing whether they have a toolkit (and in some cases what toolkit
they have).

> > 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?"
> 
> The manuals clearly say that it could or could not be applicable,
> depending on how Emacs was built.

Yes, and you interpret that in every occurrence as meaning that the reader
should not care and should not rely on...?  If that is indeed the message in
each case then we should say that: you do not need to know this, and you should
not rely on it.

Another interpretation is possible: the manual is telling me this because I need
to know whether I have a toolkit, so that I can determine whether behavior XYZ
applies to me.  That's a very different message.

> > 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.
> 
> That cannot be judged, IMO, without hearing specific instances where
> that information would help in understanding what the manuals say.

I hope that someone with knowledge about whether toolkit knowledge is pertinent
to this or that occurrence of "toolkit" in the manual will review all of the
occurrences and then judge and fix accordingly.