* bug#13490: toolkit, toolkit, who's got the toolkit? @ 2013-01-18 18:59 Drew Adams 2013-01-18 19:45 ` Eli Zaretskii 0 siblings, 1 reply; 6+ messages in thread From: Drew Adams @ 2013-01-18 18:59 UTC (permalink / raw) To: 13490 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' ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13490: toolkit, toolkit, who's got the toolkit? 2013-01-18 18:59 bug#13490: toolkit, toolkit, who's got the toolkit? Drew Adams @ 2013-01-18 19:45 ` Eli Zaretskii 2013-01-18 21:30 ` Drew Adams 0 siblings, 1 reply; 6+ messages in thread From: Eli Zaretskii @ 2013-01-18 19:45 UTC (permalink / raw) To: Drew Adams; +Cc: 13490 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Fri, 18 Jan 2013 10:59:29 -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? > 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 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. > 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) There's also some guidance in INSTALL, search for "toolkit". 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. (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, nor am I saying that what's already documented is enough.) ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13490: toolkit, toolkit, who's got the toolkit? 2013-01-18 19:45 ` Eli Zaretskii @ 2013-01-18 21:30 ` Drew Adams 2013-01-19 10:37 ` Eli Zaretskii 0 siblings, 1 reply; 6+ messages in thread From: Drew Adams @ 2013-01-18 21:30 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 13490 > > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13490: toolkit, toolkit, who's got the toolkit? 2013-01-18 21:30 ` Drew Adams @ 2013-01-19 10:37 ` Eli Zaretskii 2013-01-19 15:39 ` Drew Adams 0 siblings, 1 reply; 6+ messages in thread From: Eli Zaretskii @ 2013-01-19 10:37 UTC (permalink / raw) To: Drew Adams; +Cc: 13490 > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13490: toolkit, toolkit, who's got the toolkit? 2013-01-19 10:37 ` Eli Zaretskii @ 2013-01-19 15:39 ` Drew Adams 2020-08-31 2:32 ` Stefan Kangas 0 siblings, 1 reply; 6+ messages in thread From: Drew Adams @ 2013-01-19 15:39 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 13490 > > > > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13490: toolkit, toolkit, who's got the toolkit? 2013-01-19 15:39 ` Drew Adams @ 2020-08-31 2:32 ` Stefan Kangas 0 siblings, 0 replies; 6+ messages in thread From: Stefan Kangas @ 2020-08-31 2:32 UTC (permalink / raw) To: Drew Adams; +Cc: 13490 tags 13490 + wontfix close 13490 thanks There is a lengthy discussion here where it is suggested that we define the word "toolkit" in the Emacs manual. Eli didn't see the need for it, and I agree with that. Anyone who needs to know what it is will be able to find out by searching the web for "emacs toolkit". So I'm closing this as wontfix. ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-08-31 2:32 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2013-01-18 18:59 bug#13490: toolkit, toolkit, who's got the toolkit? Drew Adams 2013-01-18 19:45 ` Eli Zaretskii 2013-01-18 21:30 ` Drew Adams 2013-01-19 10:37 ` Eli Zaretskii 2013-01-19 15:39 ` Drew Adams 2020-08-31 2:32 ` Stefan Kangas
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).