[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: Sat, 11 Jun 2022 22:36:14 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.10.0

Hi Branden,

On 6/11/22 14:50, G. Branden Robinson wrote:
I've seen stuff like this trip it.

\&.de foo
\&.  ie 1 bar
\&.  el   baz

The indentation after the control characters prompts the complaint.  But
that is, strictly, correct, because inter-sentence space _is_ applied
even when filling is disabled, as is the case in man(7) EX/EE regions.
So if people change the supplementary inter-sentence space amount, the
indentation will become incorrect, or at least not what was intended.
More on this below.

Interesting; didn't know that. Might need to take care in some example that I wrote not so long ago.

5.1.10 Input Conventions


    * Use '\&' after '!', '?', and '.' if they are followed by space,
      tab, or newline characters and don't end a sentence.

That's why I said that I didn't consider "foo. Bar" quite correct. I remember this advice (even if I don't follow it), and so it would be correct to warn, I think. But maybe this is just good style, and not a must in roff. If so, I understand your position.

    * In filled text lines, use '\&' before '.' and ''' if they are
      preceded by space, so that reflowing the input doesn't turn them
      into control lines.

Perhaps amid all the argument over what to formally name the `\&` escape
sequence, we risk losing sight of its tremendous utility in workaday
roff documents.

(Kind of a shame that Texinfo renders a quoted apostrophe as "'''", but
but that's not a windmill I want to tilt at.)

As far as I know, that breaks the ability of groff(1) to produce the
double space;

It's bad style.  I wouldn't say anything gets "broken"; not all periods
_should_ have inter-sentence space after them.  Further, by making
sentence-ending detection reliable, we better accommodate the people who
want the amount of supplementary inter-sentence space to be zero (and
then eventually to change their minds and come over to the other side of
the Force. ;-)).

Okay, I see that the existing warnings relate to broken input. This is more like a good style warning. Compilers have both, putting them in -Wall, -Wextra, -Weverything, depending on if code is broken, or if it's just a style thing or something suspicious. But all are warnings. Maybe putting it in -ww (-Weverything) and not in -wall (-Wall) would be a good thing, but you'll know better.

I'm supportive of adding detection of within-line sentence breaks
because it is _really_ hard to reliably detect them with anything less
powerful than a roff interpreter.  Regexes are not up to the task.
People can change the control and escape characters.  Strings can be
interpolated at sentence endings.  groff further allows you to define
your own special characters, redefine exiting ones, and for any
character, change the attributes that determine whether it terminates a
sentence, cancels sentence termination, or is transparent to same.

If you or anyone else is tempted to interpret the construction of a
warning category for this purpose as a derogation of bad style, then I
would much prefer to realize the feature in a different way, which will
probably be heavier to implement (and take longer).  We're already
nearly out of option letters for groff(1), so maybe I would need to add
a writable register to enable the diagnostic.  (This could still be
accessed via the command like thanks to the '-r' option.)

Maybe that's not a bad idea, since people might want to turn this
diagnostic on and off at a finer-grained level than an entire formatter
run.  In that respect it resembles the notional 'backtrace' register
that I discussed with Ingo a while back.[1]

I'd enable it [the warning? --GBR] for everyone.  Why not?

Because as I said above, it's not presumptively invalid to write roff
input as I have written most of this email.  That is one of roff's
virtues.  You can start out by writing everyday English prose as it was
taught in schoolroom typewriting or computer class[2] and progressively
supplement it with higher-precision information and formatting detail.

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

Not correctly.  If I write

The quick brown fox jumps over the lazy dog.\&  Hello, world!

then end-of-sentence detection is defeated just as our documentation
says it will be.  That means that people who change the supplementary
inter-sentence space amount won't get what they want.

Exactly; I meant that if people want to silence the warning in a specific place (because it's not a sentence ending; but just a dot), they should use \&. But if it's really a sentence ending, it should use a newline (if the warning is enabled, which means that the code base follows the semantic newlines rules); otherwise, don't enable the warning (or don't enable absolutely all warnings, which may add new warnings as this one).



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]