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
