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

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

[Eliza Velasquez]

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

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

[Lars Ingebrigtsen]

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

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

[Eliza Velasquez]

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

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

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

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

[Lars Ingebrigtsen]

Eliza Velasquez <eliza@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

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

[Andreas Röhler]

[-- Attachment #1: Type: text/plain, Size: 565 bytes --]


Am 04.06.22 um 13:30 schrieb Lars Ingebrigtsen:
> Eliza Velasquez<eliza@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?

[-- Attachment #2: Type: text/html, Size: 1198 bytes --]

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

[Lars Ingebrigtsen]

Andreas Röhler <andreas.roehler@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