Bug#1101124: perf-intel-pt.1: Some remarks about this man page
Package: linux-perf
Version: 6.12.19-1
Severity: minor
Tags: upstream
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:3129: warning [page 28, line 13]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.17-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages linux-perf depends on:
ii libbabeltrace1 1.5.11-4+b2
ii libc6 2.41-6
ii libdebuginfod1t64 0.192-4
ii libdw1t64 0.192-4
ii libelf1t64 0.192-4
ii liblzma5 5.6.4-1
ii libnuma1 2.0.18-1+b1
ii libopencsd1 1.5.5-1
ii libperl5.40 5.40.1-2
ii libpython3.13 3.13.2-2
ii libslang2 2.3.3-5+b2
ii libstdc++6 14.2.0-17
ii libtraceevent1 1:1.8.4-2
ii libunwind8 1.8.1-0.1
ii libzstd1 1.5.7+dfsg-1
ii perl 5.40.1-2
ii python3 3.13.2-2
ii zlib1g 1:1.3.dfsg+really1.3.1-1+b1
linux-perf recommends no packages.
Versions of packages linux-perf suggests:
ii linux-doc-6.12 6.12.19-1
-- no debconf information
Input file is perf-intel-pt.1
Output from "mandoc -T lint perf-intel-pt.1": (shortened list)
1 input text line longer than 80 bytes: "Branches" events lo...
1 input text line longer than 80 bytes: "per thread" mode is...
1 input text line longer than 80 bytes: (i.e. no TSC timesta...
1 input text line longer than 80 bytes: Also the number of l...
1 input text line longer than 80 bytes: An alternative to \f...
1 input text line longer than 80 bytes: And then copy guest\...
1 input text line longer than 80 bytes: Another interesting ...
1 input text line longer than 80 bytes: Cycles can be displa...
1 input text line longer than 80 bytes: Decoding is done on\...
1 input text line longer than 80 bytes: Dumping all instruct...
1 input text line longer than 80 bytes: Even with the \fIcyc...
1 input text line longer than 80 bytes: Event Trace records ...
1 input text line longer than 80 bytes: Examples can be foun...
1 input text line longer than 80 bytes: If needed, VDSO can ...
1 input text line longer than 80 bytes: If trace data is los...
1 input text line longer than 80 bytes: In addition, the cur...
1 input text line longer than 80 bytes: In per\-thread mode ...
2 input text line longer than 80 bytes: Intel PT traces both...
1 input text line longer than 80 bytes: It is also possible ...
1 input text line longer than 80 bytes: It is possible to us...
1 input text line longer than 80 bytes: MTC packets are used...
2 input text line longer than 80 bytes: Mount the guest file...
1 input text line longer than 80 bytes: Note IPC for "branch...
1 input text line longer than 80 bytes: Note it is also poss...
1 input text line longer than 80 bytes: Note that last branc...
1 input text line longer than 80 bytes: Note that the existi...
1 input text line longer than 80 bytes: Note there are now n...
1 input text line longer than 80 bytes: Note, due to the gue...
1 input text line longer than 80 bytes: Note, the host trace...
1 input text line longer than 80 bytes: Note, this is essent...
1 input text line longer than 80 bytes: Now \fIperf inject\f...
1 input text line longer than 80 bytes: Originally, software...
1 input text line longer than 80 bytes: Refer to \fInew snap...
1 input text line longer than 80 bytes: Refer to script expo...
1 input text line longer than 80 bytes: Repeating the q opti...
1 input text line longer than 80 bytes: Show an excerpt from...
1 input text line longer than 80 bytes: Sideband events from...
2 input text line longer than 80 bytes: Start an open\-ended...
1 input text line longer than 80 bytes: TSC is not supported...
1 input text line longer than 80 bytes: The calculation used...
1 input text line longer than 80 bytes: The default auxtrace...
1 input text line longer than 80 bytes: The default snapshot...
1 input text line longer than 80 bytes: The difference betwe...
1 input text line longer than 80 bytes: The flags are "bcros...
1 input text line longer than 80 bytes: The intel\-pt\-event...
1 input text line longer than 80 bytes: The mmap size and au...
1 input text line longer than 80 bytes: The option "dry\-run...
1 input text line longer than 80 bytes: There are two ways t...
1 input text line longer than 80 bytes: To display PEBS even...
1 input text line longer than 80 bytes: Trace data is collec...
1 input text line longer than 80 bytes: Trace data must be \...
1 input text line longer than 80 bytes: Unless /proc/sys/ker...
1 input text line longer than 80 bytes: addresses. To suppor...
1 input text line longer than 80 bytes: and cycle events are...
1 input text line longer than 80 bytes: as the data capture....
1 input text line longer than 80 bytes: branches entering an...
1 input text line longer than 80 bytes: buffer sizes are lim...
1 input text line longer than 80 bytes: builds, however the ...
1 input text line longer than 80 bytes: by inability to acce...
1 input text line longer than 80 bytes: can be used to deter...
1 input text line longer than 80 bytes: cases, avoid specify...
1 input text line longer than 80 bytes: data is available yo...
1 input text line longer than 80 bytes: events happening in ...
1 input text line longer than 80 bytes: faults, VM exits and...
1 input text line longer than 80 bytes: it. The other tools...
1 input text line longer than 80 bytes: kernels and perf too...
1 input text line longer than 80 bytes: must be preceded by ...
1 input text line longer than 80 bytes: only 7\-bytes, so th...
1 input text line longer than 80 bytes: perf script displays...
1 input text line longer than 80 bytes: resulting in data lo...
1 input text line longer than 80 bytes: selected by providin...
1 input text line longer than 80 bytes: simply \fIdata\fP) a...
1 input text line longer than 80 bytes: that in full trace w...
1 input text line longer than 80 bytes: useful to use the \f...
1 input text line longer than 80 bytes: using \fIperf inject...
1 input text line longer than 80 bytes: was not able to diff...
1 input text line longer than 80 bytes: which will create a ...
1 input text line longer than 80 bytes: will or will not be ...
1 skipping insecure request: mso
1 skipping paragraph macro: br at the end of SH
17 skipping paragraph macro: sp after SH
15 skipping paragraph macro: sp after SS
1 skipping unknown macro: LINKSTYLE blue R < >
-.-.
Output from "test-nroff -mandoc -t -ww -z perf-intel-pt.1": (shortened list)
1 cannot break line
-.-.
Show if asciidoctor generated this.
Who is actually generating this man page? Debian or upstream?
Is the generating software out of date?
4:.\" Generator: Asciidoctor 2.0.23
Latest version: Asciidoctor 2.0.23 [https://asciidoctor.org]
-.-.
Reduce space between words.
perf-intel-pt.1:1387:collection of side\-band information. In order to prevent that, a dummy
perf-intel-pt.1:1636:this: "ip: 0 payload: 0x123456789abcdef0" where "ip" is 1 if "fup_on_ptw" was
perf-intel-pt.1:1739:sets the period to 10us i.e. one instruction sample is synthesized for each 10
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
620:e.g. value 3 means 16KiB bytes between PSBs
1173:warning. When sampling is used, psb_period defaults to 0 (2KiB).
1175:The default sample size is 4KiB.
1178:sample size is limited by the maximum event size which is 64KiB. It is
1180:but the tool validates that the sample size is not greater than 60KiB.
1211:nor snapshot size is specified, then the default is 4MiB for privileged users
1212:(or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
1237:selects a buffer size of 16 pages i.e. 64KiB.
1242:The default auxtrace mmap size for Intel PT is 4MiB/page_size for privileged users
1243:(or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
1245:reduced from the default 512KiB/page_size to 256KiB/page_size, otherwise the
1248:512KiB (actually /proc/sys/kernel/perf_event_mlock_kb minus 1 page) per cpu
1249:against the mlock limit so an unprivileged user is allowed 512KiB per cpu plus
1250:their mlock limit (which defaults to 64KiB but is not multiplied by the number
1338:buffer sizes are limited to powers of 2 up to 4MiB (MAX_PAGE_ORDER). In order to
2519:$ sudo perf record \-o guest\-sideband\-testing\-host\-perf.data \-m,64M \-\-kcore \-a \-e intel_pt/cyc/
-.-.
Strings longer than 3/4 of a standard line length (80).
Use "\:" to split the string at the end of an output line, for example a
long URL (web address)
410 /sys/bus/event_source/devices/intel_pt/format/cyc_thresh:config:19\-22
412 /sys/bus/event_source/devices/intel_pt/format/mtc_period:config:14\-17
413 /sys/bus/event_source/devices/intel_pt/format/noretcomp:config:11
414 /sys/bus/event_source/devices/intel_pt/format/psb_period:config:24\-27
484 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
498 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
503 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1013 /sys/bus/event_source/devices/intel_pt/caps/power_event_trace
1146 perf record \-e \*(Aq{intel_pt//u,branch\-misses/aux\-sample\-size=8192/u}\*(Aq
1477 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1491 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1496 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1507 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1512 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1531 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2231 kcore added to build\-id cache directory /home/user/.debug/[kernel.kcore]/9600f316a53a0f54278885e8d9710538ec5f6a08/2021021807494306
2232 $ KALLSYMS=/home/user/.debug/[kernel.kcore]/9600f316a53a0f54278885e8d9710538ec5f6a08/2021021807494306/kallsyms
2331 same kcore found in /home/user/.debug/[kernel.kcore]/cc9c55a98c5e4ec0aeda69302554aabed5cd6491/2021021312450777
2332 $ KALLSYMS=/home/user/.debug/\(rs[kernel.kcore\(rs]/cc9c55a98c5e4ec0aeda69302554aabed5cd6491/2021021312450777/kallsyms
2631 $ perf inject \-i guest\-sideband\-testing\-host\-perf.data \-o inj \-\-guestmount ~/guestmount \-\-guest\-data=guest\-sideband\-testing\-guest\-perf.data,13376,0xfffffa6ae070cb20
2778 [guest/18436] 18436 [007] 10897.962087836:\& branches:\& vmentry\& 0 [unknown] ([unknown]) =>\& 402c81 guest_code+0x131 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2779 [guest/18436] 18436 [007] 10897.962087836:\& branches:\& call\& 402c81 guest_code+0x131 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dba0 ucall+0x0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2779 [guest/18436] 18436 [007] 10897.962087836:\& branches:\& call\& 402c81 guest_code+0x131 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dba0 ucall+0x0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2780 [guest/18436] 18436 [007] 10897.962088248:\& branches:\& vmexit\& 40dba0 ucall+0x0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 0 [unknown] ([unknown])
2790 [guest/18436] 18436 [007] 10897.962089424:\& branches:\& vmentry\& 0 [unknown] ([unknown]) =>\& 40dba0 ucall+0x0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2791 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jmp\& 40dc1b ucall+0x7b (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc39 ucall+0x99 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2791 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jmp\& 40dc1b ucall+0x7b (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc39 ucall+0x99 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2792 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc3c ucall+0x9c (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc20 ucall+0x80 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2792 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc3c ucall+0x9c (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc20 ucall+0x80 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2793 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc3c ucall+0x9c (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc20 ucall+0x80 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2793 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc3c ucall+0x9c (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc20 ucall+0x80 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2794 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc37 ucall+0x97 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc50 ucall+0xb0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2794 [guest/18436] 18436 [007] 10897.962089701:\& branches:\& jcc\& 40dc37 ucall+0x97 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dc50 ucall+0xb0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
2795 [guest/18436] 18436 [007] 10897.962089878:\& branches:\& vmexit\& 40dc55 ucall+0xb5 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 0 [unknown] ([unknown])
3129 .URL "https://perf.wiki.kernel.org/index.php/Perf_tools_support_for_Intel%C2%AE_Processor_Trace"; "" ""
-.-.
Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
82:Data is captured with \fIperf record\fP e.g. to trace \fIls\fP userspace\-only:
92:And profiled with \fIperf report\fP e.g.
106:\-\-kcore is used, but access to /proc/kcore is restricted e.g.
130:selected for reporting. e.g. sample every microsecond
277:sampling increases i.e. if the number of cycles is too low by a small amount,
284:(e.g. page fault or interrupt), then the instruction count does not include the
289:presently sampled, so IPC values for them do not appear e.g. a CYC packet with a
291:value, "instructions" events can be used e.g. \-\-itrace=i0ns
368:An enhancement has been made to allow default "config" e.g. the option
420:Note that the default config must be overridden for each term i.e.
479:perf_event_attr is displayed if the \-vv option is used e.g.
522:The default config selects tsc (i.e. tsc=1).
534:The default config does not select noretcomp (i.e. noretcomp=0).
595:valid values e.g. bit 2 set means value 2 is valid.
620:e.g. value 3 means 16KiB bytes between PSBs
629:will give a list of valid values e.g.
647:of 3 (i.e. psb_period=3) or the nearest lower value that is
741:valid values e.g. bit 2 set means value 2 is valid.
765:e.g. value 3 means one eighth of CTC\-frequency
783:will give a list of valid values e.g.
876:valid values e.g. bit 2 set means value 2 is valid.
902:e.g. value 4 means 8 CPU cycles must pass before a CYC packet
904:packet is sent, not at, e.g. every 8 CPU cycles.
913:will give a list of valid values e.g.
1098:Optionally it can be followed by the sample size in bytes e.g.
1108:In addition, the Intel PT event to sample must be defined e.g.
1118:Samples on other events will be created containing Intel PT data e.g. the
1131:events. In this case, the grouping is implied e.g.
1200:Optionally it can be followed by the snapshot size e.g.
1216:The snapshot size is displayed if the option \-vv is used e.g.
1227:Intel PT buffer size is specified by an addition to the \-m option e.g.
1237:selects a buffer size of 16 pages i.e. 64KiB.
1257:The mmap size and auxtrace mmap size are displayed if the \-vv option is used e.g.
1274:Full\-trace mode traces continuously e.g.
1284:Sample mode attaches a Intel PT sample to other events e.g.
1295:control command is issued. e.g. using a signal
1313:controlled by access to a FIFO e.g.
1337:There may be buffer limitations (i.e. single ToPa entry) which means that actual
1426:command to run (i.e. the workload).
1431:In per\-cpu mode all processes (or processes from the selected cgroup i.e. \-G
1470:The sched_switch events are automatically added. e.g. the second event shown
1727:perf\-config(1) e.g. perf config itrace.debug\-log\-buffer\-size=30000
1729:In addition, the period of the "instructions" event can be specified. e.g.
1739:sets the period to 10us i.e. one instruction sample is synthesized for each 10
1755:\fIinstructions\fP (i.e. \-\-itrace=i1i).
1758:transactions events can be specified. e.g.
1770:transactions events can be specified. e.g.
1826:cases, avoid specifying the event period i.e. avoid the \fIperf record\fP \-c option,
1968:Note the q option does not specify what events will be synthesized e.g. the p
1971:Repeating the q option (double\-q i.e. qq) results in even faster decoding and even
1973:instruction pointer if there is a FUP packet within PSB+ (i.e. between PSB and
2005:(i.e. config term tsc=0). It can be useful to avoid timestamp issues when
2033:perf script has an option (\-D) to "dump" the events i.e. display the binary
2054:removed and replaced with the synthesized events. e.g.
2116:Recording is selected by using the aux\-output config term e.g.
2139:To display PEBS events from the Intel PT trace, use the itrace \fIo\fP option e.g.
2183:(i.e. no TSC timestamps) or VM Time Correlation. VM Time Correlation is an extra step
2193:Guest kernel self\-modifying code (e.g. jump labels or JIT\-compiled eBPF) will result in decoding errors
2369:have no effect i.e. the resulting timestamps will be correct anyway.
2670:only calls and errors are displayed i.e. \-\-itrace=ce
2869:Event trace is selected for recording using the "event" config term. e.g.
2879:Event trace events are output using the \-\-itrace I option. e.g.
2919:flag is changed, then the "t" flag is also included i.e.
2936:TNT packets are disabled using the "notnt" config term. e.g.
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Longest line is number 2779 with 320 characters
[guest/18436] 18436 [007] 10897.962087836:\& branches:\& call\& 402c81 guest_code+0x131 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test) =>\& 40dba0 ucall+0x0 (/home/user/git/work/tools/testing/selftests/kselftest_install/kvm/tsc_msrs_test)
-.-.
Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
perf-intel-pt.1:1814:\- hardware supports it
perf-intel-pt.1:1815:\- PEBS is used
perf-intel-pt.1:1816:\- event period is specified, instead of frequency
perf-intel-pt.1:1817:\- the sample type is limited to the following flags:
perf-intel-pt.1:3110:\- full\-trace, system wide : when buffer passes watermark
perf-intel-pt.1:3111:\- full\-trace, not system\-wide : when buffer passes watermark or
perf-intel-pt.1:3113:\- snapshot mode : as above but also when a snapshot is made
perf-intel-pt.1:3114:\- sample mode : as above but also when a sample is made
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
1727:perf\-config(1) e.g. perf config itrace.debug\-log\-buffer\-size=30000
2030:See also perf\-dlfilters(1)
3132:perf\-record(1), perf\-script(1), perf\-report(1),
3133:perf\-inject(1)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-
Use a character "\(->" instead of plain "->" or "\->".
2909:iflag:\& t\& IFLAG: 1\->0 via branch
2925:t\& interrupts become disabled IF=1 \-> IF=0
2927:Dt\& interrupts become enabled\& IF=0 \-> IF=1
-.-.
Only one space character after a possible end of sentence
(after a punctuation, that can end a sentence).
[List of affected lines removed.]
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
perf-intel-pt.1:10:.TH "PERF\-INTEL\-PT" "1" "2025-03-16" "perf" "perf Manual"
perf-intel-pt.1:30:.SH "NAME"
perf-intel-pt.1:32:.SH "SYNOPSIS"
perf-intel-pt.1:38:.SH "DESCRIPTION"
perf-intel-pt.1:76:.SH "QUICKSTART"
perf-intel-pt.1:2007:.SS "dlfilter\-show\-cycles.so"
perf-intel-pt.1:2066:.URL "https://github.com/google/autofdo"; "" ")"
perf-intel-pt.1:2069:.URL "https://gcc.gnu.org/wiki/AutoFDO/Tutorial"; "" ")"
perf-intel-pt.1:2148:.SH "XED"
perf-intel-pt.1:3125:.SH "EXAMPLE"
perf-intel-pt.1:3129:.URL "https://perf.wiki.kernel.org/index.php/Perf_tools_support_for_Intel%C2%AE_Processor_Trace"; "" ""
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
15:.ad l
23:. ad l
26:. ad l
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
30:.SH "NAME"
32:.SH "SYNOPSIS"
38:.SH "DESCRIPTION"
76:.SH "QUICKSTART"
363:.SH "PERF RECORD"
364:.SS "new event"
507:.SS "config terms"
1086:.SS "AUX area sampling option"
1181:.SS "new snapshot option"
1225:.SS "new auxtrace mmap size option"
1267:.SS "Intel PT modes of operation"
1335:.SS "Buffer handling"
1356:.SS "Intel PT and build ids"
1383:.SS "Snapshot mode and event disabling"
1415:.SS "perf record modes (nothing new here)"
1438:.SS "Privileged vs non\-privileged users"
1464:.SS "sched_switch tracepoint"
1553:.SH "PERF SCRIPT"
1557:.SS "New \-\-itrace option"
2007:.SS "dlfilter\-show\-cycles.so"
2031:.SS "dump option"
2046:.SH "PERF REPORT"
2051:.SH "PERF INJECT"
2113:.SH "PEBS VIA INTEL PT"
2148:.SH "XED"
2180:.SH "TRACING VIRTUAL MACHINES (KERNEL ONLY)"
2467:.SH "TRACING VIRTUAL MACHINES (INCLUDING USER SPACE)"
2754:.SH "TRACING VIRTUAL MACHINES \- GUEST CODE"
2839:.SH "EVENT TRACE"
2934:.SH "TNT DISABLE"
2948:.SH "EMULATED PTWRITE"
3097:.SH "PIPE MODE"
3125:.SH "EXAMPLE"
3130:.SH "SEE ALSO"
-.-.
Remove excessive "\&" when it has no functional purpose.
[List of affected lines removed.]
-.-.
Put a (long) web address on a new line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
2066:.URL "https://github.com/google/autofdo"; "" ")"
2069:.URL "https://gcc.gnu.org/wiki/AutoFDO/Tutorial"; "" ")"
2155:$ git clone https://github.com/intelxed/mbuild.git mbuild
2156:$ git clone https://github.com/intelxed/xed
3129:.URL "https://perf.wiki.kernel.org/index.php/Perf_tools_support_for_Intel%C2%AE_Processor_Trace"; "" ""
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:3129: warning [page 28, line 13]: cannot break line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
Reply to: