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/
