Re: Warn on semantic newlines

[Alejandro Colomar]

Hi Branden,

On 6/11/22 14:50, G. Branden Robinson wrote:
> I've seen stuff like this trip it.
>
> .EX
> \&.de foo
> \&.  ie 1 bar
> \&.  el   baz
> \&..
> .EE
>
> 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).


Regards,

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