[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against vali
From: |
Lars Ingebrigtsen |
Subject: |
bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes |
Date: |
Fri, 03 Jun 2022 13:08:19 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) |
Eliza Velasquez <eliza@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.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no