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

[Alan Mackenzie <acm@muc.de>]

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@gnu.org>
> To: emacs-devel@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).