Re: man(7): .TP: Change minimum distance between tag and paragraph from 1 to 2 (subjective)

[Alejandro Colomar]

Hi Branden!

On 11/16/22 16:54, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2022-11-15T20:53:28+0100, Alejandro Colomar wrote:
> > I had this discussion today:
> >
> > Tagged paragraphs leave a minimum of a single space betweeen the tag
> > and the paragraph.  In some cases, where the tag can be continuated in
> > the same line by the paragraph as a sentence, it feels a bit
> > confusing, and feels like there's a missing line break.
> >
> > 0123   foo bar baz
> >
> > 01234  foo bar baz
> >
> > 012345 foo bar baz
> >
> > 0123456
> >         foo bar baz
>
> That's a fair observation.
>
> Since you CCed Doug, I will note that groff's behavior is largely
> consistent with that of Version 7 Unix man(7).  Both implementations use
> a fixed indentation for the paragraph.  Version 7 used an indentation of
> 5n; groff uses 7n.  Both implementations break the line after the tag if
> it is longer than the indentation amount minus 1n.  This effectively
> means a minimum "tag separation" of 1n.

Yeah, I guessed this comes from the times of Doug (or maybe older?), which is 
why I CCed him.  Especially since he also had a look at my patches for the man 
pages about lists :)

I guess that Version 7 having an indentation of 5 made it a bit more reasonable 
to use 1n, since otherwise most tags would add a line break.  However, I still 
prefer 2n even with 5n of indent.  It avoids confusion in some corner cases.

> I will illustrate, using groff 1.22.4, and blank output lines elided.

[... tests elided ...]

> So--parameterization of the indentation amount aside--while groff's
> behavior is faithful to that of Unix troff, let us further consider the
> issue.
>
> > I've had this feeling myself in the past, and in fact, I designed the
> > use of lists in the Linux man-pages to avoid that as much as possible,
> > by leaving always 2 spaces betweed a bullet list and the text[1].
>
> I can understand why this is desirable.  I'm "used to" the existing
> breaking threshold but cannot articulate a strong defense of it.

I'm guessing its defense was having a small indentation of 5n back in the days. 
But maybe it's just something without proper thought behind.  Any of those seems 
quite reasonable to me.

> You could get what you want today by specifying an argument to each `TP`
> macro call (strictly, the first of each group of related `TP` calls),
> but (1) that would be incredibly tedious for a corpus as huge as the
> Linux man-pages project's; and (2) I think we should encourage people to
> put _less_ presentational and measurement-related content in their man
> pages, not more.

Yeah, let's discard this one please :)

> > I suggest a breaking change to groff_man(7), where the minimum
> > (default) separation between the tag and the paragraph is 2.  I also
> > suggest adding a register (or I couldn't find it) to tweak that
> > amount.
>
> There actually is a register for this, but it is not part of groff
> man(7)'s documented interface, nor is anyone encouraged to use it.  It
> is in the package's (conventionally) private name space.

Hmm, then I suggest 2 changes:

(1)  Make that register public and document it; maybe with a shorter name, as is 
tradition, although the current name makes sense to me and is self-documenting.

(2)  Change its default value to be 2n.

You may have noticed the 2n after the bullet/tag/whatever.  ;)

> Here's the relevant code from groff Git HEAD.

[... groff_man(7) internals ...]

> This `an-tag-separation` register is set every time `TH` is called, so
> overriding it is not _quite_ as easy as setting the supported rendering
> parameter options like `SN` or `HF`.
>
> But you can still do it.
>
> Append to the `TH` macro to redefine the register.  This will be
> reliable because nothing in `TH` will call the macro that uses
> `an-tag-separation`.  Put the following in your man.local file (or a
> local macro file that you manually load, as I seem to recall is
> happening with the hack we crafted for lethalizing style warnings).
>
> .am TH
> .  nr an-tag-separation 2n
> ..

Thanks.

> > Does this make sense to you?  It's a breaking change, but it's just
> > cosmetic.  I hope people won't scream too much about it.
>
> I'd like you try out the foregoing first.

Done.  It works.

>  I am not fundamentally
> opposed to either (1) exposing a proper interface register for this nor
> (2) changing the default tag separation to 2n.

I'd propose both, and in that order.

> The latter might even, arguably, be more congruent with a separation
> that mdoc(7) does when setting lists.  It always seems to want to put 2n
> of space between a list item's "tag" and its...remainder.  (Has any any
> proper nomenclature has been developed for that?)

'Paragraph'?  If it's a single line, then 'line' can work.  From the .It macro 
name, I guess 'item' was maybe in the mind of whoever invented the macro?

> $ cat EXPERIMENTS/list-item.doc

[...]

> .Bl -tag -width ".Dq\ man page" -offset indent -compact
> .It Li ".Dq man page"

[...]

>               .Dq man page  → “man page”

[...]

> (I used mdoc(7) from groff Git HEAD to avoid distractions from unrelated
> bugs in the 1.22.4 version.)
>
> I am curious to know what other people think, and to see if we can build
> some sort of consensus here.

Sure!

> Regards,
> Branden



On 11/16/22 17:10, G. Branden Robinson wrote:
> Hi Alex,
>
> Quick self-correction here.
>
> The name of the relevant register in groff 1.22.4 (and earlier, going
> back many years) is `an-tag-sep`.  I had forgotten that I had renamed it
> in the past 4 years.
>
> So here's an updated "patch".
>
> .am TH
> .  nr an-tag-sep 2n
> ..

I have groff 1.23, so I'm fine with the other patch :)

>
> Regards,
> Branden

Cheers,

Alex


--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature