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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <13490@debbugs.gnu.org>
> Date: Fri, 18 Jan 2013 13:30:51 -0800
> 
> > > 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?

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

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

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

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.

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

> > There's also some guidance in INSTALL, search for "toolkit".
> 
> Emacs users are the target.  Not just Emacs installers.

INSTALL is for users who build their own Emacs.  It is not for
"installers", whoever they are.

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

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

It was your argument to mention the build process.

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

I explicitly refrained from passing judgment on this issue.  I asked
you not to consider my message as such a judgment.  What else could I
have said to make that more clear?

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

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?

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

> > (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.

You are welcome.

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