bug#17567: 24.4.50; doc string of `define-derived-mode'

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Stefan Kangas]

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!

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Stefan Kangas]

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.

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Stefan Kangas]

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?

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: 24.4.50; doc string of `define-derived-mode'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I think it's better to delete it.

OK, done.

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Eli Zaretskii]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Drew Adams]

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

bug#17567: [External] : Re: bug#17567: 24.4.50; doc string of `define-derived-mode'

[Richard Stallman]

[[[ 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)