GNU bug report logs - #75290
Fwd: remove-pos-from-symbol and bare-symbol

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 75290 in the body.
You can then email your comments to 75290 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: Stefan Kangas <stefankangas <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Fwd: remove-pos-from-symbol and bare-symbol
Date: Thu, 2 Jan 2025 11:22:44 -0600

Severity: wishlist

I'm forwarding this to the bug tracker so that we don't lose track of
it.  Alan, any comments here?

-------------------- Start of forwarded message --------------------
From: Richard Stallman <rms <at> gnu.org>
To: emacs-devel <at> gnu.org
Subject: remove-pos-from-symbol and bare-symbol
Date: Sun, 10 Mar 2024 22:39:23 -0400

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

The doc string of remove-pos-from-symbol says to compare it with
bare-symbol.  The doc strings are too sketchy to make clear what the
difference is.  Someone who knows should make that clear.

Is the difference what they do to an argument that is not a symbol?
If so, it would be good to state that explicitly in the doc string
of bare-symbol.  "If need be" is not explicit, not concrete.

I tried looking at the macros they call, which are in lisp.h.  But
those don't have doc strings and just call other functions that have
no comments to say what they do.

The macros and inline functions in lisp.h need to be documented there.

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



-------------------- End of forwarded message --------------------

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

From: Alan Mackenzie <acm <at> muc.de>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: acm <at> muc.de, 75290 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Sun, 5 Jan 2025 16:08:35 +0000

Hello, Stefan.

Thanks for the Cc:.

On Thu, Jan 02, 2025 at 11:22:44 -0600, Stefan Kangas wrote:
> Severity: wishlist

> I'm forwarding this to the bug tracker so that we don't lose track of
> it.  Alan, any comments here?

Yes.  I remember vaguely having some difficulty formulating these doc
strings.  Making them accurate would have made them less readable.  So I
erred on the side of sketchy rather than unreadable.  I underestimated
the amount of difficulty this would cause.

> -------------------- Start of forwarded message --------------------
> From: Richard Stallman <rms <at> gnu.org>
> To: emacs-devel <at> gnu.org
> Subject: remove-pos-from-symbol and bare-symbol
> Date: Sun, 10 Mar 2024 22:39:23 -0400

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

> The doc string of remove-pos-from-symbol says to compare it with
> bare-symbol.  The doc strings are too sketchy to make clear what the
> difference is.  Someone who knows should make that clear.

> Is the difference what they do to an argument that is not a symbol?

Yes.  bare-symbol signals an error, remove-pos-from-symbol returns a
non-symbol argument unchanged.

> If so, it would be good to state that explicitly in the doc string
> of bare-symbol.  "If need be" is not explicit, not concrete.

OK.  The current doc string for bare-symbol is:

    Extract, if need be, the bare symbol from SYM.
    SYM is either a symbol or a symbol with position.
    Ignore `symbols-with-pos-enabled'.

How about the following replacement?

    Extract and return the bare symbol from SYM, when it is a symbol
    with position.  Return SYM unchanged when it is a symbol.  Otherwise
    signal an error.  Ignore `symbols-with-pos-enable'.

    Compare with `remove-pos-from-symbol'.

> I tried looking at the macros they call, which are in lisp.h.  But
> those don't have doc strings and just call other functions that have
> no comments to say what they do.

> The macros and inline functions in lisp.h need to be documented there.

I agree, this is bad and needs rectifying.  The time taken to fix this
would be less than the time wasted by people reading it and having to
figure out for themselves what each macro/function does.

When I added symbols with position to this part of lisp.h, I just did so
in the style of the existing code, i.e. undocumented.

I think somebody should fix it now.

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



> -------------------- End of forwarded message --------------------

-- 
Alan Mackenzie (Nuremberg, Germany).

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 75290 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Sat, 1 Mar 2025 20:17:53 -0800

Alan Mackenzie <acm <at> muc.de> writes:

> Hello, Stefan.
>
> Thanks for the Cc:.
>
> On Thu, Jan 02, 2025 at 11:22:44 -0600, Stefan Kangas wrote:
>> Severity: wishlist
>
>> I'm forwarding this to the bug tracker so that we don't lose track of
>> it.  Alan, any comments here?
>
> Yes.  I remember vaguely having some difficulty formulating these doc
> strings.  Making them accurate would have made them less readable.  So I
> erred on the side of sketchy rather than unreadable.  I underestimated
> the amount of difficulty this would cause.
>
>> -------------------- Start of forwarded message --------------------
>> From: Richard Stallman <rms <at> gnu.org>
>> To: emacs-devel <at> gnu.org
>> Subject: remove-pos-from-symbol and bare-symbol
>> Date: Sun, 10 Mar 2024 22:39:23 -0400
>
>> [[[ 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. ]]]
>
>> The doc string of remove-pos-from-symbol says to compare it with
>> bare-symbol.  The doc strings are too sketchy to make clear what the
>> difference is.  Someone who knows should make that clear.
>
>> Is the difference what they do to an argument that is not a symbol?
>
> Yes.  bare-symbol signals an error, remove-pos-from-symbol returns a
> non-symbol argument unchanged.
>
>> If so, it would be good to state that explicitly in the doc string
>> of bare-symbol.  "If need be" is not explicit, not concrete.
>
> OK.  The current doc string for bare-symbol is:
>
>     Extract, if need be, the bare symbol from SYM.
>     SYM is either a symbol or a symbol with position.
>     Ignore `symbols-with-pos-enabled'.
>
> How about the following replacement?
>
>     Extract and return the bare symbol from SYM, when it is a symbol
>     with position.  Return SYM unchanged when it is a symbol.  Otherwise
>     signal an error.  Ignore `symbols-with-pos-enable'.
>
>     Compare with `remove-pos-from-symbol'.

