Re: man-pages.7: Simplify indentation of structure definitions, shell session logs, and so on

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 9/27/20 8:03 AM, G. Branden Robinson wrote:
> At 2020-09-24T10:15:31+0200, Michael Kerrisk (man-pages) wrote:
>> On 9/21/20 4:15 PM, G. Branden Robinson wrote:
> [much snippage]
>>> In my opinion, .in requests are never necessary in idiomatic,
>>> well-written man pages and I'm happy to offer technical advice for
>>> how to achieve the desired result without using them.
>>
>> So, I don't disagree with you. (And as ever, thank you for your
>> detailed input.) The pattern I use above (with ".in +4n/.in" was a
>> hack that I cam up with to get code blocks with a "suitable"
>> indent. Your suggestion of ".RS 4/.RE" (in your patch, which I've
>> quoted inline below), does seem better. I'm not averse to changing
>> things. But, there is a related question. I use a similar hack in
>> the SYNOPSIS of many pages (e.g., chmod.2), to undent a single
>> line:
>>
>> [[
>> .PP
>> .in -4n
>> Feature Test Macro Requirements for glibc (see
>> .BR feature_test_macros (7)):
>> .in
>> .PP
>> ]]
>>
>> Presumably, that could be replaced with ".RS -4/.RE", but is
>> there something even better?
> 
> You're correct; .RS honors a negative indentation argument.  So you
> could do this and I would consider it an improvement because it reduces
> the number of lexemes that man page readers--human and machine
> alike--have to comprehend.

I've done it.

> 
> I noticed something about "Feature Test Macro Requirements for glibc",
> however...
> 
> Because of the negative indent, it's within one en of the indentation of
> a subsection (.SS) heading; in fact it's an exact match on nroff devices
> (terminals).  I'm guessing that wasn't an accident.  You're even already
> title-casing it like a heading.
> 
> If you used .SS, it look much the same but end up in bold.
> 
> Admittedly the parenthetical man page cross-reference fits poorly with a
> subsection heading, in part because the font style change would be
> obscured.  

(Yes, I'm not so keen on that.)

> However, I think that could be moved to the _end_ of the
> synopsis with little loss.  It doesn't take seasoned readers of section
> 2 and 3 man-pages documents long to internalize this knowledge about
> feature_test_macros(7), so repeating it by rote in the current
> pseudo-heading may not be helping much.  Inexperienced readers need to
> read closely anyway, and experienced ones already know this information.

Possibly you are right, but that's a bigger global edit that I 
won't attempt for now.

> I notice that in these feature test macro areas you're making heavy use
> of .ad and .br requests, as well as the deprecated .PD macro to set the
> inter-paragraph spacing to zero.  However, that's probably a digression
> for another thread... :)

I think the words you were looking for are "disgusting hack" :-).
Feel free to start another thread...

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/