[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Symbol quotation in doc strings

From: Arash Esbati
Subject: Re: Symbol quotation in doc strings
Date: Sun, 29 May 2022 19:29:45 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50

Hi Keita,

Ikumi Keita <> 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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]