Subject: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol

From: Alan Mackenzie <[email-masked]>
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 <[email-masked]> 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 <[email-masked]>
> >> To: [email-masked]
> >> 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).