[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Warn on semantic newlines

From: Alejandro Colomar
Subject: Re: Warn on semantic newlines
Date: Fri, 10 Jun 2022 17:47:40 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.10.0

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 
        && 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;

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

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.




Alejandro Colomar
Linux man-pages comaintainer;

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]