* bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes
@ 2022-06-03 0:04 Eliza Velasquez
2022-06-03 11:08 ` Lars Ingebrigtsen
0 siblings, 1 reply; 6+ messages in thread
From: Eliza Velasquez @ 2022-06-03 0:04 UTC (permalink / raw)
To: 55780
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes
2022-06-03 0:04 bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes Eliza Velasquez
@ 2022-06-03 11:08 ` Lars Ingebrigtsen
2022-06-04 1:32 ` Eliza Velasquez
0 siblings, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-03 11:08 UTC (permalink / raw)
To: Eliza Velasquez; +Cc: 55780
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes
2022-06-03 11:08 ` Lars Ingebrigtsen
@ 2022-06-04 1:32 ` Eliza Velasquez
2022-06-04 11:30 ` Lars Ingebrigtsen
0 siblings, 1 reply; 6+ messages in thread
From: Eliza Velasquez @ 2022-06-04 1:32 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 55780
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes
2022-06-04 1:32 ` Eliza Velasquez
@ 2022-06-04 11:30 ` Lars Ingebrigtsen
2022-06-04 12:21 ` Andreas Röhler
0 siblings, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2022-06-04 11:30 UTC (permalink / raw)
To: Eliza Velasquez; +Cc: 55780
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-06-04 13:15 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-06-03 0:04 bug#55780: 29.0.50; byte-compile-docstring-style-warn warns against valid usages of curved quotes Eliza Velasquez
2022-06-03 11:08 ` Lars Ingebrigtsen
2022-06-04 1:32 ` Eliza Velasquez
2022-06-04 11:30 ` Lars Ingebrigtsen
2022-06-04 12:21 ` Andreas Röhler
2022-06-04 13:15 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).