[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Alejandro Colomar
Subject: Re: man(7): .TP: Change minimum distance between tag and paragraph from 1 to 2 (subjective)
Date: Wed, 16 Nov 2022 17:33:33 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.4.1

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

        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

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

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


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.



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




Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]