* docstring has wrong usage of unescaped single quotes (use \= or different quoting)
@ 2022-07-22 10:24 João Távora
2022-07-22 12:27 ` Phil Sainty
2022-07-22 12:31 ` Antoine Kalmbach
0 siblings, 2 replies; 7+ messages in thread
From: João Távora @ 2022-07-22 10:24 UTC (permalink / raw
To: emacs-devel
Hi,
This byte-compilation warning pops up all over the place now. I've
fixed it in some of my packages, but when byte-compiling I'm interested
in those warnings that, when unheeded, could cause my program logic to
produce incorrect results and/or waste resources. Perhaps I'm mistaken,
but this does not seem like one such thing. This is particularly noisy
when hunting problems with 'flymake-mode'.
Docstring checking code should go into "checkdoc", so one has a choice
of removing its checkdoc backend and the associated noise if one is not
interested in it.
Furthermore, in a tangent issue, I don't understand exactly the
suggestion in the warning message. How exactly is \= to be used? \='
doesn't work. In one of my docstrings I had an elisp snippet for users
to copy-paste and I ended replacing the quote character with the 'quote'
special form, which works but now produces an inferior docstring.
Thanks,
João
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 10:24 docstring has wrong usage of unescaped single quotes (use \= or different quoting) João Távora
@ 2022-07-22 12:27 ` Phil Sainty
2022-07-22 12:31 ` Antoine Kalmbach
1 sibling, 0 replies; 7+ messages in thread
From: Phil Sainty @ 2022-07-22 12:27 UTC (permalink / raw
To: João Távora; +Cc: emacs-devel
On 2022-07-22 22:24, João Távora wrote:
> Furthermore, in a tangent issue, I don't understand exactly the
> suggestion in the warning message. How exactly is \= to be used?
> \=' doesn't work.
To include \=' in a double-quoted string you need to write it as
"\\='", as backslashes need escaping in the read syntax for strings.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 10:24 docstring has wrong usage of unescaped single quotes (use \= or different quoting) João Távora
2022-07-22 12:27 ` Phil Sainty
@ 2022-07-22 12:31 ` Antoine Kalmbach
2022-07-22 14:12 ` João Távora
1 sibling, 1 reply; 7+ messages in thread
From: Antoine Kalmbach @ 2022-07-22 12:31 UTC (permalink / raw
To: João Távora; +Cc: emacs-devel
I believe the syntax to get a docstring to show "Blah blah 'foo" to show
correctly you'd have to write "Blah blah \\='foo".
Interestingly, such errors are not reported by checkdoc, but as you
mentioned, byte-compilation reports them.
--
Antoine Kalmbach
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 12:31 ` Antoine Kalmbach
@ 2022-07-22 14:12 ` João Távora
2022-07-22 14:38 ` Lars Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: João Távora @ 2022-07-22 14:12 UTC (permalink / raw
To: Antoine Kalmbach, Phil Sainty; +Cc: emacs-devel
Antoine Kalmbach <ane@iki.fi> writes:
> I believe the syntax to get a docstring to show "Blah blah 'foo" to show
> correctly you'd have to write "Blah blah \\='foo".
Thanks Phil and Antoine, I'll try that.
> Interestingly, such errors are not reported by checkdoc, but as you
> mentioned, byte-compilation reports them.
Yep. Maybe the idea is to be more "aggressive" so that these docstring
issues are addressed sooner. That's because more people run the byte
compiler than run checkdoc (which is extremely picky and has lots of
"false positives"). So I think I can understand that this is a good
intention.
But, IMHO, introducing such a new warning that has little to do with
byte-compilation is a drag on people working with existing packages and
looking for byte-compilation issues. Maybe there is a flag to turn off
or demote this warning, and maybe that flag could be used in
elisp-flymake-byte-compile.
João
PS: I'm with the non-fancy/ASCII quote crowd, but I don't oppose
allowing or recommending such fancy quotes in docstrings. I just don't
want that to hinder my normal workflow when maintaining old packages.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 14:12 ` João Távora
@ 2022-07-22 14:38 ` Lars Ingebrigtsen
2022-07-22 15:23 ` João Távora
0 siblings, 1 reply; 7+ messages in thread
From: Lars Ingebrigtsen @ 2022-07-22 14:38 UTC (permalink / raw
To: João Távora; +Cc: Antoine Kalmbach, Phil Sainty, emacs-devel
João Távora <joaotavora@gmail.com> writes:
> But, IMHO, introducing such a new warning that has little to do with
> byte-compilation is a drag on people working with existing packages and
> looking for byte-compilation issues.
We've been using byte compilation warnings for ages to make people
actually fix things that aren't, strictly speaking, necessary for
getting something to byte compile. For instance, deprecation warnings
and warnings about not using save-excursion+set-buffer. These new
warnings are about more "real" problems than those two, in a way,
because they indicate that the markup used in the doc string is
incorrect, and people trying to use code examples from the doc string
will fail (for instance, when a (setq bar 'foo) is rendered as
(setq bar ’foo) in the *Help* buffer.
> Maybe there is a flag to turn off
> or demote this warning, and maybe that flag could be used in
> elisp-flymake-byte-compile.
See `byte-compile-warning-types'.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 14:38 ` Lars Ingebrigtsen
@ 2022-07-22 15:23 ` João Távora
2022-07-22 20:08 ` Lars Ingebrigtsen
0 siblings, 1 reply; 7+ messages in thread
From: João Távora @ 2022-07-22 15:23 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: Antoine Kalmbach, Phil Sainty, emacs-devel
Lars Ingebrigtsen <larsi@gnus.org> writes:
> João Távora <joaotavora@gmail.com> writes:
>
>> But, IMHO, introducing such a new warning that has little to do with
>> byte-compilation is a drag on people working with existing packages and
>> looking for byte-compilation issues.
>
> We've been using byte compilation warnings for ages to make people
> actually fix things that aren't, strictly speaking, necessary for
> getting something to byte compile. For instance, deprecation warnings
> and warnings about not using save-excursion+set-buffer.
Presumably these warnings tell me something about the
forward-compatiblity, performance, or otherwise functional aspects of my
program. I do not count the documentation there. It's not that I don't
pay attention to it, but I don't necessarily do simultaneously when
making my program functionally correct. This is why we one has
different checkers, and why different checkers check different things.
In the byte-compilation check, this is a hack. Else we may just as well
add spell-checking to the byte-compiler.
>> Maybe there is a flag to turn off
>> or demote this warning, and maybe that flag could be used in
>> elisp-flymake-byte-compile.
>
> See `byte-compile-warning-types'.
Thanks.
João
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: docstring has wrong usage of unescaped single quotes (use \= or different quoting)
2022-07-22 15:23 ` João Távora
@ 2022-07-22 20:08 ` Lars Ingebrigtsen
0 siblings, 0 replies; 7+ messages in thread
From: Lars Ingebrigtsen @ 2022-07-22 20:08 UTC (permalink / raw
To: João Távora; +Cc: Antoine Kalmbach, Phil Sainty, emacs-devel
João Távora <joaotavora@gmail.com> writes:
> In the byte-compilation check, this is a hack. Else we may just as well
> add spell-checking to the byte-compiler.
The doc strings are not plain text. They use a specific markup
language, and the warnings are about that markup being invalid. This is
not comparable to spell-checking text.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2022-07-22 20:08 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-07-22 10:24 docstring has wrong usage of unescaped single quotes (use \= or different quoting) João Távora
2022-07-22 12:27 ` Phil Sainty
2022-07-22 12:31 ` Antoine Kalmbach
2022-07-22 14:12 ` João Távora
2022-07-22 14:38 ` Lars Ingebrigtsen
2022-07-22 15:23 ` João Távora
2022-07-22 20:08 ` 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).