[PATCH] guix: lint: Improve message in linter warning.

  • Open
  • quality assurance status badge
Details
5 participants
  • Arun Isaac
  • jgart
  • Ludovic Courtès
  • Maxim Cournoyer
  • zimoun
Owner
unassigned
Submitted by
jgart
Severity
normal
J
J
jgart wrote on 12 Nov 2022 16:09
(address . guix-patches@gnu.org)(name . jgart)(address . jgart@dismail.de)
20221112150907.29793-1-jgart@dismail.de
* guix/lint.scm (check-end-of-sentence-space): Improve message.
---
guix/lint.scm | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)

Toggle diff (23 lines)
diff --git a/guix/lint.scm b/guix/lint.scm
index 8e3976171f..37a9539e2c 100644
--- a/guix/lint.scm
+++ b/guix/lint.scm
@@ -14,6 +14,7 @@
;;; Copyright © 2021 Xinglu Chen <public@yoctocell.xyz>
;;; Copyright © 2021, 2022 Maxime Devos <maximedevos@telenet.be>
;;; Copyright © 2021 Brice Waegeneire <brice@waegenei.re>
+;;; Copyright © 2022 jgart <jgart@dismail.de>
;;;
;;; This file is part of GNU Guix.
;;;
@@ -409,7 +410,7 @@ (define (check-end-of-sentence-space description)
(list
(make-warning package
(G_ "sentences in description should be followed ~
-by two spaces; possible infraction~p at ~{~a~^, ~}")
+by two spaces due to issues wth Emacs; possible infraction~p at ~{~a~^, ~}")
(list (length infractions)
infractions)
#:field 'description)))))
--
2.38.1
J
J
jgart wrote on 12 Nov 2022 16:15
Re: bug#59217: Acknowledgement ([PATCH] guix: lint: Improve message in linter warning.)
(address . 59217@debbugs.gnu.org)(name . Arun Isaac)(address . arunisaac@systemreboot.net)
20221112091515.GB30032@dismail.de
On Sat, 12 Nov 2022 15:10:02 +0000 help-debbugs@gnu.org (GNU bug Tracking System) wrote:
Toggle quote (2 lines)
> Thank you for filing a new bug report with debbugs.gnu.org.

Hi Arun,

Not sure if you remember that conversation we had about the linter
warning regarding emacs and having to use two spaces in description
field sentences.

Would you mind recapping the issue so that I can improve this message further.

What I wrote is currently vague:

Why do the sentences in the description field have to be separated by two spaces due to Emacs?

all best,

jgart
L
L
Ludovic Courtès wrote on 19 Nov 2022 19:37
Re: bug#59217: [PATCH] guix: lint: Improve message in linter warning.
(name . jgart)(address . jgart@dismail.de)(address . 59217@debbugs.gnu.org)
87v8na94ed.fsf@gnu.org
Hi,

jgart <jgart@dismail.de> skribis:

Toggle quote (2 lines)
> * guix/lint.scm (check-end-of-sentence-space): Improve message.

[...]

Toggle quote (3 lines)
> -by two spaces; possible infraction~p at ~{~a~^, ~}")
> +by two spaces due to issues wth Emacs; possible infraction~p at ~{~a~^, ~}")

Probably the two-space story needs an explanation, but what about adding
it to the manual, with a cross-ref to the relevant Emacs manual section?

Thanks,
Ludo’.
A
A
Arun Isaac wrote on 22 Nov 2022 21:58
Re: bug#59217: Acknowledgement ([PATCH] guix: lint: Improve message in linter warning.)
87wn7mk8pp.fsf@systemreboot.net
Hi jgart,

Toggle quote (4 lines)
> Not sure if you remember that conversation we had about the linter
> warning regarding emacs and having to use two spaces in description
> field sentences.

Yes, I remember the conversation.

Toggle quote (3 lines)
> Would you mind recapping the issue so that I can improve this message
> further.

My original point was that the linter should not simply complain about
the absence of double spaces but also explain why double spaces are
required. Double spaces are required because Emacs sentence commands
such as M-a and M-e only work when sentences are separated by double
spaces. To be honest, I would consider this an Emacs bug. But, it's
probably impossible to achieve consensus on such a bold claim. ;-)

So, at the very least, the Guix linter should explain why double spaces
are required. As a general rule for all linter messages, contributors
will be happier when the linter explains the rationale for various
messages. Most people don't like doing things without understanding why
they have to do them.

Regards,
Arun
Z
Z
zimoun wrote on 23 Nov 2022 11:13
Re: [bug#59217] Acknowledgement ([PATCH] guix: lint: Improve message in linter warning.)
86mt8iashd.fsf@gmail.com
Hi Arun,

On Tue, 22 Nov 2022 at 20:58, Arun Isaac <arunisaac@systemreboot.net> wrote:

Toggle quote (7 lines)
> My original point was that the linter should not simply complain about
> the absence of double spaces but also explain why double spaces are
> required. Double spaces are required because Emacs sentence commands
> such as M-a and M-e only work when sentences are separated by double
> spaces. To be honest, I would consider this an Emacs bug. But, it's
> probably impossible to achieve consensus on such a bold claim. ;-)

Indeed, it is impossible to achieve consensus since it is probably not
an Emacs bug but an historical inheritance of typographical convention,
see [1,2].



Toggle quote (6 lines)
> So, at the very least, the Guix linter should explain why double spaces
> are required. As a general rule for all linter messages, contributors
> will be happier when the linter explains the rationale for various
> messages. Most people don't like doing things without understanding why
> they have to do them.

Well, maybe a paragraph in the manual under ’(guix) Synopses and
Descriptions’ is a better location for such explanations than the linter
message itself. WDYT?


Cheers,
simon
A
A
Arun Isaac wrote on 23 Nov 2022 13:52
87bkoxbzoc.fsf@systemreboot.net
Toggle quote (4 lines)
> Well, maybe a paragraph in the manual under ’(guix) Synopses and
> Descriptions’ is a better location for such explanations than the linter
> message itself. WDYT?

That sounds good. Detailed explanations do belong in the manual. But,
the linter CLI output should link to the relevant section of the web
manual. That would be better than sending people hunting in the
manual. Many good linters for other programming languages do do this.

Cheers!
M
M
Maxim Cournoyer wrote on 21 Mar 2023 20:50
Re: bug#59217: [PATCH] guix: lint: Improve message in linter warning.
(name . Arun Isaac)(address . arunisaac@systemreboot.net)
87edphnat3.fsf_-_@gmail.com
Hi,

Arun Isaac <arunisaac@systemreboot.net> writes:

Toggle quote (9 lines)
>> Well, maybe a paragraph in the manual under ’(guix) Synopses and
>> Descriptions’ is a better location for such explanations than the linter
>> message itself. WDYT?
>
> That sounds good. Detailed explanations do belong in the manual. But,
> the linter CLI output should link to the relevant section of the web
> manual. That would be better than sending people hunting in the
> manual. Many good linters for other programming languages do do this.

Instead of a bug in Emacs, I'd say it's rather a convention, rooted in
the fact that without the two-spaces trick, how would you reliably
locate the end of a sentence? A period followed by a capital letter
might happen in the middle of a sentence, which makes it ambiguous.
Note that two-spaces also exists as a typographical convention, called
"double sentence spacing". Here's some interesting quote from the
Wikipedia page [0]:

The text-editing environment in Emacs uses a double space following a
period to identify the end of sentences unambiguously; the
double-space convention prevents confusion with periods within
sentences that signify abbreviations. How Emacs recognizes the end of
a sentence is controlled by the settings sentence-end-double-space
and sentence-end.[71]

The Unix typesetter program Troff uses two spaces to mark the end of
a sentence.[72] This allows the typesetter to distinguish sentence
endings from abbreviations and to typeset them differently. Early
versions of Troff,[72] which only typeset in fixed-width fonts, would
automatically add a second space between sentences, which were
detected based on the combination of terminal punctuation and a line
feed.

Personally, I'd prefer not having explanations directly in the output of
Guix lint; it should be terse, as it's involved often and repeatedly.


--
Thanks,
Maxim
J
J
jgart wrote on 22 Mar 2023 22:37
d754c7632bec53604b8ae06c7008194f@dismail.de
Toggle quote (4 lines)
> New users should not be baffled by error messages and should have some
> way of learning more without having to ask on the mailing list or do
> extensive research.

I agree with this. This is esoteric historical knowledge that could benefit from a bit of help by hinting.
M
M
Maxim Cournoyer wrote on 23 Mar 2023 03:52
(name . Arun Isaac)(address . arunisaac@systemreboot.net)
878rfofabh.fsf@gmail.com
Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

Toggle quote (20 lines)
> Hi Maxim,
>
>> Personally, I'd prefer not having explanations directly in the output of
>> Guix lint; it should be terse, as it's involved often and repeatedly.
>
> I see your point. But, perhaps there should at least be a
> link. Something like
>
> /home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
> description should be followed by two spaces; possible infraction at 313
> (see
> https://guix.gnu.org/manual/en/html_node/guix-lint-errors.html#two-spaces
> for details)
>
> Or a lint error code that can be explained in detail in the manual:
>
> /home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
> description should be followed by two spaces; possible infraction at 313
> (#12345)

I think I like the error code more; the link is too verbose to my taste,
and I prefer to stay outside of the browser as much as I can ;-).

It seems error codes that can be documented somewhere else are common
for linters (e.g., pylint). It then also give some way to disable the
lint checks by annotating the source with e.g.

Toggle snippet (3 lines)
;disable #12345

I'm not sure we'd want to do that, but that'd be an option for the
future if we had some documented codes for the checks.

Toggle quote (2 lines)
> Or a --verbose flag that can enable longer explanations.

That's another interesting approach. On the bad side, you'd probably
often run 'guix lint', then realize you needed --verbose, and have to
run it again (and it's slow).

Toggle quote (4 lines)
> New users should not be baffled by error messages and should have some
> way of learning more without having to ask on the mailing list or do
> extensive research.

I agree there's merit to improving the situation!

--
Thanks,
Maxim
A
A
Arun Isaac wrote on 22 Mar 2023 22:22
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
871qlga3ci.fsf@systemreboot.net
Hi Maxim,

Toggle quote (3 lines)
> Personally, I'd prefer not having explanations directly in the output of
> Guix lint; it should be terse, as it's involved often and repeatedly.

I see your point. But, perhaps there should at least be a
link. Something like

/home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
description should be followed by two spaces; possible infraction at 313
(see
for details)

Or a lint error code that can be explained in detail in the manual:

/home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
description should be followed by two spaces; possible infraction at 313
(#12345)

Or a --verbose flag that can enable longer explanations.

New users should not be baffled by error messages and should have some
way of learning more without having to ask on the mailing list or do
extensive research.

Cheers!
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send an email to 59217@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 59217
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch