Re: Warn on semantic newlines

[G. Branden Robinson]

Hi Alex!

At 2022-06-10T11:52:30+0200, Alejandro Colomar wrote:
> As far as I know, there's currently no tool that warns on "foo. bar"
> in filled test.  Not `mandoc -Tlint`, and not `groff -ww`, and not
> `groff -rCHECKSTYLE=999`.  I know that CHECKSTYLE is not designed in a
> way that could catch this easily,

It's worse than a matter of design.  Being in the roff language, the
"CHECKSTYLE" feature of groff man(7) simply does not have access to the
relevant bit of parser state that is required to emit such a warning.

> but maybe -ww or -Tlint could.  Do you think you could add some
> semantic newlines warnings so that writers could realize by themselves
> that their text could be improved?

For groff, at least, the fundamental change is straightforward.  I can
made the troff(1) command do it with a 1-line patch.

diff --git a/src/roff/troff/env.cpp b/src/roff/troff/env.cpp
index d6a9e982d..d3f80a205 100644
--- a/src/roff/troff/env.cpp
+++ b/src/roff/troff/env.cpp
@@ -472,6 +472,7 @@ void environment::space(hunits space_width, hunits 
sentence_space_width)
       && node_list_ends_sentence(p->next) == 1) {
     hunits xx = translate_space_to_dummy ? H0 : sentence_space_width;
     if (p->merge_space(xx, space_width, sentence_space_width)) {
+      debug("end of sentence detected in input line");
       *tp += xx;
       return;
     }

This is not production-ready.  Wording for the diagnostic needs to be
hammered on to make it clear that a within-input line sentence ending
has been detected.  A warning category needs to have a name chosen and
support written.  Documentation of this feature needs to be added.

However, initial results are promising.  All I had to do was type "make"
and within-tree documents were re-generated, and this diagnostic sprung
up in places I expected (mom examples, meintro.me, msboxes.ms, some man
pages I have not deeply revised) and a few places I didn't.

I don't want to make any commitments about when or how fast this will
happen, but it seems practicable.  I'm still reeling from the last bike
shed discussion; I'm curious to see if a new one arises.

I _will_ commit now to not turning this warning on by default.  Sentence
endings internal to a line are not incorrect roff practice.  They're
merely easy to screw up (and they make diff-based maintenance work
uglier than it needs to be).

> The tool could have a secondary warning, not so important, for "foo,
> bar".

This would be a deeper, more intrusive change and unlike the foregoing I
have no clear idea how to implement it.  A comma isn't special to the
formatter; it's not a sentence-ending character, nor is it transparent
to sentence endings.  Barring hyphenation considerations, the formatter
treats it the same as "a", "R", or "#".  (If you give "#" a hyphenation
code and pattern files using it, it too can behave like a letter.)

> Also, as far as I know, neither of -ww nor -Tlint have something
> equivalent to -Wno-switch (or -Wno-error=switch),

No, that's not correct.  GNU troff has supported a '-W' flag to disable
warnings of the type given in the argument since 1991 or earlier.  It
goes all the way back to day one of our Git history.

If I implement the thing above, then the Make rules for the (non-man(7))
documents that don't use semantic newlines will need their command
recipes updated to say "-ww -Wsentence" or whatever the new category
gets called.

*BSD Make's commitment to suffix rules in preference to all other ways
to get a target made and refusal to countenance "$<" in target rules
throw caltrops in our path again here, and will force a policy of
enabling or disabling this warning for all documents in our tree using a
certain macro package.

The path of least pain for groff's own documents is to be determined.

Regards,
Branden

signature.asc
Description: PGP signature