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 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. 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. 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... :) Regards, Branden
Attachment:
signature.asc
Description: PGP signature
