all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* 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 external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.