Subject: Re: bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes

From: Lars Ingebrigtsen <[email-masked]>
Date: Fri, 03 Jun 2022 13:08:19 +0200

Eliza Velasquez <[email-masked]> writes:

> The elisp manual states in "(elisp)Documentation Tips"
>
>> 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 (‘..’).
>
> ‘checkdoc’ treats this case as valid.
>
> Recently, though, it seems like bytecomp.el’s
> ‘byte-compile-docstring-style-warn’ function was recently modified by
> 2701cd59b521989530a7eb7489540c64177e0f69 which mistakenly flags this
> usage as incorrect.

The ‘..’ convention in doc strings was introduced in 2015, but never
really took off -- even after seven years, there were only a dozen
usages in-tree, so it seemed time to revert back to the previous
convention (which is to use `...', which is then converted to ‘...’ on
display).  The problem with ‘..’ is that nobody still knows how to type
it, and if you're working on a display that can't display those
characters, the help texts are all messed up.  (Which isn't the case
when using `...'.)

I forgot to update the documentation here, though, so I've now done
that.  Perhaps it's a bit early to issue a compilation warning for this,
though, since it's probably found in the wild here and there, so I've
now disabled that in Emacs 29.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no