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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55780 in the body.
You can then email your comments to 55780 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Eliza Velasquez <eliza <at> eliza.sh>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; byte-compile-docstring-style-warn warns against valid
 usages of curved quotes
Date: Thu, 02 Jun 2022 17:04:41 -0700

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. Its news entry states:

> When writing code snippets that contains the ' character (APOSTROPHE),
> that quote character has to be escaped to avoid Emacs displaying it as
> ’ (LEFT SINGLE QUOTATION MARK), which would make code examples like
> 
>     (setq foo '(1 2 3))
> 
> invalid.  Emacs will now warn during byte compilation if it seems
> something like that, and also warn about when using RIGHT/LEFT SINGLE
> QUOTATION MARK directly.  In both these cases, if these characters
> should really be present in the doc string, they should be quoted with
> \=.

Judging by both this news entry and the implementation's regex, I assume
this is intended to catch erroneous cases like “(setq foo ’(1 2 3))” and
allow correct usages like “it’s”, but it inadvertently flags cases like
“‘lisp-mode’”.

In GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.33, cairo version 1.16.0)
Repository revision: e06d600b4963fc6ccc69fb0bbbc725350a80c9fc
Repository branch: master
System Description: NixOS 22.11 (Raccoon)

Configured using:
 'configure
 --prefix=/nix/store/banascjwdai200brq116c4m54jx10if9-emacs-pgtk-native-comp-20220529.0
 --disable-build-details --with-modules --with-x-toolkit=gtk3
 --with-cairo --with-native-compilation --with-pgtk'

-- 
Eliza

Message #8 received at 55780 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eliza Velasquez <eliza <at> eliza.sh>
Cc: 55780 <at> debbugs.gnu.org
Subject: Re: 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

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.

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

Message #13 received at 55780 <at> debbugs.gnu.org (full text, mbox):

From: Eliza Velasquez <eliza <at> eliza.sh>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55780 <at> debbugs.gnu.org
Subject: Re: 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

Message #16 received at 55780 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eliza Velasquez <eliza <at> eliza.sh>
Cc: 55780 <at> debbugs.gnu.org
Subject: Re: bug#55780: 29.0.50; byte-compile-docstring-style-warn warns
 against valid usages of curved quotes
Date: Sat, 04 Jun 2022 13:30:14 +0200

Eliza Velasquez <eliza <at> eliza.sh> writes:

> 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).

Good idea -- I've now added a note about this.

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

Message #19 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Andreas Röhler <andreas.roehler <at> easy-emacs.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#55780: 29.0.50; byte-compile-docstring-style-warn warns
 against valid usages of curved quotes
Date: Sat, 4 Jun 2022 14:21:50 +0200

[Message part 1 (text/plain, inline)]

Am 04.06.22 um 13:30 schrieb Lars Ingebrigtsen:
> Eliza Velasquez<eliza <at> eliza.sh>  writes:
>
>> 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).
> Good idea -- I've now added a note about this.
>

BTW is there a name for the now new old style - backtick-quoted-symbol?

[Message part 2 (text/html, inline)]

Message #22 received at 55780 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Andreas Röhler <andreas.roehler <at> easy-emacs.de>
Cc: 55780 <at> debbugs.gnu.org
Subject: Re: bug#55780: 29.0.50; byte-compile-docstring-style-warn warns
 against valid usages of curved quotes
Date: Sat, 04 Jun 2022 15:15:15 +0200

Andreas Röhler <andreas.roehler <at> easy-emacs.de> writes:

> BTW is there a name for the now new old style - backtick-quoted-symbol?

I think we sometimes call them "fancy quotes"?

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

Previous Next

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