[CC list trimmed]

At 2020-08-04T14:52:05+0200, Michael Kerrisk (man-pages) wrote:
> > > >         There is already inconsistency here: there are may
> > > >         top-level lists using ".IP *" in prctl.2, and plenty of
> > > >         places where the default indentation is used.
> > >
> > > I must admit that I'm in the process of rethinking bulleted lists,
> > > and I have not come to a conclusion (and that's why nothing is
> > > said in man-pages(7), and also why there is currently
> > > inconsistency).
> > >
> > > Using .IP with the default indent (8n) results in a very deep
> > > indent between the glyph and the text, so it's not my preference.

Technically the indentation _amount_ is 7n in groff for nroff output
(7.2n for troff).  So with repeated indents you get text on columns 8,
15, 22, and so on (where the leftmost character cell is numbered 1).

> >
> > Is it worth trying to change the default indent in the macro
> > package, or will that just upset other people?
> 
> I imagine it would break other stuff.

In well-written man pages, I don't think it would, but it's still not
worth doing within man pages themselves.  However, a solution does exist
that people can apply to their own environments, if their man pager uses
groff as the typesetter (this is likely true of anybody reading this
unless they know they use the mandoc program).

The same indentation value is used for multiple purposes in the groff
implementation of the man macros, the language in which classical man
pages are written.  These purposes are:

	1. The amount a standard paragraph (.PP, .LP, or .P) is indented
	from the left edge of the screen (where the section headings
	defined by .SH are aligned).

	2. The amount a "relative indent" section is inset from the
	existing left margin.  In other words, how much an .RS/.RE
	region lies "inboard" of the surrounding material if you don't
	give .RS an explicit argument.

	3. The amount of space allocated to the tag in a tagged
	paragraph (the macros .TP and .TQ).  (If the tag overruns this
	amount, it gets the output line to itself and the entire
	subsequent paragraph is set indented by this same amount.)

	4. The amount of space by which an indented paragraph (.IP) is
	indented.  (.IP takes an optional tag argument, and is ideal for
	itemized or enumerated lists.)

A nice feature of the above extensive re-use of the same parameter is
that it pushes the man(7) language in the direction of being more
semantic and less presentational.  On the other hand, some people just
don't like the resulting esthetics.

This parameter is a register called "IN".  (There's one exception to
this generality; the indent of a subsection is controlled by the
register SN, and defaults to 3n.)

But rather than customizing each man page to the writer's preference,
which will (and does) lead to an explosion of different conventions
leading to an inconsistent user experience for readers of man pages from
diverse sources, we can give tell the man macro package what we want
this indentation amount to be.

You can edit your man.local file (on my Debian system, it is in
/etc/groff/man.local), and add a line like this (without the leading
tab):

	.nr IN 4n

If you're practiced with the *roff language you can write conditionals
to tune the application of this setting.  Say I only want to change the
IN register only if groff is my typesetter and if I'm rendering the page
to "an nroff device" (a terminal, basically).  I can do this:

	.if \n(.g .if n .nr IN 4n

The first condition is probably slightly contrived because I'd be
surprised if any non-groff typesetter opened /etc/groff/man.local to
read it, but I don't want to come across as unecumenical; there are
users out there of Heirloom Doctools troff, Plan 9 troff, and neatroff.

I'm attaching an example man page to demonstrate the above.  If you use
Colin Watson's man-db you can view it directly with "man -l".  I put the
register tweaking directly at the top of the page to make it easy for
people to experiment but *PLEASE* don't do this in actual man pages.  To
reiterate my earlier point: we want to empower the _reader_ to configure
the indentation in a way that pleases them, not encourage a hundred
different man page writers to subject the rest of the world to their
varied and conflicting preferences.

Regards,
Branden