GNU bug report logs - #66928
[PATCH 2/2] Update names to match the docstring

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66928 in the body.
You can then email your comments to 66928 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: [PATCH 2/2] Update names to match the docstring
Date: Sat, 04 Nov 2023 12:49:27 +0000

[Message part 1 (text/plain, inline)]

Tags: patch

Hello

I noticed that for the function below the docstring doesn't match the
arg names.  I've chosen to keep the docstring on the basis that it may
be what has been the most visible for a time, and update the names in
the code.

In general, is it TRT?  Do we have a convention to keep names or the
docstring.  Please let me know if this patch is useful in its current
form or a change is needed.

thanks
Jeremy 

[0002-Update-names-to-match-the-docstring.patch (text/patch, attachment)]

Message #8 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 66928 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#66928: [PATCH 2/2] Update names to match the docstring
Date: Sat, 04 Nov 2023 15:00:23 +0200

> Date: Sat, 04 Nov 2023 12:49:27 +0000
> From:  Jeremy Bryant via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> I noticed that for the function below the docstring doesn't match the
> arg names.

That's why we have the "(fn SYMBOL PROPNAME)" part there.

Message #11 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Sat, 04 Nov 2023 12:13:05 -0400

> I noticed that for the function below the docstring doesn't match the
> arg names.

I agree it's an odd choice (requiring the use of `\n(fn SYMBOL PROPNAME)`),
but it's not a big problem since the (fn SYMBOL PROPNAME) makes sure
that the right names are presented in `C-h o`.

If you want to install a patch like you suggest, then please remove the
(fn SYMBOL PROPNAME) since it makes it redundant.
It'd be considered as a cosmetic patch.

One more thing: the first line of the commit should be a bit more
specific, e.g. it could start with "(cl-remprop):"


        Stefan

Message #14 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Sat, 04 Nov 2023 22:56:14 +0000

thank you, I will work on this.

One question, the elisp manual mentions that the \(fn ARGLIST) facility
is particularly useful for macros.

Why would we use this for defuns?  What is TRT in general?

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> I noticed that for the function below the docstring doesn't match the
>> arg names.
>
> I agree it's an odd choice (requiring the use of `\n(fn SYMBOL PROPNAME)`),
> but it's not a big problem since the (fn SYMBOL PROPNAME) makes sure
> that the right names are presented in `C-h o`.
>
> If you want to install a patch like you suggest, then please remove the
> (fn SYMBOL PROPNAME) since it makes it redundant.
> It'd be considered as a cosmetic patch.
>
> One more thing: the first line of the commit should be a bit more
> specific, e.g. it could start with "(cl-remprop):"
>
>
>         Stefan

Message #17 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Sat, 04 Nov 2023 23:34:00 +0000

[Message part 1 (text/plain, inline)]

Attached is a proposed patch to install, with the two changes requested.

This is cosmetic patch.

[0002-lisp-emacs-lisp-cl-extra.el-cl-remprop-Update-names-.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> I noticed that for the function below the docstring doesn't match the
>> arg names.
>
> I agree it's an odd choice (requiring the use of `\n(fn SYMBOL PROPNAME)`),
> but it's not a big problem since the (fn SYMBOL PROPNAME) makes sure
> that the right names are presented in `C-h o`.
>
> If you want to install a patch like you suggest, then please remove the
> (fn SYMBOL PROPNAME) since it makes it redundant.
> It'd be considered as a cosmetic patch.
>
> One more thing: the first line of the commit should be a bit more
> specific, e.g. it could start with "(cl-remprop):"
>
>
>         Stefan

Message #20 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Sun, 05 Nov 2023 09:09:57 -0500

> One question, the elisp manual mentions that the \(fn ARGLIST) facility
> is particularly useful for macros.
>
> Why would we use this for defuns?

We use it for some defuns where ELisp's arglist functionality is not
refined enough to express the intention of the programmer.
For example, the "real" arglist may be

    name args &optional docstring &rest body

but the intended arglist is

    name args [docstring] &rest body

i.e. if `docstring` is not a string it's taken as the first instruction
of `body`.


        Stefan

Message #23 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Mon, 06 Nov 2023 22:55:39 +0000

Interesting, thank you 
Perhaps it would be of interest to add some text to the elisp manual in
(elisp) Function Documentation

Are there any conventions for manual additions?
in particular to keep the number of printed pages limited is there a way
to say 'don't print this node'?

thanks
Jeremy


Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> One question, the elisp manual mentions that the \(fn ARGLIST) facility
>> is particularly useful for macros.
>>
>> Why would we use this for defuns?
>
> We use it for some defuns where ELisp's arglist functionality is not
> refined enough to express the intention of the programmer.
> For example, the "real" arglist may be
>
>     name args &optional docstring &rest body
>
> but the intended arglist is
>
>     name args [docstring] &rest body
>
> i.e. if `docstring` is not a string it's taken as the first instruction
> of `body`.
>
>
>         Stefan

Message #28 received at 66928-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 66928-done <at> debbugs.gnu.org
Subject: Re: bug#66928: [PATCH 2/2] Update names to match the docstring
Date: Sun, 12 Nov 2023 15:54:24 -0500

> I noticed that for the function below the docstring doesn't match the
> arg names.  I've chosen to keep the docstring on the basis that it may

This is now fixed, closing,


        Stefan

Message #31 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Jeremy Bryant <jb <at> jeremybryant.net>
Cc: 66928 <at> debbugs.gnu.org
Subject: Re: [PATCH 2/2] Update names to match the docstring
Date: Sun, 12 Nov 2023 16:02:00 -0500

> Perhaps it would be of interest to add some text to the elisp manual
> in (elisp) Function Documentation

There's already a note about the (fn ...) convention, but if you have an
idea of something that would have been helpful to, please send us your
suggestion :-)

> Are there any conventions for manual additions?
> in particular to keep the number of printed pages limited is there a way
> to say 'don't print this node'?

I think there were ways to keep some parts out of the printed manual,
but I'm not sure this is relevant to the ELisp manual any more: is it
still printed?

The FSF shop still carries the Emacs manual and the ELisp intro, but
I can't see the ELisp manual in there.


        Stefan

Message #34 received at 66928 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>, Richard Stallman <rms <at> gnu.org>
Cc: 66928 <at> debbugs.gnu.org, jb <at> jeremybryant.net
Subject: Re: bug#66928: [PATCH 2/2] Update names to match the docstring
Date: Mon, 13 Nov 2023 15:58:30 +0200

> Cc: 66928 <at> debbugs.gnu.org
> Date: Sun, 12 Nov 2023 16:02:00 -0500
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> > Are there any conventions for manual additions?
> > in particular to keep the number of printed pages limited is there a way
> > to say 'don't print this node'?
> 
> I think there were ways to keep some parts out of the printed manual,

Yes, use @ifnottex..@end ifnottex.

> but I'm not sure this is relevant to the ELisp manual any more: is it
> still printed?
> 
> The FSF shop still carries the Emacs manual and the ELisp intro, but
> I can't see the ELisp manual in there.

Richard?

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.