On Mon, Nov 14, 2022 at 1:05 PM Eli Zaretskii <eliz@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