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

[G. Branden Robinson]

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.

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

$ nroff -man EXPERIMENTS/TP-indent.man | sed '/^$/d'
foo(1)                      General Commands Manual                     foo(1)
Name
       foo - frobnicate a bar
Description
       Foobar.
       1      This is my tagged paragraph.
       12     This is my tagged paragraph.
       123    This is my tagged paragraph.
       1234   This is my tagged paragraph.
       12345  This is my tagged paragraph.
       123456 This is my tagged paragraph.
       1234567
              This is my tagged paragraph.
groff test suite                  2022‐11‐16                            foo(1)

$ nroff -M./HISTORY-MAN/1979-01-v7 -manv7 EXPERIMENTS/TP-indent.man | sed 
'/^$/d'
foo(1)               UNIX Programmer’s Manual              foo(1)
Name
     foo − frobnicate a bar
Description
     Foobar.
     1    This is my tagged paragraph.
     12   This is my tagged paragraph.
     123  This is my tagged paragraph.
     1234 This is my tagged paragraph.
     12345
          This is my tagged paragraph.
     123456
          This is my tagged paragraph.
     1234567
          This is my tagged paragraph.
Printed 11/16/122           2022‐11‐16                          1

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.

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.

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

Here's the relevant code from groff Git HEAD.

[...]
.\" Begin man page.
.\" .TH topic section[ extra1[ extra2[ extra3]]]
.de1 TH
[...]
.  nr an-tag-separation 1n
[...]
..
[...]
.\" Output the tag of a tagged paragraph, or of an indented paragraph
.\" (IP) that has a tag.  Whether we break depends on the tag width.
.de an-write-paragraph-tag
[...]
.  \" Does the tag fit within the paragraph indentation?
.  nr an-tag-fits \
     (\\n[dl] + \\n[an-tag-separation] <= \\n[an-prevailing-indent])
.  if \\n[an-tag-fits] .DEVTAG-COL 1
.  an-div
.  if \\n[an-tag-fits] .sp -1v
.  ev
.  in (\\n[an-margin]u + \\n[an-prevailing-indent]u)
.  if \\n[an-tag-fits] .DEVTAG-COL 2
.  rr an-tag-fits
..
[...]

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

> 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.  I am not fundamentally
opposed to either (1) exposing a proper interface register for this nor
(2) changing the default tag separation to 2n.

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?)

$ cat EXPERIMENTS/list-item.doc
.Dd 2022-11-16
.Dt foo 1
.Os
.Sh Name
.Nm foo
.Nd frobnicate a bar
.Sh Description
.Bl -tag -width ".Dq\ man page" -offset indent -compact
.It Li ".Dq man page"
\[->]
.Dq man page
.El
$ ./build/test-groff -Tutf8 -mdoc EXPERIMENTS/list-item.doc
foo(1)                      General Commands Manual                     foo(1)

Name
       foo — frobnicate a bar

Description
             .Dq man page  → “man page”

GNU                               2022‐11‐16                            foo(1)

(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.

Regards,
Branden

signature.asc
Description: PGP signature