GNU bug report logs - #55780
29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes

Previous Next

Full log

View this message in rfc822 format

From: Eliza Velasquez <eliza <at> eliza.sh>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55780 <at> debbugs.gnu.org
Subject: bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes
Date: Fri, 03 Jun 2022 18:32:01 -0700

On Fri, Jun 03 2022 at 13:08 +02, Lars Ingebrigtsen <larsi <at> gnus.org> wrote:

> Eliza Velasquez <eliza <at> eliza.sh> 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.

Thank you for the clarification and quick fix. Perhaps the documentation
should breifly mention that at one point in time, ‘...’ was recommended?
That could save on future confusion of people who find usages of the
curly format in third party packages (as this was the first place I had
ever seen the curly format in the wild).

-- 
Eliza

Previous Next

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