Re: groff man(7) `B` macro behavior with `\c`, and input traps

[G. Branden Robinson]

Hi Ingo!

At 2022-06-06T09:18:01+0200, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Sun, Jun 05, 2022 at 06:08:46PM -0500:
> > .\" Set arguments (or next input line if none) in bold style.
> > .de1 B
> > .  itc 1 an-input-trap
> 
> Ouch: .itc!

;-)

> > .B
> > .
> > foo
> > 
> > Should "foo" be in bold?
> 
> Yes, groff and mandoc output agree.
> 
> [...]
> > So, what kind of line produces formatted output?  Well, text lines.
> 
> And to allude to an another conversation we are currently having,
> including those that contain nothing but "\&", but *not* those
> that are completely empty, which would make you think that "\&"
> is a "zero-width non-breaking space" or a "zero-width non-printing
> character" rather than merely an "input break".  But that should
> really be decided in another thread.

Watching the threads and doing experiments over the past few days, I'm
_personally_ finding that it reduces my cognitive dissonance the most to
think of \& as a "dummy character [escape sequence]".

I'm not saying that's what I'll wind up putting in our documentation,
but for now that is the term that has attained a local minimum on the
intensity plot of the buzzing sound inside my head.

> Yes, both print CINCOMPAC in bold in both groff and mandoc,
> even though mandoc fails to document that.

*nod*

It sounds like the implementations are in good agreement until and
unless \c gets involved.

> Yes, indeed groff and mandoc format this the same way, ending the .TP
> next line scope right before "This option".  In that sense, i
> understand why .TP now uses .itc rather than .it.

My own understanding was certainly poorer before yesterday, prior to
checking my assumptions sufficiently to write that mail.

> [...]
> > And that's the story of why groff and Heirloom Doctools nroff put
> > "bar" in bold.
> 
> So since .B uses .itc, and that appears to match Heirloom behaviour
> according to your research, it might be unwise to change that now.

I was a little uneasy about this point yesterday and a fresh experiment
today just made it worse.

Yesterday, for Heirloom, I used the ultra-minimal example you supplied.

Today, I added a `TH` call to the top of the document (because groff
man(7) insists on its presence), and I witnessed an unhappy thing.

Heirloom rendered the page footer in boldface too.  That's obviously a
bug, and it shook my confidence in its correctness.

Here's the input exhibit.

.TH foo 1
.B foo\c
bar

A further experiment is even more dispiriting.

.TH foo 1
.B foo\c
bar
baz

Now, in Heirloom, "baz" _and_ the page footer are in bold, and that just
cannot be correct.  In fact boldface seems to stay on until a
paragraphing or sectioning macro occurs.

Worse, Heirloom doesn't seem to honor the next-line input-trap form of
`SH`.  Yikes.[1]

(In groff 1.22.4 and Git, "foobar" is in bold; "baz" and the page footer
are not.  If you change `B`'s `itc` to `it`, "bar" becomes roman too.)

> Still, i wonder whether choosing that behaviour was a good decision.
> From the user perspective, this feel asymmetric, in particular for
> users who dislike traps and don't want to think about them:
> 
>   .BI command arg\c
>   text
> 
> sets "text" in Roman font but
> 
>   .I arg\c
>   text
> 
> sets "text" in italics?  Isn't that really surprising from the
> user perspective?  No argument about .TP, but wouldn't it have
> been better for .B and .I to use .it rather than .itc for symmetry
> with .BI?

That is indeed possible.  _Some_ asymmetry is inescapably
entrenched--you can give B, I, SM, SB, SS, and SH no arguments and they
_will_ handle the next written or drawn output produced by an input line
as if it were an argument.

But this is not true of the font alternation macros.  If you give them
zero arguments, they do nothing.  (Except, in groff Git HEAD man(7), if
the `CHECKSTYLE` register is set, to warn you of your error.)

But to the point of whether these input-trap-setting macros should go
back to `it`, _except_ for TP...I'm suddenly quite open to that.

It is disappointing that I couldn't get any useful information out of
Unix V7 nroff.  But I tried only the default device (Teletype Model 37),
and maybe others are more performant.  That in turn may require that I
temporarily learn the escape sequences for ancient terminals like the
"GE TermiNet 300", "DASI-300S", or "Diablo Hyperterm", which I've never
even heard of in any other context.  Some days my beard is not so gray.

And that will be possible only if adequate documentation for those
devices survives.

(Even then we're not necessarily beaten; John Gardner's JavaScript C/A/T
input interpreter is available [so it is possible to evaluate Unix V7
troff output] but I've had the devil's own time getting it to work
locally on my system.  I've since updated my OS, though, so it may be
worth giving it another try.)

I note that Doug is here, a fact for which I'm grateful, but before
appealing to him as an oracle I'd like to see what I can turn up with a
bit more research.

> For now, i have added this entry to
> https://cvsweb.bsd.lv/~checkout~/mandoc/TODO?rev=HEAD :
> 
>   - the man(7) single-font macros (e.g. .B) use .itc,
>     so ".B foo\c" followed by "bar" prints "bar" in bold
>     gbranden@ Sun, 5 Jun 2022 18:08:46 -0500

Okay.  "Watch this space", as the saying goes.

One thing is for sure: once we've determined what the correct behavior
is, whether through discovery or decree, I'm writing regression tests
for it.  This kind of underspecification is frustrating.

Regards,
Branden

[1] There _is_ an input trap in Heirloom Doctools man(7)'s `SH`
    implementation, but it's deep in conditional logic having to do with
    defining macros for HP-UX compatibility; I guess they're drafting
    `SH` into service as some kind of initializer for the package.

https://github.com/n-t-roff/heirloom-doctools/blob/master/troff/troff.d/tmac.d/an.in#L195

signature.asc
Description: PGP signature