Re: Symbol quotation in doc strings

[Arash Esbati]

Hi Keita,

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> In recent commits 6fe2f21e and 3447aa75 about doc strings, several
> references on elisp symbols were converted like this:
> ----------------------------------------------------------------------
> @@ -5661,7 +5661,7 @@ characters."
> [...]
> -DIRECTION can be indicated by the symbols 'forward and 'backward.
> +DIRECTION can be indicated by the symbols \\='forward and \\='backward.
> [...]
> ----------------------------------------------------------------------
> However, info node `(elisp) Documentation Tips' directs to quote elisp
> symbol in ‘this style’ or `this style' rather than "\='" quoting:
> ,----
> |    • When a documentation string refers to a Lisp symbol, write it as it
> |      would be printed (which usually means in lower case), surrounding
> |      it with curved single quotes (‘..’).
> |   [...]
> |      Documentation strings can also use an older single-quoting
> |      convention, which quotes symbols with grave accent ` and apostrophe
> |      ': `like-this' rather than ‘like-this’.
> `----
> So I think it would be more appropriate to follow this convention. Is
> there any circumstances I'm missing?

My changes were primarily meant to silence the Emacs (29 master)
compiler.  In general, you're of course right, those symbols should be
written `like this'.  I currently wouldn't do ‘like-this’ since it
raises other warnings about fancy quotes, c.f. here for example[1].

If you want to clean up after me (I would be grateful, of course ;-),
please go ahead, otherwise I will try to address this soon.

Best, Arash

Footnotes:
[1]  https://lists.gnu.org/archive/html/help-gnu-emacs/2022-05/msg00324.html