Hi Ian,
At 2024-11-01T12:11:56-0700, Ian Rogers wrote:
[...]
> +.EX
> +pos: 0
> +flags: 02100002
> +mnt_id: 26
> +ino: 284
> +drm-driver: i915
> +drm-client-id: 39
> +drm-pdev: 0000:00:02.0
> +drm-total-system0: 6044 KiB
> +drm-shared-system0: 0
> +drm-active-system0: 0
> +drm-resident-system0: 6044 KiB
> +drm-purgeable-system0: 1688 KiB
> +drm-total-stolen-system0: 0
> +drm-shared-stolen-system0: 0
> +drm-active-stolen-system0: 0
> +drm-resident-stolen-system0: 0
> +drm-purgeable-stolen-system0: 0
> +drm-engine-render: 346249 ns
> +drm-engine-copy: 0 ns
> +drm-engine-video: 0 ns
> +drm-engine-capacity-video: 2
> +drm-engine-video-enhance: 0 ns
> +.EE
> +.TP
> +.IR drm-driver: " .+ (mandatory)"
> +The name this driver registered.
> +.TP
> +.IR drm-pdev: " <aaaa:bb:cc.d>"
> +For PCI devices this should contain the PCI slot address of the device
> +in question.
> +.TP
> +.IR drm-client-id: " [0-9]+"
> +Unique value relating to the open DRM file descriptor used to
> +distinguish duplicated and shared file descriptors.
> +.P
> +GPUs usually contain multiple execution engines. Each shall be given a
> +stable and unique name (<engine_name>), with possible values
> +documented in the driver specific documentation.
> +.TP
> +.IR drm-engine-<engine_name>: " [0-9]+ ns"
> +GPU engine utilization, time spent busy executing workloads for this client.
[...]
In my opinion the use of <bracketed_notation> like that is not idiomatic
in man pages. (We sometimes see it anyway, because for a long time
"rock star programmers" have treated the neglect of man page idioms as a
competitive sport.[1])
Also the mixture of regex notation with <bracketed_notation> is a little
bewildering (again, my opinion).
I would recast these to use bold for the literal bits, italics for the
variable parts, roman for nonliteral syntax, and, for this page, lean
completely into the use of EREs.
groff_man_style(7) offers suggestions:
Font style macros
...
Use bold for literal portions of syntax synopses, for
command‐line options in running text, and for literals
that are major topics of the subject under discussion; for
example, this page uses bold for macro, string, and
register names. In an .EX/.EE example of interactive I/O
(such as a shell session), set only user input in bold.
...
Use italics for file and path names, for environment
variables, for C data types, for enumeration or
preprocessor constants in C, for variant (user‐
replaceable) portions of syntax synopses, for the first
occurrence (only) of a technical concept being introduced,
for names of journals and of literary works longer than an
article, and anywhere a parameter requiring replacement by
the user is encountered. An exception involves variant
text in a context already typeset in italics, such as file
or path names with replaceable components; in such cases,
follow the convention of mathematical typography: set the
file or path name in italics as usual but use roman for
the variant part (see .IR and .RI below), and italics
again in running roman text when referring to the variant
material.
...
Observe what is not prescribed for setting in bold or italics
above: elements of “synopsis language” such as ellipses and
brackets around options; proper names and adjectives; titles of
anything other than major works of literature; identifiers for
standards documents or technical reports such as CSTR #54,
RFC 1918, Unicode 13.0, or POSIX.1‐2017; acronyms; and
occurrences after the first of a technical term.
So I might write these more like the following.
.P
We use extended regular expressions to represent the expected parameter
values;
see
.BR regex (7). \" `BR` for Linux man-pages documents only
.TP
.BR drm\-driver: " .+"\c
.I " (mandatory)"
The name this driver registered.
.TP
.BR drm\-pdev: " [0-9A-F]{4}:[0-9A-F]{2}:[0-9A-F]{2}.[0-9A-F]"
For PCI devices this should contain the PCI slot address of the device
in question.
.TP
.BR drm\-client\-id: " [0-9]+"
Unique value relating to the open DRM file descriptor used to
distinguish duplicated and shared file descriptors.
.P
GPUs usually contain multiple execution engines.
Each shall be given a
stable and unique
.IR engine-name ,
with possible values documented in driver-specific documentation.
.TP
.BI drm\-engine\- engine-name :\c
\& [0-9]+ ns
GPU engine utilization:
time spent busy executing workloads for this client.
I also (1) used the `\c` escape sequence to fit three different font
styles into a paragraph tag; and (2) escaped literal hyphens.
Regards,
Branden
[1] I give you the Worst Man Page in the World.
https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
Fortunately the procps-ng maintainers eventually rewrote it.
Attachment:
signature.asc
Description: PGP signature
