Sureness Threshold Messages Unclear

[localjo]

I had a hard time figuring out what the sureness threshold messages meant until I read the code. The possible messages are;

Definitely hard to read sentence
Very hard to read sentence
Quite hard to read sentence

What those really mean is;

6/7 formulas agree that the sentence is hard to read
5/7 formulas agree that the sentence is hard to read
4/7 formulas agree that the sentence is hard to read

To make the messaging more clear, I propose that we add a ruleId and improve the wording of the message. Maybe we could target an end result that looks something like this;

7:1-7:265  error      Hard to read sentence, 85% consensus        difficult-sentence-85
8:1-8:165  warning    Hard to read sentence, 70% consensus        difficult-sentence-70
9:1-9:65   warning    Hard to read sentence,  60% consensus       difficult-sentence-60

Open to other suggestions. The "error"/"warning" level is another question altogether, but I put it in my example just to illustrate more how it could be used.

[localjo]

The added benefit of giving each threshold a different ruleId would be that the messages could be turned off/on or given a different error/warning level based on which threshold they hit.

[localjo]

To be consistent with the way things work currently, here's another potential target:

7:1-7:265  warning    Hard to read sentence, Threshold 6/7        hard-to-read-6
8:1-8:165  warning    Hard to read sentence, Threshold 5/7        hard-to-read-5
9:1-9:65   warning    Hard to read sentence, Threshold 4/7        hard-to-read-4

[wooorm]

OK, thinking out loud here, these are my initial feels:

• 👍 Adding a “sureness” to messages;
• 👍 Modifying the message, that may indeed make things easier to grasp;
• 😐 Things with errors is that they cause everything to stop: no further plugins are run, no further messages are triggered for that file. Still, I am OK with adding an option to set a threshold which, when messages above that threshold are found, stops processing.
• 👎 Adding rule-id’s per sureness, that just makes them harder to ignore. Say you change the configured threshold, that means you have to change all message-control comments as well! And that makes the needed logic harder, as you presumable want <!--some-name ignore hard-to-read-4--> to turn off -5, -6, and -7 as well? It’s much easier to have <!--some-name ignore hard-to-read--> turn off the next paragraph.

I also think that your initial issues sort-of poses an XY-problem: the messages are unclear, but instead of just changing the messages, you propose adding a ruleId, which will make it possible to write code which does that. I think changing the messages / adding sureness accomplishes this as well!?

[localjo]

Makes sense. Especially about the ruleId. I didn't think about the message-control scenario. Maybe we can just add one ruleId for all of them? retext-readability or just readability?

For the errors, I'm just thinking it would be nice to have different severity levels for the messages, not that it would be a thread-stopping error. I've currently got a workaround in quality-docs that does this, and it works nicely. But that's probably an extensive change across lots of plugins and really it's a different issue anyway.

I'm wrapping up for the day, but I think tomorrow I'll create a PR that does the following;

• [x] Changes the description for readability messages to say "Hard to read, threshold x/7"
• [x] Adds a ruleId of retext-readability to readability messages

How's that sound?

[wooorm]

Good!

1. 👍
2. 👍 - Same as source, seems logical for plugins with just one rule (PS ruleId can be passed as a third argument to warn())

And related to severities: https://github.com/wooorm/remark-lint/issues/65.