~protesilaos/modus-themes

4 2

Addressing compilation warning: docstring has wrong usage of unescaped single quotes

Details
Message ID
<87bktlvgyy.fsf@rfc20.org>
DKIM signature
pass
Download raw message
I noticed that a recent Emacs master version issues compilation warnings
for modus-themes.el. These become visible with nativcomp builds, so it
would be nice to address them. The warning is new and was added to Emacs
in this commit:

> commit 2701cd59b521989530a7eb7489540c64177e0f69
> Author: Lars Ingebrigtsen <larsi@gnus.org>
> Date:   Tue May 24 18:48:39 2022 +0200
>
>    Make byte compilation warn about wrong quoting in doc strings

The warning is new, but the issue is an old one. See the thread "How to
disable warnings about single quotes in emacs-29" on emacs-devel,
starting 07 June.

In modus-themes the issue occurs in code such as this:

(defface modus-themes-special-cold nil
  "Combines the 'special cold' background and foreground values.
This is intended for cases when a neutral gray background is not
suitable and where a combination of more saturated colors would
not be appropriate.

The actual styling of the face is done by `modus-themes-faces'."
  :group 'modus-themes-faces)

Here, 'special cold' is flagged as a problem.

Possible fixes:

  "Combines the \"special cold\" background and foreground values.

  "Combines the \\='special cold\\=' background and foreground values.

  "Combines the `special cold' background and foreground values.

The correct fix depends on intent. I think in most cases modus-themes
should use the first or second form -- the last approach seems to be for
syntatically meaningful lisp constructs that the help system highlights
specially (functions, variables, key bindings, etc.).

See also (info "(elisp) Text Quoting Style").

I'm happy to send a patch, but I'm not sure in these example if "special
cold" is a set of two lisp symbols or or simply an English phrase, so
I'm not sure about the fix.


Compiling file /home/matt/git/modus-themes/modus-themes.el at Mon Jul 18 16:49:25 2022
modus-themes.el:957:2: Warning: custom-declare-face
    `modus-themes-special-cold' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:966:2: Warning: custom-declare-face
    `modus-themes-special-mild' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:975:2: Warning: custom-declare-face
    `modus-themes-special-warm' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:984:2: Warning: custom-declare-face
    `modus-themes-special-calm' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:993:2: Warning: custom-declare-face `modus-themes-diff-added'
    docstring has wrong usage of unescaped single quotes (use \= or different
    quoting)
modus-themes.el:1001:2: Warning: custom-declare-face
    `modus-themes-diff-changed' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:1009:2: Warning: custom-declare-face
    `modus-themes-diff-removed' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
modus-themes.el:1017:2: Warning: custom-declare-face
    `modus-themes-diff-refine-added' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1025:2: Warning: custom-declare-face
    `modus-themes-diff-refine-changed' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1033:2: Warning: custom-declare-face
    `modus-themes-diff-refine-removed' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1041:2: Warning: custom-declare-face
    `modus-themes-diff-focus-added' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1049:2: Warning: custom-declare-face
    `modus-themes-diff-focus-changed' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1057:2: Warning: custom-declare-face
    `modus-themes-diff-focus-removed' docstring has wrong usage of unescaped
    single quotes (use \= or different quoting)
modus-themes.el:1697:2: Warning: custom-declare-variable
    `modus-themes-org-agenda' docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)

In modus-themes--paren:
modus-themes.el:3128:2: Warning: docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)

In modus-themes--agenda-habit:
modus-themes.el:3396:2: Warning: docstring has wrong usage of unescaped single
    quotes (use \= or different quoting)
Details
Message ID
<87mtd5zmhe.fsf@protesilaos.com>
In-Reply-To
<87bktlvgyy.fsf@rfc20.org> (view parent)
DKIM signature
pass
Download raw message
> From: Matt Armstrong <matt@rfc20.org>
> Date: Mon, 18 Jul 2022 21:55:49 -0700

Hello Matt,

> I noticed that a recent Emacs master version issues compilation warnings
> for modus-themes.el. These become visible with nativcomp builds, so it
> would be nice to address them. The warning is new and was added to Emacs
> in this commit:
>
>> commit 2701cd59b521989530a7eb7489540c64177e0f69
>> Author: Lars Ingebrigtsen <larsi@gnus.org>
>> Date:   Tue May 24 18:48:39 2022 +0200
>>
>>    Make byte compilation warn about wrong quoting in doc strings

You are right and thanks for starting this discussion!

I have noticed it as well and am not happy with those warnings.  There
should be an option or some way to placate the compiler without
introducing syntax that isn't human-friendly.  Stuff like \\=' is not
nice for those who read doc strings directly in the source instead of
the Help buffer (I do it all the time).  The reason it is not nice is
because there are a few of them and the reader needs to be remember what
each one signifies.

This is why, by the way, in some doc strings where there are code
samples, I use the 'quote' keyword: it evaluates even if someone does it
from inside the doc string (and experienced users know how to replace it
with the ').

> The warning is new, but the issue is an old one. See the thread "How to
> disable warnings about single quotes in emacs-29" on emacs-devel,
> starting 07 June.

Just re-read the thread.  Basically these are here to stay.

> I'm happy to send a patch, but I'm not sure in these example if "special
> cold" is a set of two lisp symbols or or simply an English phrase, so
> I'm not sure about the fix.

Thank you!  I still prefer not to use such markup and would rather
remove the quotes altogether because they are not significant.

I attach a patch with my proposed changes.

What do you think?

All the best,
Protesilaos (or simply "Prot")

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2v8rroa0z.fsf@me.com>
In-Reply-To
<87mtd5zmhe.fsf@protesilaos.com> (view parent)
DKIM signature
pass
Download raw message
Protesilaos Stavrou <info@protesilaos.com> writes:

+  "Combines yellow colors for the focused changed state in.

In ... diffs?

Rudy
-- 
"It is no paradox to say that in our most theoretical moods we may be
nearest to our most practical applications."
-- Alfred North Whitehead, 1861-1947

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia
Details
Message ID
<8735ev603f.fsf@protesilaos.com>
In-Reply-To
<m2v8rroa0z.fsf@me.com> (view parent)
DKIM signature
pass
Download raw message
> From: Rudolf Adamkovič <salutis@me.com>
> Date: Wed, 20 Jul 2022 21:32:12 +0200
>
> +  "Combines yellow colors for the focused changed state in.
>
> In ... diffs?

Good catch!  Just pushed an update.  Thank you!

By the way, I did merge this patch earlier.  Please let me know if it is
okay.

-- 
Protesilaos Stavrou
https://protesilaos.com
Details
Message ID
<m2h72vsnc1.fsf@me.com>
In-Reply-To
<8735ev603f.fsf@protesilaos.com> (view parent)
DKIM signature
pass
Download raw message
Protesilaos Stavrou <info@protesilaos.com> writes:

> By the way, I did merge this patch earlier.  Please let me know if it
> is okay.

Just checked; looking great!

Rudy
-- 
"It is no paradox to say that in our most theoretical moods we may be
nearest to our most practical applications."
-- Alfred North Whitehead, 1861-1947

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia
Reply to thread Export thread (mbox)