[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
Attachment:
indentation.man
Description: Unix manual page
Attachment:
signature.asc
Description: PGP signature
