Re: Format inline code

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

Hello Alex, Branden,

On 11/13/20 9:28 AM, G. Branden Robinson wrote:
> 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 ?

But in the "-branden" version I see

[[
.RS 6n
]]

If I understand correctly, then that number is calculated based on the
".IP * 2" that precedes it. That doesn't seem good (since, maybe at 
some point, one might want to change the .IP yo say ".IP  1) 3",
and then one has to fix the .RS lines. Am I missing something?

Thanks,

Michael


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