How to disable warnings about single quotes in emacs-29

How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


I have now such warnings:

Warning: docstring has wrong usage of unescaped single quotes (use \= or different quoting)

How one is supposed to stop these warnings apart replacing all "'"
accumulated since 12 years or so with "\\='".

Thanks.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Philip Kaludercic]

Thierry Volpiatto <thievol@posteo.net> writes:

> I have now such warnings:
>
> Warning: docstring has wrong usage of unescaped single quotes (use \=
> or different quoting)
>
> How one is supposed to stop these warnings apart replacing all "'"
> accumulated since 12 years or so with "\\='".

A short-term, radical solution would be to set `byte-compile-warnings',
globally or file locally, to (not docstrings).


I am surprised that the byte compiler is taking care of this, and not
checkdoc.  Checkdoc could at least propose to automatically fix the
text.

> Thanks.

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Philip Kaludercic <philipk@posteo.net> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>> I have now such warnings:
>>
>> Warning: docstring has wrong usage of unescaped single quotes (use \=
>> or different quoting)
>>
>> How one is supposed to stop these warnings apart replacing all "'"
>> accumulated since 12 years or so with "\\='".
>
> A short-term, radical solution would be to set `byte-compile-warnings',
> globally or file locally, to (not docstrings).

I expected this too, but no native-compilation doesn't take care of local
variables, anyway using (no docstrings) doesn't cover this problem AFAIK.

>
> I am surprised that the byte compiler is taking care of this, and not
> checkdoc.  Checkdoc could at least propose to automatically fix the
> text.

Didn't try checkdoc, but as long as one use text-quoting-style==grave he
should not be annoyed by this.

Thanks.

-- 
Thierry (annoyed by these quoting style problems since emacs-25)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Thierry Volpiatto <thievol@posteo.net> writes:

> How one is supposed to stop these warnings apart replacing all "'"
> accumulated since 12 years or so with "\\='".

Are there any false positives in the warnings?  (Many people don't know
that a 'foo is displayed as ’foo, which isn't what they intended to have
displayed.)

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>> How one is supposed to stop these warnings apart replacing all "'"
>> accumulated since 12 years or so with "\\='".
>
> Are there any false positives in the warnings?

No.

> (Many people don't know that a 'foo is displayed as ’foo, which isn't
> what they intended to have displayed.)

I don't want to display 'foo as ’foo, I even don't know how to type this
on my keyboard, I was quite quiet during some time by setting
text-quoting-style to grave, but it seems not enough.
However I had to fix all the quotes in helm with "\\=". I had to write
code to do this at once. But now docstrings in source code looks ugly
and I will have to remember to use "\\=" each time I quote something
like `foo', really a pain.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Thierry Volpiatto <thievol@posteo.net> writes:

> I don't want to display 'foo as ’foo, I even don't know how to type this
> on my keyboard, I was quite quiet during some time by setting
> text-quoting-style to grave, but it seems not enough.

(That disables the ' => ’ translation for yourself, but not for others
that use the package, of course.)

> However I had to fix all the quotes in helm with "\\=". I had to write
> code to do this at once. But now docstrings in source code looks ugly
> and I will have to remember to use "\\=" each time I quote something
> like `foo', really a pain.

There no warnings for `foo', surely?

But if you want all quotes to never be displayed as the Unicode quotes
for all users of your packages, then nothing has changed in about a
decade -- you have to escape the quotes, because (by default) they're
translated.  The only thing that's new is that the byte compilation
warns when

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>> I don't want to display 'foo as ’foo, I even don't know how to type this
>> on my keyboard, I was quite quiet during some time by setting
>> text-quoting-style to grave, but it seems not enough.
>
> (That disables the ' => ’ translation for yourself, but not for others
> that use the package, of course.)

Yes, right.

>> However I had to fix all the quotes in helm with "\\=". I had to write
>> code to do this at once. But now docstrings in source code looks ugly
>> and I will have to remember to use "\\=" each time I quote something
>> like `foo', really a pain.
>
> There no warnings for `foo', surely?

Yes there is, to stop warning we have to write `foo\\=', same for
e.g. "don't do this" we need "don\\='t do this" to avoid warnings.

