Re: Format inline code

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2477 bytes --]

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 #1.2: alex.man --]
[-- Type: application/x-troff-man, Size: 990 bytes --]

[-- Attachment #1.3: alex-branden.man --]
[-- Type: application/x-troff-man, Size: 991 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]