Message-ID: <20241102103839.fv3qvp2ltgzzvlr5@illithid>
Date: Sat, 2 Nov 2024 05:38:39 -0500
From: "G. Branden Robinson" <g.branden.robinson@...il.com>
To: Ian Rogers <irogers@...gle.com>
Cc: Alejandro Colomar <alx@...nel.org>, David Airlie <airlied@...il.com>,
	Simona Vetter <simona@...ll.ch>,
	Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
	Maxime Ripard <mripard@...nel.org>,
	Thomas Zimmermann <tzimmermann@...e.de>,
	Jonathan Corbet <corbet@....net>, dri-devel@...ts.freedesktop.org,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	linux-man@...r.kernel.org
Subject: Re: [PATCH v3 4/4] proc_pid_fdinfo.5: Add DRM subsection

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.

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists