At 2020-11-12T22:17:34+0100, Alejandro Colomar wrote: > There are some cases using [.nf/.fi] instead of [.EX/.EE]. > I would replace those by [.EX/.EE]. Yes! I strongly encourage this, and recently finished fixing all of groff's man pages (about 60 of them) to clear the last vestiges of .nf/.fi. > However, I would still do the change [.IP] -> [(.RS + .PP)/.RE], > so almost always you'll have [.PP] surrounding code examples, > and you'll only see [.IP] when it is really needed: > in cases where you use its argument ([.IP * n]). I think this is a good idea, too. As I have tried to explain in groff_man(7)--at some length because this issue bedeviled me a long time--the "relative inset" macros should really be thought of separately from paragraph indentation. In a way it is regrettable that the default indent for paragraphs is different from the increment used for relative insets; if they were different, the distinction would be much more obvious to people. But perhaps not, in the end, much less frustrating. If you'd like to give me some feedback on the subsections "Horizontal and vertical spacing" and the .RS-related item in section "Notes" in groff_man_style(7), I'd appreciate it. https://man7.org/linux/man-pages/man7/groff_man_style.7.html > In those cases, you should also use [.IP] for the code > (see perf_event_open.2:1426): > > [[ > .IP * 2 > If > .B PERF_FORMAT_GROUP > was specified to allow reading all events in a group at once: > .IP > .in +4n > .EX > struct read_format { > u64 nr; /* The number of events */ > u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ > u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ > struct { > u64 value; /* The value of the event */ > u64 id; /* if PERF_FORMAT_ID */ > } values[nr]; > }; > .EE > .in Have you considered changing out this .IP/.in/.EX/.../.EE/.in pattern for .RS/.PP/.EX/.../.EX ? I'm attaching two fake man pages based on the above content, following each approach. The _only_ difference is in the man page footer, to make it easy to see which approach is used. > This way, inline code, and only inline code, will use [.in], > which will help grepping if it is ever needed. Don't .EX and .EE serve just as well for this? I regret to say I'm not as familiar with the man-pages corpus as I should be, so I could be wrong. Regards, Branden
Attachment:
alex.man
Description: Unix manual page
Attachment:
alex-branden.man
Description: Unix manual page
Attachment:
signature.asc
Description: PGP signature