> But if you want all quotes to never be displayed as the Unicode quotes
> for all users of your packages, then nothing has changed in about a
> decade -- you have to escape the quotes, because (by default) they're
> translated.  The only thing that's new is that the byte compilation
> warns when

Would be great to be able to put a local variable like
text-quoting-style in files or .dir-locals to stop this.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Thierry Volpiatto <thievol@posteo.net> writes:

>> There no warnings for `foo', surely?
>
> Yes there is, to stop warning we have to write `foo\\=', same for
> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.

I don't get any warnings for those.  Do you have a recipe to reproduce
this?

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>>> There no warnings for `foo', surely?
>>
>> Yes there is, to stop warning we have to write `foo\\=', same for
>> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.
>
> I don't get any warnings for those.

You need emacs-29 native compiled and look at the *warnings* buffer when
restarting emacs, you have not such warnings when compiling e.g. with make.

> Do you have a recipe to reproduce this?

Not yet, will try to make one soon.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Thierry Volpiatto <thievol@posteo.net> writes:

>>> Yes there is, to stop warning we have to write `foo\\=', same for
>>> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.
>>
>> I don't get any warnings for those.
>
> You need emacs-29 native compiled and look at the *warnings* buffer when
> restarting emacs, you have not such warnings when compiling e.g. with make.

Sounds like a bug.

>> Do you have a recipe to reproduce this?
>
> Not yet, will try to make one soon.

Great; please report it with report-emacs-bug.

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>>>> Yes there is, to stop warning we have to write `foo\\=', same for
>>>> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.
>>>
>>> I don't get any warnings for those.
>>
>> You need emacs-29 native compiled and look at the *warnings* buffer when
>> restarting emacs, you have not such warnings when compiling e.g. with make.
>
> Sounds like a bug.

No, I don't have anymore those warnings after fixing others i.e. I have
reverted and fixed all quote but `foo' and quotes inside words like
"don't".
Stay, would be great to avoid such warnings with a local variable,
something like "byte-compile-warnings: (not docstrings)" like suggested
previously.

Thanks.


-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Stefan Monnier]

>> There no warnings for `foo', surely?
> Yes there is, to stop warning we have to write `foo\\=', same for
> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.

If you bump into such a warning, please report it as a bug.
Emacs's own source compiles without emitting any such warnings, so you
can be sure that there are at least *some* cases where "don't" and
"`foo'" does not cause a warning, since we have many of those in
our docstrings.  The things that tend to cause warnings are:

   Set this to 'foo in order to crok the struble.

which should be rewritten to:

   Set this to `foo' in order to crok the struble.


-- Stefan

Re: How to disable warnings about single quotes in emacs-29

[Kaushal Modi]

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

On Tue, Jun 7, 2022, 8:57 AM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> >> There no warnings for `foo', surely?
> > Yes there is, to stop warning we have to write `foo\\=', same for
> > e.g. "don't do this" we need "don\\='t do this" to avoid warnings.
>
> If you bump into such a warning, please report it as a bug.
>

+1

Also I believe that almost all of such instances were already fixed when
the curved quotes feature went in (few years back).

Related blog post where I summarized how to specify if you want straight
quotes instead of curved in doc strings and messages:
https://scripter.co/straight-and-curved-quotes-in-emacs-lisp/

Feedback is welcome (probably in a different thread).

>

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Kaushal Modi <kaushal.modi@gmail.com> writes:

> Related blog post where I summarized how to specify if you want
> straight quotes instead of curved in doc strings and
> messages: https://scripter.co/straight-and-curved-quotes-in-emacs-lisp/

Thanks for the link.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> There no warnings for `foo', surely?
>> Yes there is, to stop warning we have to write `foo\\=', same for
>> e.g. "don't do this" we need "don\\='t do this" to avoid warnings.
>
> If you bump into such a warning, please report it as a bug.

I think I don't have such warnings now.

> The things that tend to cause warnings are:
>
>    Set this to 'foo in order to crok the struble.
>
> which should be rewritten to:
>
>    Set this to `foo' in order to crok the struble.

Yes, I have some of those, problem is to detect them when replacing
apart writing something more elaborated, the code I used didn't
differency these from the one to replace so I replaced with \\='foo
instead.

Thanks.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Thierry Volpiatto <thievol@posteo.net> writes:

> Stay, would be great to avoid such warnings with a local variable,
> something like "byte-compile-warnings: (not docstrings)" like suggested
> previously.

I think that should work?  (I haven't tested, but skimming the code, it
looks like it's supposed to.)

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

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Lars Ingebrigtsen <larsi@gnus.org> writes:

> Thierry Volpiatto <thievol@posteo.net> writes:
>
>> Stay, would be great to avoid such warnings with a local variable,
>> something like "byte-compile-warnings: (not docstrings)" like suggested
>> previously.
>
> I think that should work?  (I haven't tested, but skimming the code, it
> looks like it's supposed to.)

Same, it is working when byte compiling with e.g. make but
native-compile seems to ignore such variable.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Stefan Monnier]

> Same, it is working when byte compiling with e.g. make but
> native-compile seems to ignore such variable.

Sounds like a bug.


        Stefan

Re: How to disable warnings about single quotes in emacs-29

[T.V Raman]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=gb18030, Size: 454 bytes --]

If we generate warnings that are annoying, that then lead to developers
turning off warnings, it has two negative consequences:

1. Useful warnings get ignored 
2. The work that went into generating those annoying warnings is wasted.

So I suggest that if we find developers  reporting warnings that are
annoying, then we fix the annoyance,

-- 

Thanks,

--Raman(I Search, I Find, I Misplace, I Research)
7©4 Id: kg:/m/0285kf1  •0Ü8

Re: How to disable warnings about single quotes in emacs-29

[Phil Sainty]

On 2022-06-08 07:42, T.V Raman wrote:
> So I suggest that if we find developers reporting warnings that
> are annoying, then we fix the annoyance,

In this instance, it sounds like the warnings were all correct,
with the possible exception that some unescaped instances of
'foo may (although it's not clear to me) have caused some
false-positive warnings about instances of `foo' in the same
docstring?

So the annoyance was justified and disabling the warnings would
have been a mistake, yes?

Re: How to disable warnings about single quotes in emacs-29

[Po Lu]

Phil Sainty <psainty@orcon.net.nz> writes:

> In this instance, it sounds like the warnings were all correct,
> with the possible exception that some unescaped instances of
> 'foo may (although it's not clear to me) have caused some
> false-positive warnings about instances of `foo' in the same
> docstring?
>
> So the annoyance was justified and disabling the warnings would
> have been a mistake, yes?

Shouldn't this warning be part of checkdoc and not the byte compiler
itself?

Re: How to disable warnings about single quotes in emacs-29

[Phil Sainty]

On 2022-06-08 13:14, Po Lu wrote:
> Shouldn't this warning be part of checkdoc and not the byte compiler
> itself?

I expect you could argue it both ways.

`checkdoc' says its purpose is to "check the entire buffer for style
errors", but IMO the \\=' issue is more a "bug" than a "style error"
(as it will typically be about documented lisp code).

I do think such bugs are far more likely to be addressed if they're
produced by the byte-compiler, so to me it doesn't seem like a bad
thing unless it's prone to false-positives (in which case compilation
warnings would be pretty frustrating).

Re: How to disable warnings about single quotes in emacs-29

[Po Lu]

Phil Sainty <psainty@orcon.net.nz> writes:

> I expect you could argue it both ways.
>
> `checkdoc' says its purpose is to "check the entire buffer for style
> errors", but IMO the \\=' issue is more a "bug" than a "style error"
> (as it will typically be about documented lisp code).
>
> I do think such bugs are far more likely to be addressed if they're
> produced by the byte-compiler, so to me it doesn't seem like a bad
> thing unless it's prone to false-positives (in which case compilation
> warnings would be pretty frustrating).

checkdoc was eventually supposed to be integrated into the
byte-compiler, I think.  Errors in doc strings are not fatal to the
program either, so I'd call them "style errors".

Re: How to disable warnings about single quotes in emacs-29

[Thierry Volpiatto]

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


Po Lu <luangruo@yahoo.com> writes:

> Phil Sainty <psainty@orcon.net.nz> writes:
>
>> I expect you could argue it both ways.
>>
>> `checkdoc' says its purpose is to "check the entire buffer for style
>> errors", but IMO the \\=' issue is more a "bug" than a "style error"
>> (as it will typically be about documented lisp code).
>>
>> I do think such bugs are far more likely to be addressed if they're
>> produced by the byte-compiler, so to me it doesn't seem like a bad
>> thing unless it's prone to false-positives (in which case compilation
>> warnings would be pretty frustrating).
>
> checkdoc was eventually supposed to be integrated into the
> byte-compiler, I think.  Errors in doc strings are not fatal to the
> program either, so I'd call them "style errors".

Checkdoc is nice, but it would be too much work to fix such warnings
with checkdoc one buffer after the other (48 buffers), I had to use a
function that do it all at once without asking.

-- 
Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 686 bytes --]

Re: How to disable warnings about single quotes in emacs-29

[Michael Heerdegen]

Thierry Volpiatto <thievol@posteo.net> writes:

> Checkdoc is nice, but it would be too much work to fix such warnings
> with checkdoc one buffer after the other (48 buffers), I had to use a
> function that do it all at once without asking.

`byte-compile-docstring-style-warn' does this:

#+begin_src emacs-lisp
(when (string-match-p "\\( \"\\|[ \t]\\|^\\)'[a-z(]" docs)
        (byte-compile-warn-x
         name "%s%sdocstring has wrong usage of unescaped single quotes (use \\= or different quoting)"
         kind name))
#+end_src

Maybe you can use that regexp to find a (semi) automated way of fixing?

Michael.

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

"T.V Raman" <raman@google.com> writes:

> If we generate warnings that are annoying, that then lead to developers
> turning off warnings, it has two negative consequences:
>
> 1. Useful warnings get ignored 
> 2. The work that went into generating those annoying warnings is wasted.
>
> So I suggest that if we find developers  reporting warnings that are
> annoying, then we fix the annoyance,

There will always (absolutely always) be (some) developers that find
whatever we're changing annoying, so that's not a good rule of thumb.

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

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

> checkdoc was eventually supposed to be integrated into the
> byte-compiler, I think.  Errors in doc strings are not fatal to the
> program either, so I'd call them "style errors".

It's not warning about style errors -- doc strings are written in a
markup language, and it's warning about errors in that markup language.
Putting "For instance, (setq foo 'bar)" in a doc string is wrong -- the
doc string displayed in *Help* will be syntactically wrong.

(And we use the byte compiler to report about a bunch of stylistic
problems, like the usage of save-excursion+set-buffer.)

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

Re: How to disable warnings about single quotes in emacs-29

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> It's not warning about style errors -- doc strings are written in a
> markup language, and it's warning about errors in that markup language.
> Putting "For instance, (setq foo 'bar)" in a doc string is wrong -- the
> doc string displayed in *Help* will be syntactically wrong.

But the byte compiler compiles Emacs Lisp, not doc strings.  I think we
should move everything related to doc string markup into checkdoc, and
then resolve the TODO about integrating that with the byte compiler,
perhaps by adding a new warning type `checkdoc' for warnings from
checkdoc.

> (And we use the byte compiler to report about a bunch of stylistic
> problems, like the usage of save-excursion+set-buffer.)

Those stylistic problems affect Lisp, not help buffers.

Re: How to disable warnings about single quotes in emacs-29

[Lars Ingebrigtsen]

Po Lu <luangruo@yahoo.com> writes:

> But the byte compiler compiles Emacs Lisp, not doc strings.

The byte compiler compiles .el files, and the doc strings are part of
that.

> I think we should move everything related to doc string markup into
> checkdoc, and then resolve the TODO about integrating that with the
> byte compiler, perhaps by adding a new warning type `checkdoc' for
> warnings from checkdoc.

Checkdoc is about stylistic issues, which is something else than this
warning.

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

Re: How to disable warnings about single quotes in emacs-29

[Po Lu]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The byte compiler compiles .el files, and the doc strings are part of
> that.

Doc strings are, well, strings.  Only the help mechanisms care about
them.

> Checkdoc is about stylistic issues, which is something else than this
> warning.

This warning _is_ about a stylistic issue.  There is nothing incorrect
about defuns with doc strings formatted so that they are not readable in
help buffers.