Re: Warn on semantic newlines

[Alejandro Colomar]

On 6/10/22 14:16, G. Branden Robinson wrote:
> 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;
>       }

Looks great!

> 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 hope we see it in 1.23 :)

When you add it, I'll test it in the Linux man-pages.

> 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).

Is the following correct?  "foo. Bar"
As far as I know, that breaks the ability of groff(1) to produce the 
double space; so I'd say something's wrong there?  It's not only a 
matter of maintainability, is it?

> > 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.)
Yeah, just have this floating around in your mind, and if you find a 
solution some day that's great; otherwise, it looks like an impossible 
thing.  Maybe mandoc(1) has it different?

> 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.

Ahh, right.  It was maybe with mandoc(1) that I had issues...

> 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.

Hmm, no?

       -wname Enable warning name.  Available warnings are
              described  in  section "Warnings" below.  To
              enable most useful warnings use -w all.   To
              enable  absolutely all warnings use -w w in-
              stead.  Multiple -w options are allowed.

-ww enables absolutely all warnings.  This is part of "absolutely all" 
warnings, so if someone wanted absolutely all warnings, they should get 
this one too.  If not, they better read absolutely twice before using it.

-wall enables most useful warnings.  This is a "most useful" warning, 
since most of the manual pages (if not all) should follow this.

If someone just wants a specific set of warnings, and that the build 
doesn't break because a warning was added, I'd say they should use a 
specific set of warnings, instead of a wildcard.  The same happens with 
gcc(1)'s warnings.  Every release, builds break, for a good reason. 
Solution: fix the code.

> *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.

I'd enable it for everyone.  Why not?

BTW, I guess the "no-op escape" \& can be used to silence this warning, 
right?

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

Cheers,

Alex


--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

OpenPGP_signature
Description: OpenPGP digital signature