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

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

[João Távora]

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

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

[Phil Sainty]

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.

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

[Antoine Kalmbach]

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

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

[João Távora]

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.

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

[Lars Ingebrigtsen]

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

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

[João Távora]

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

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

[Lars Ingebrigtsen]

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