* bug#17567: 24.4.50; doc string of `define-derived-mode' @ 2014-05-23 19:15 Drew Adams 2014-05-23 19:35 ` Drew Adams 0 siblings, 1 reply; 17+ messages in thread From: Drew Adams @ 2014-05-23 19:15 UTC (permalink / raw) To: 17567 The doc string erroneously says that parameter NAME is "a string which will appear in the status line". Emacs does not have a "status line". That term is used nowhere. What should be said about NAME is that it defines the value of variable `mode-name' for mode CHILD. A user consulting that variable will see that its value is used in the mode line etc. In GNU Emacs 24.4.50.1 (i686-pc-mingw32) of 2014-05-17 on ODIEONE Bzr revision: 117119 eggert@cs.ucla.edu-20140517081131-ugu7ociaoec2xk7y Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=/c/Devel/emacs/snapshot/trunk --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1 -Ic:/Devel/emacs/include'' ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2014-05-23 19:15 bug#17567: 24.4.50; doc string of `define-derived-mode' Drew Adams @ 2014-05-23 19:35 ` Drew Adams 2021-09-25 17:15 ` Stefan Kangas 0 siblings, 1 reply; 17+ messages in thread From: Drew Adams @ 2014-05-23 19:35 UTC (permalink / raw) To: 17567 Also, the doc string should state the types of the values of keywords :group, :syntax-table, and :abbrev-table. And it says that the mode runs the hook constructed by function `derived-mode-hook-name'. Constructed how? What does constructed mean here? And the doc string of `derived-mode-hook-name' is no help here: "Construct a mode-hook name based on a MODE name." The arg is MODE. What is it? What data type? And what is its "name"? What does it mean to construct a hook name? And how is that name constructed from the "MODE name"? And what about the contradiction between the doc string of `define-derived-mode' and that of `derived-mode-hook-name'? The former says that `d-m-h-name' constructs a _hook_. The latter says that it constructs a hook _name_. Far clearer for `derived-mode-hook-name' would be to just say what it really does: Return a symbol whose name is "-hook" appended to the `symbol-name' of MODE. That also makes it clear that MODE is expected to be a symbol. (Similarly, for the other `defsubst's in derived.el.) ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2014-05-23 19:35 ` Drew Adams @ 2021-09-25 17:15 ` Stefan Kangas 2021-09-25 17:30 ` Eli Zaretskii 2021-09-25 17:36 ` bug#17567: [External] : " Drew Adams 0 siblings, 2 replies; 17+ messages in thread From: Stefan Kangas @ 2021-09-25 17:15 UTC (permalink / raw) To: Drew Adams; +Cc: 17567 tags 17567 + fixed close 17567 28.1 thanks Drew Adams <drew.adams@oracle.com> writes: > The doc string erroneously says that parameter NAME is "a string > which will appear in the status line". > > Emacs does not have a "status line". That term is used nowhere. > > What should be said about NAME is that it defines the value of variable > `mode-name' for mode CHILD. A user consulting that variable will see > that its value is used in the mode line etc. Drew Adams <drew.adams@oracle.com> writes: > Also, the doc string should state the types of the values of > keywords :group, :syntax-table, and :abbrev-table. > > And it says that the mode runs the hook constructed by function > `derived-mode-hook-name'. Constructed how? What does constructed > mean here? > > And the doc string of `derived-mode-hook-name' is no help here: > "Construct a mode-hook name based on a MODE name." > > The arg is MODE. What is it? What data type? And what is > its "name"? What does it mean to construct a hook name? > And how is that name constructed from the "MODE name"? > > And what about the contradiction between the doc string of > `define-derived-mode' and that of `derived-mode-hook-name'? > The former says that `d-m-h-name' constructs a _hook_. The > latter says that it constructs a hook _name_. > > Far clearer for `derived-mode-hook-name' would be to just > say what it really does: > > Return a symbol whose name is "-hook" appended to the > `symbol-name' of MODE. > > That also makes it clear that MODE is expected to be a symbol. > > (Similarly, for the other `defsubst's in derived.el.) I have now fixed this on (commit e4c9081d46). This change will be a part of the upcoming Emacs 28.1. Please verify that this fix works for you, but for now I'm closing this bug report. If you see anything that is wrong, please reply to this email (use "Reply to all" in your email client) and we can reopen the bug report. You could also just report a new bug. Thanks again for the bug report! ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 17:15 ` Stefan Kangas @ 2021-09-25 17:30 ` Eli Zaretskii 2021-09-25 18:01 ` Stefan Kangas 2021-09-25 17:36 ` bug#17567: [External] : " Drew Adams 1 sibling, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 17:30 UTC (permalink / raw) To: Stefan Kangas; +Cc: 17567 > From: Stefan Kangas <stefan@marxist.se> > Date: Sat, 25 Sep 2021 10:15:16 -0700 > Cc: 17567@debbugs.gnu.org > > I have now fixed this on (commit e4c9081d46). This change will be a > part of the upcoming Emacs 28.1. Thanks, but IMO talking about "unquoted symbols" makes this text confusing. Why did you need to say that? My suggestion is to remove those sentences, they aren't needed. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 17:30 ` Eli Zaretskii @ 2021-09-25 18:01 ` Stefan Kangas 2021-09-25 18:46 ` Eli Zaretskii 0 siblings, 1 reply; 17+ messages in thread From: Stefan Kangas @ 2021-09-25 18:01 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 17567 Eli Zaretskii <eliz@gnu.org> writes: >> I have now fixed this on (commit e4c9081d46). This change will be a >> part of the upcoming Emacs 28.1. > > Thanks, but IMO talking about "unquoted symbols" makes this text > confusing. Why did you need to say that? My suggestion is to remove > those sentences, they aren't needed. Oh, I thought it made it more clear. As a user of this function, I basically just want to know if I need to put: :syntax-table foo-syntax-table or :syntax-table 'foo-syntax-table I'm fine with saying nothing, for the simple fact that these features aren't used that much, and it's easy to just try both variants to see which work. But I think it would be better to say something if we can come up with something clear. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 18:01 ` Stefan Kangas @ 2021-09-25 18:46 ` Eli Zaretskii 2021-09-25 19:07 ` Stefan Kangas 0 siblings, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 18:46 UTC (permalink / raw) To: Stefan Kangas; +Cc: 17567 > From: Stefan Kangas <stefan@marxist.se> > Date: Sat, 25 Sep 2021 11:01:45 -0700 > Cc: drew.adams@oracle.com, 17567@debbugs.gnu.org > > Eli Zaretskii <eliz@gnu.org> writes: > > > Thanks, but IMO talking about "unquoted symbols" makes this text > > confusing. Why did you need to say that? My suggestion is to remove > > those sentences, they aren't needed. > > Oh, I thought it made it more clear. As a user of this function, I > basically just want to know if I need to put: > > :syntax-table foo-syntax-table > > or > :syntax-table 'foo-syntax-table The first is a variable, the second is a symbol. "Unquoted symbol" is something that causes at least me to raise a brow. > I'm fine with saying nothing, for the simple fact that these features > aren't used that much, and it's easy to just try both variants to see > which work. But I think it would be better to say something if we can > come up with something clear. The thing is, we use this all over the place, so we'd need to say that everywhere. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 18:46 ` Eli Zaretskii @ 2021-09-25 19:07 ` Stefan Kangas 2021-09-25 19:11 ` Eli Zaretskii 0 siblings, 1 reply; 17+ messages in thread From: Stefan Kangas @ 2021-09-25 19:07 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 17567 Eli Zaretskii <eliz@gnu.org> writes: > The first is a variable, the second is a symbol. "Unquoted symbol" is > something that causes at least me to raise a brow. Is it better to delete that sentence and leave it as it was, or is there something else we could usefully put as an explanation? ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 19:07 ` Stefan Kangas @ 2021-09-25 19:11 ` Eli Zaretskii 2021-09-25 19:38 ` Stefan Kangas 0 siblings, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 19:11 UTC (permalink / raw) To: Stefan Kangas; +Cc: 17567 > From: Stefan Kangas <stefan@marxist.se> > Date: Sat, 25 Sep 2021 12:07:02 -0700 > Cc: drew.adams@oracle.com, 17567@debbugs.gnu.org > > Eli Zaretskii <eliz@gnu.org> writes: > > > The first is a variable, the second is a symbol. "Unquoted symbol" is > > something that causes at least me to raise a brow. > > Is it better to delete that sentence and leave it as it was, or is there > something else we could usefully put as an explanation? I think it's better to delete it. In general, when the symbol's value is needed, we don't say anything. When the symbol itself is needed, we sometimes say it should be a symbol, as in the case of add-hook: HOOK should be a symbol, ... So I think in this case we don't need to say anything. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 19:11 ` Eli Zaretskii @ 2021-09-25 19:38 ` Stefan Kangas 0 siblings, 0 replies; 17+ messages in thread From: Stefan Kangas @ 2021-09-25 19:38 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 17567 Eli Zaretskii <eliz@gnu.org> writes: > I think it's better to delete it. OK, done. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 17:15 ` Stefan Kangas 2021-09-25 17:30 ` Eli Zaretskii @ 2021-09-25 17:36 ` Drew Adams 2021-09-25 18:42 ` Eli Zaretskii 1 sibling, 1 reply; 17+ messages in thread From: Drew Adams @ 2021-09-25 17:36 UTC (permalink / raw) To: Stefan Kangas; +Cc: 17567@debbugs.gnu.org > I have now fixed this on (commit e4c9081d46). This change will be a > part of the upcoming Emacs 28.1. Thanks. > Please verify that this fix works for you, but for now I'm closing this > bug report. If you see anything that is wrong, please reply to this > email (use "Reply to all" in your email client) and we can reopen the > bug report. You could also just report a new bug. No, I won't try to verify your fix by downloading the updated files from master etc. If you'd posted the new doc string in the bug thread I could easily have, and would have, gladly checked it. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 17:36 ` bug#17567: [External] : " Drew Adams @ 2021-09-25 18:42 ` Eli Zaretskii 2021-09-25 18:59 ` Drew Adams 0 siblings, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 18:42 UTC (permalink / raw) To: Drew Adams; +Cc: stefan, 17567 > From: Drew Adams <drew.adams@oracle.com> > Date: Sat, 25 Sep 2021 17:36:16 +0000 > Cc: "17567@debbugs.gnu.org" <17567@debbugs.gnu.org> > > > Please verify that this fix works for you, but for now I'm closing this > > bug report. If you see anything that is wrong, please reply to this > > email (use "Reply to all" in your email client) and we can reopen the > > bug report. You could also just report a new bug. > > No, I won't try to verify your fix by downloading the > updated files from master etc. If you'd posted the > new doc string in the bug thread I could easily have, > and would have, gladly checked it. There's no need to download anything, the up-to-date sources can be browsed on the Savannah's Emacs project page using your Web browser. The URL was posted for your convenience many times. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 18:42 ` Eli Zaretskii @ 2021-09-25 18:59 ` Drew Adams 2021-09-25 19:05 ` Eli Zaretskii 0 siblings, 1 reply; 17+ messages in thread From: Drew Adams @ 2021-09-25 18:59 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stefan@marxist.se, 17567@debbugs.gnu.org > > No, I won't try to verify your fix by downloading the > > updated files from master etc. If you'd posted the > > new doc string in the bug thread I could easily have, > > and would have, gladly checked it. > > There's no need to download anything, the up-to-date sources can be > browsed on the Savannah's Emacs project page using your Web browser. As I said, if the updated doc string is posted in the bug-report thread then I'll be glad to check it (whether with a web browser or a mail client). But no, I'm not going to go to Savannah, find the Emacs project page, and dig out the source code. Not for a doc string correction. Far easier, and clearer for everyone, to post the doc string in the bug thread, where it will remain forever as part of that thread. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 18:59 ` Drew Adams @ 2021-09-25 19:05 ` Eli Zaretskii 2021-09-25 19:44 ` Drew Adams 0 siblings, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 19:05 UTC (permalink / raw) To: Drew Adams; +Cc: stefan, 17567 > From: Drew Adams <drew.adams@oracle.com> > CC: "stefan@marxist.se" <stefan@marxist.se>, > "17567@debbugs.gnu.org" > <17567@debbugs.gnu.org> > Date: Sat, 25 Sep 2021 18:59:13 +0000 > > > > No, I won't try to verify your fix by downloading the > > > updated files from master etc. If you'd posted the > > > new doc string in the bug thread I could easily have, > > > and would have, gladly checked it. > > > > There's no need to download anything, the up-to-date sources can be > > browsed on the Savannah's Emacs project page using your Web browser. > > As I said, if the updated doc string is posted > in the bug-report thread then I'll be glad to > check it (whether with a web browser or a mail > client). That's not how Emacs development works. People who want to track the development or participate in it are expected to access the Git repository. > But no, I'm not going to go to Savannah, find > the Emacs project page, and dig out the source > code. Not for a doc string correction. You can see the diffs there as well, if you want. No need for any digging, as the changes are shown in chronological order with their commit log messages which can be easily searched to find what you need. If you refuse to do that, you are not helping the project as much as you could have. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 19:05 ` Eli Zaretskii @ 2021-09-25 19:44 ` Drew Adams 2021-09-25 19:53 ` Eli Zaretskii 0 siblings, 1 reply; 17+ messages in thread From: Drew Adams @ 2021-09-25 19:44 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stefan@marxist.se, 17567@debbugs.gnu.org > > As I said, if the updated doc string is posted > > in the bug-report thread then I'll be glad to > > check it (whether with a web browser or a mail > > client). > > That's not how Emacs development works. People who want to track the > development or participate in it are expected to access the Git > repository. If you'd like me to check the fix (Stefan's request) then please consider putting the new text in the bug thread. Otherwise, you'll just have to do without my review and feedback, I guess. Not a biggee (the bug was anyway closed, without such a review). _I didn't request_ to review the fix ("participate" in tracking the development). I was invited to do so. I replied that if the text to review is in the bug thread then I'll be glad to review it. > > But no, I'm not going to go to Savannah, find > > the Emacs project page, and dig out the source > > code. Not for a doc string correction. > > ... If you refuse to do that, you are not helping > the project as much as you could have. If you refuse to put the updated doc string in a bug thread that asks only for a doc-string fix, then you're not helping users, or the project, as much as you could. Copy...paste...send. Simple. (I'd even consider that common courtesy, but you're by no means obliged to see courtesy the same way, of course.) ___ And if that review-request text is boilerplate (I wonder now, as I see that it mentions using "Reply to all" etc.) then you might consider adding a link to it, to the fix (manually, if not automatically). Please verify that this fix works for you, but for now I'm closing this bug report. If you see anything that is wrong, please reply to this email (use "Reply to all" in your email client) and we can reopen the bug report. You could also just report a new bug. Thanks again for the bug report! ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 19:44 ` Drew Adams @ 2021-09-25 19:53 ` Eli Zaretskii 2021-09-25 21:08 ` Drew Adams 0 siblings, 1 reply; 17+ messages in thread From: Eli Zaretskii @ 2021-09-25 19:53 UTC (permalink / raw) To: Drew Adams; +Cc: stefan, 17567 > From: Drew Adams <drew.adams@oracle.com> > CC: "stefan@marxist.se" <stefan@marxist.se>, > "17567@debbugs.gnu.org" > <17567@debbugs.gnu.org> > Date: Sat, 25 Sep 2021 19:44:50 +0000 > > > > As I said, if the updated doc string is posted > > > in the bug-report thread then I'll be glad to > > > check it (whether with a web browser or a mail > > > client). > > > > That's not how Emacs development works. People who want to track the > > development or participate in it are expected to access the Git > > repository. > > If you'd like me to check the fix (Stefan's request) > then please consider putting the new text in the bug > thread. Otherwise, you'll just have to do without > my review and feedback, I guess. Not a biggee (the > bug was anyway closed, without such a review). This response makes no sense to me. You don't mind writing the longest email messages ever, but refuse to type a 50-character URL into your browser? Why? But whatever. > If you refuse to put the updated doc string in a bug > thread that asks only for a doc-string fix, then > you're not helping users, or the project, as much as > you could. Copy...paste...send. Simple. No, it's not simple. There's no place to copy/paste from, because installing a change usually doesn't involve looking at the diffs, or even producing them. We edit the sources and commit them, that's it. > (I'd even consider that common courtesy, but you're > by no means obliged to see courtesy the same way, > of course.) Yes of course: everyone has to be courteous to you, but you don't feel you need to be courteous to others. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 19:53 ` Eli Zaretskii @ 2021-09-25 21:08 ` Drew Adams 2021-09-27 22:36 ` Richard Stallman 0 siblings, 1 reply; 17+ messages in thread From: Drew Adams @ 2021-09-25 21:08 UTC (permalink / raw) To: Eli Zaretskii; +Cc: stefan@marxist.se, 17567@debbugs.gnu.org > > If you'd like me to check the fix (Stefan's request) > > then please consider putting the new text in the bug > > thread. Otherwise, you'll just have to do without > > my review and feedback, I guess. Not a biggee (the > > bug was anyway closed, without such a review). > > This response makes no sense to me. You don't mind writing the > longest email messages ever, but refuse to type a 50-character URL > into your browser? Why? This response makes no sense to me. You don't mind dragging out this thread, but pasting the updated doc string into the thread, after requesting its review, is too much trouble? Why? Reviewing text starts with the text to be reviewed. And it's often collaborative - back & forth. Doing that in one place is more productive than sending a reviewer off to some diffs somewhere. A typical doc review involves, well, doc, not just diffs. > But whatever. Indeed. > > > If you refuse to do that, you are not helping > > > the project as much as you could have. > > > > If you refuse to put the updated doc string in a bug > > thread that asks only for a doc-string fix, then > > you're not helping users, or the project, as much as > > you could. Copy...paste...send. Simple. > > No, it's not simple. There's no place to copy/paste from, because > installing a change usually doesn't involve looking at the diffs, or > even producing them. We edit the sources and commit them, that's it. It's apparently too hard for someone who's fixed a doc string to look at the edited result (sources) in an Emacs buffer and copy that. OK, got it. It's likewise too hard for me to dig out the diffs and reconstruct the resulting doc string from them, in order to respond to a review request. Not the end of the world, but the end of the review, I guess. Again, I didn't ask to review the fix. (And the bug is already closed. I didn't say a word about that, except "Thanks". I just responded to the review request ("please verify"), with a request for the text to review.) > > (I'd even consider that common courtesy, but you're > > by no means obliged to see courtesy the same way, > > of course.) > > Yes of course: everyone has to be courteous to you, > but you don't feel you need to be courteous to others. I do feel that need. And I try to be courteous, and I want to, even when some, such as yourself, are needlessly aggressive, such as now. And it's not about being courteous to me. Showing the text to be reviewed is, in my world, a normal, courteous part of asking for a review - regardless of who the review is requested from or who's doing the requesting. Asking for a review is asking for help. Unnecessary hurdles make it harder to help. Filing bug reports, just like fixing bugs, is helping, or trying to. We're all volunteers here, though you seem to keep opposing volunteers who fix problems to volunteers who report them. I'm thankful for both the fixers and the reporters. ^ permalink raw reply [flat|nested] 17+ messages in thread
* bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode' 2021-09-25 21:08 ` Drew Adams @ 2021-09-27 22:36 ` Richard Stallman 0 siblings, 0 replies; 17+ messages in thread From: Richard Stallman @ 2021-09-27 22:36 UTC (permalink / raw) To: Drew Adams, Eli Zaretskii; +Cc: stefan, 17567 [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] Please, colleagues, defend your positions without persoal antagonism. -- Dr Richard Stallman (https://stallman.org) Chief GNUisance of the GNU Project (https://gnu.org) Founder, Free Software Foundation (https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org) ^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2021-09-27 22:36 UTC | newest] Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2014-05-23 19:15 bug#17567: 24.4.50; doc string of `define-derived-mode' Drew Adams 2014-05-23 19:35 ` Drew Adams 2021-09-25 17:15 ` Stefan Kangas 2021-09-25 17:30 ` Eli Zaretskii 2021-09-25 18:01 ` Stefan Kangas 2021-09-25 18:46 ` Eli Zaretskii 2021-09-25 19:07 ` Stefan Kangas 2021-09-25 19:11 ` Eli Zaretskii 2021-09-25 19:38 ` Stefan Kangas 2021-09-25 17:36 ` bug#17567: [External] : " Drew Adams 2021-09-25 18:42 ` Eli Zaretskii 2021-09-25 18:59 ` Drew Adams 2021-09-25 19:05 ` Eli Zaretskii 2021-09-25 19:44 ` Drew Adams 2021-09-25 19:53 ` Eli Zaretskii 2021-09-25 21:08 ` Drew Adams 2021-09-27 22:36 ` Richard Stallman
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).