GNU bug report logs - #59082
28.2; Undocumented `intern-soft` feature with shorthands symbols

Previous Next

Full log

View this message in rfc822 format

From: João Távora <joaotavora <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: thievol <at> posteo.net, rms <at> gnu.org, 59082 <at> debbugs.gnu.org
Subject: bug#59082: 28.2; Undocumented `intern-soft` feature with shorthands symbols
Date: Mon, 14 Nov 2022 13:36:15 +0000

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

On Mon, Nov 14, 2022 at 1:05 PM Eli Zaretskii <eliz <at> gnu.org> wrote:

> I think it really is such a widespread (and good) practice to include
> cross-references in doc strings that it should be a no-brainer to
> decide that supporting this practice is important.
>

OK, are these the only examples? Because my brain also tells me
that these could be fixed by hand, for example:

-previously found match, use `s-count-matches'."
+previously found match, use `magnars-string-count-matches'."

Of course, I agree that if we have this support in the docstring
logic, it is more convenient to _not_ have to do this edit.

Anyway, I hope everyone here is on the same page that
whatever the implementation of that support is, when typing
C-h f s-count-matches OR C-h f magnars-string-count-matches
in a buffer where read-symbol-shorthands is non-nil, then what appears
in the subsequent _global_ *Help* buffer is sth like:

  magnars-string-count-matches-all is a function defined in
magnars-string.el

  Blabla... see, also magnars-string-count-matches.

I.e. the name of the symbol is `magnars-string-count-matches`,
not `s-count-matches`: that's just a local shorthand in that particular
hypothetical buffer (the local shorthand s- being particularly popular
for the library in question).

IOW it would be plainly wrong to print the symbol as s-count-matches
in the *Help* buffer.  Even though that's a popular shorthand, another
buffer where `s-` is already taken for `sandworms-` might have decided
to use the shorthand `str-` instead for `magnar-string.el`

I know I keep reminding this, I just want to make sure everyone
understands this.

João

[Message part 2 (text/html, inline)]

Previous Next

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