Re: [RFC v1] perf_event_open.2: srcfix + ffix

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

Hi Michael,

On 11/13/20 10:21 AM, Michael Kerrisk (man-pages) wrote:
[...]
> 
>> @@ -1800,12 +1854,17 @@ by new.
>>  In overwrite mode, it might not be possible to infer where the
>>  new data began, and it is the consumer's job to disable
>>  measurement while reading to avoid possible data races.
>> -.IP
>> +.PP
>>  The
>> -.IR aux_head " and " aux_tail
>> +.I aux_head
>> +and
>> +.I aux_tail
>>  ring buffer pointers have the same behavior and ordering
>>  rules as the previous described
>> -.IR data_head " and " data_tail .
>> +.I data_head
>> +and
>> +.IR data_tail .
>> +.RE
>>  .PP
>>  The following 2^n ring-buffer pages have the layout described below.
>>  .PP
>> @@ -1845,15 +1904,15 @@ the fields with shorter descriptions are presented first.
>>  This indicates the size of the record.
>>  .TP
>>  .I misc
>> +.RS
>>  The
>>  .I misc
>>  field contains additional information about the sample.
> 
> This renders as:
> 
>        size   This indicates the size of the record.
> 
>        misc
>               The  misc  field  contains additional information about the
>               sample.
> 
>               The CPU mode can be determined from this value  by  masking
>               with  PERF_RECORD_MISC_CPUMODE_MASK  and looking for one of
>               the following (note these are not bit masks, only  one  can
>               be set at a time):
> 
> This is anomalous. We have a newline after "misc", but not after "size",
> because of the proposal that we add ".RS/.RE" only in .TP blocks
> with multiple paragraphs.

Yes, that's a bit inconsistent...

> 
> Whats the alternative? I guess we could *always* use .RS/.RE even inside
> .TP blocks that have only one paragraph, but:
> 
> * That's even more markup
> * We end up with even more white space in the rendered output.
> * We almost certainly *don't* want to do this for .TP lists
>   that consist of multiple items where each list item is a 
>   rendered paragraph that is juust a line or two. [1]

Right.

> 
> [...]
> 
> At this point, I feel we are devoting a lot of energy to solving a
> problem that has no really good solution. The status quo is not ideal,
> but so far I'm not convinced that there's any compellingly better
> alternative. And moving to one of those alternatives will require
> changes in a lot of pages. I'm in favor of staying with the status quo.

Agreed.

> 
> Thanks,
> 
> Michael
> 
> [1]
> I mean, I think this:
> 
> [[
> HEAD   item text
> 
> HEAD   item text
> 
> HEAD   item text
> ]]
> 
> is preferable to this:
> 
> [[
> HEAD
>        item text
> 
> HEAD
>        item text
> 
> HEAD
>        item text
> 
> HEAD
>        item text
> 
> ]]

Completely agree.


Cheers,

Alex