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

Alejandro Colomar
2020-11-13T10:26:40Z

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