Richard, could you please comment on this?

>> I tried looking at the macros they call, which are in lisp.h.  But
>> those don't have doc strings and just call other functions that have
>> no comments to say what they do.
>
>> The macros and inline functions in lisp.h need to be documented there.
>
> I agree, this is bad and needs rectifying.  The time taken to fix this
> would be less than the time wasted by people reading it and having to
> figure out for themselves what each macro/function does.
>
> When I added symbols with position to this part of lisp.h, I just did so
> in the style of the existing code, i.e. undocumented.
>
> I think somebody should fix it now.

Would you be willing to propose such docstrings?

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

From: Alan Mackenzie <acm <at> muc.de>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 75290 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Tue, 4 Mar 2025 20:06:30 +0000

Hello, Stefan.

On Sat, Mar 01, 2025 at 20:17:53 -0800, Stefan Kangas wrote:
> Alan Mackenzie <acm <at> muc.de> writes:

> > Hello, Stefan.

> > Thanks for the Cc:.

> > On Thu, Jan 02, 2025 at 11:22:44 -0600, Stefan Kangas wrote:
> >> Severity: wishlist

> >> I'm forwarding this to the bug tracker so that we don't lose track of
> >> it.  Alan, any comments here?

> > Yes.  I remember vaguely having some difficulty formulating these doc
> > strings.  Making them accurate would have made them less readable.  So I
> > erred on the side of sketchy rather than unreadable.  I underestimated
> > the amount of difficulty this would cause.

> >> -------------------- Start of forwarded message --------------------
> >> From: Richard Stallman <rms <at> gnu.org>
> >> To: emacs-devel <at> gnu.org
> >> Subject: remove-pos-from-symbol and bare-symbol
> >> Date: Sun, 10 Mar 2024 22:39:23 -0400

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

> >> The doc string of remove-pos-from-symbol says to compare it with
> >> bare-symbol.  The doc strings are too sketchy to make clear what the
> >> difference is.  Someone who knows should make that clear.

> >> Is the difference what they do to an argument that is not a symbol?

> > Yes.  bare-symbol signals an error, remove-pos-from-symbol returns a
> > non-symbol argument unchanged.

> >> If so, it would be good to state that explicitly in the doc string
> >> of bare-symbol.  "If need be" is not explicit, not concrete.

> > OK.  The current doc string for bare-symbol is:

> >     Extract, if need be, the bare symbol from SYM.
> >     SYM is either a symbol or a symbol with position.
> >     Ignore `symbols-with-pos-enabled'.

> > How about the following replacement?

> >     Extract and return the bare symbol from SYM, when it is a symbol
> >     with position.  Return SYM unchanged when it is a symbol.  Otherwise
> >     signal an error.  Ignore `symbols-with-pos-enable'.

> >     Compare with `remove-pos-from-symbol'.

> Richard, could you please comment on this?

> >> I tried looking at the macros they call, which are in lisp.h.  But
> >> those don't have doc strings and just call other functions that have
> >> no comments to say what they do.

> >> The macros and inline functions in lisp.h need to be documented there.

> > I agree, this is bad and needs rectifying.  The time taken to fix this
> > would be less than the time wasted by people reading it and having to
> > figure out for themselves what each macro/function does.

> > When I added symbols with position to this part of lisp.h, I just did so
> > in the style of the existing code, i.e. undocumented.

> > I think somebody should fix it now.

> Would you be willing to propose such docstrings?

I'm afraid I need to decline such requests.  I'm no longer working on
Emacs (except for CC Mode, and possibly things I'm "responsible" for).
I'm now working on other things.

Sorry.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 75290 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Tue, 4 Mar 2025 20:50:17 +0000

Alan Mackenzie <acm <at> muc.de> writes:

>> Would you be willing to propose such docstrings?
>
> I'm afraid I need to decline such requests.  I'm no longer working on
> Emacs (except for CC Mode, and possibly things I'm "responsible" for).
> I'm now working on other things.
>
> Sorry.

Understood, and thanks for letting us know.

I suppose we need someone else to familiarize themselves with this code
and make the docstring improvements here.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: acm <at> muc.de, 75290-done <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Thu, 06 Mar 2025 12:55:00 +0200

> Cc: 75290 <at> debbugs.gnu.org, rms <at> gnu.org
> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Tue, 4 Mar 2025 20:50:17 +0000
> 
> Alan Mackenzie <acm <at> muc.de> writes:
> 
> >> Would you be willing to propose such docstrings?
> >
> > I'm afraid I need to decline such requests.  I'm no longer working on
> > Emacs (except for CC Mode, and possibly things I'm "responsible" for).
> > I'm now working on other things.
> >
> > Sorry.
> 
> Understood, and thanks for letting us know.
> 
> I suppose we need someone else to familiarize themselves with this code
> and make the docstring improvements here.

The required changes in the doc strings are so simple that frankly I
was surprised by Alan's response.

Anyway, this is now fixed on the emacs-30 release branch; closing.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: acm <at> muc.de, 75290 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol
Date: Thu, 6 Mar 2025 03:08:45 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

> Anyway, this is now fixed on the emacs-30 release branch; closing.

Thanks for doing that.

Previous Next

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