Hello Evan,

your patch actually triggered a breakthrough in my understanding
of one particular aspect of the mdoc(7) language that has been
a thorn in our side for years, please bear with me:

Evan Silberman wrote on Sun, May 18, 2025 at 10:48:44PM -0700:

> I was looking at top, was wondering what WAIT meant, typed `man top`
> and then :t WAIT in the pager

I'm always happy to hear that people do that.  :-)

> and got no results.

Admittedly not ideal.  One might argue that "/WAIT" instead of ":tWAIT"
works in this case and is 16% shorter - then again, stuff working only
on the second try is not very user-friendly, and even worse, "/CPU"
finds the desired definition only with the eigth match.

> I can't think of a better mdoc macro for an element of an interactive
> display

This is amazing, your sentence actually contains the best possible
search term for

  https://mandoc.bsd.lv/mdoc/appendix/markup.html

The relevant entry reads:

  display:
   * very short, for example a single character: Sq
   * in-line display, default font: Dq
   * in-line display, literal font: Ql
   * single indented line, default font: D1
   * single indented line, literal font: Dl
   * multiple lines: Bd

Note that the term "display" is ambiguous.  In the context of
documentation, it refers to the manual page displaying something,
usually example code or example output or both combined.
In the context of a program, it refers to the program itself
displaying something, usually program results on standard output.
In your case, *both* meanings of the term apply.

The trouble is that what you want here is - in documentation terms -
an unquoted in-line literal display, and the appendix of the
extended documentation suggests no macro for that.  You want it
 * unquoted because .It already makes it stand out (eliminates Sq Dq Ql)
 * in-line such that it can fit in the .It head (eliminates D1 Dl Bd)
 * literal because it is program output (eliminates Sq Dq D1)

But a fitting macro does actually exist: .Li ...

I deprecated that macro six years ago in mdoc.7 rev. 1.161
with the commit message

  Simplify and clarify instructions for .Ql, and deprecate .Li.
  The macros .Ql, .Dl, and .Bd -literal leave no room for any
  valid use case for .Li whatsoever.
  General direction discussed with jmc@.

It appears that was overly aggressive, you just found a valid use case.

Also, your use case lifts the macro from it's deplorably
presentational definition - see "man -O tag=Li mdoc"

  Li word ...
    Request a typewriter (literal) font.  ...

to a much better semantic defintion which will be something like

    Unquoted in-line literal display.


> than Sy; Ic seems worse.

You are right, .Ic would be totally wrong because the user does not type it.
While .Sy is less bad, it is not really right either because you do not
want to indicate seriousness nor is this really a "syntax element" -
it is merely output to be displayed.

> If none are appropriate we could
> sprinkle Tg in this list but that seemed less desirable.

Correct, do not use .Tg as a replacement for semantic markup, only use
it *after* you got the semantics right if the automatic tag detection
then still remains unable to find the word to be tagged, which is
very rare.  If that happens at all, it usually happens with very
complex syntax like this found in tmux(1) and ddb(4):

  .Tg attach
  .It Xo Ic attach-session
  .Op Fl dErx
  .Op Fl c Ar working-directory
  .Op Fl f Ar flags
  .Op Fl t Ar target-session
  .Xc

  .Tg examine
  .It Xo
  .Oo Ic e Oc Ns
  .Ic x Ns Op Ic amine
  .Op Cm /bhlqaAxzodurcsmiI
  .Op Ar addr Ns
  .Op Ic \&, Ns Ar count
  .Xc

Anyone willing to OK the following version of the patch?
  Ingo


Index: top.1
===================================================================
RCS file: /cvs/src/usr.bin/top/top.1,v
diff -u -r1.82 top.1
--- top.1	19 May 2025 12:27:56 -0000	1.82
+++ top.1	19 May 2025 13:39:46 -0000
@@ -432,27 +432,31 @@
 but it is not exactly the same.
 The following fields are displayed:
 .Bl -tag -width USERNAME -offset indent
-.It PID
+.It Li PID
 The process ID.
-.It USERNAME
+.It Li USERNAME
 The name of the process's owner.
-.It TID
-The thread ID, used instead of USERNAME if
+.It Li TID
+The thread ID, used instead of
+.Li USERNAME
+if
 .Fl H
 is specified.
-.It UID
-Used instead of USERNAME if
+.It Li UID
+Used instead of
+.Li USERNAME
+if
 .Fl u
 is specified.
-.It PRI
+.It Li PRI
 The current priority of the process.
-.It NICE
+.It Li NICE
 The nice amount (in the range \-20 to 20).
-.It SIZE
+.It Li SIZE
 The total size of the process (the text, data, and stack segments).
-.It RES
+.It Li RES
 The current amount of resident memory.
-.It STATE
+.It Li STATE
 The current state (one of
 .Li start ,
 .Li run ,
@@ -465,19 +469,21 @@
 .Li onproc ) .
 On multiprocessor systems, this is followed by a slash and the CPU
 number on which the process is bound.
-.It WAIT
+.It Li WAIT
 A description of the wait channel the process is sleeping on if it's
 asleep.
-.It RTABLE
-The routing table, used instead of WAIT if
+.It Li RTABLE
+The routing table, used instead of
+.Li WAIT
+if
 .Fl t
 is specified.
-.It TIME
+.It Li TIME
 The number of system and user CPU seconds that the process has used.
-.It CPU
+.It Li CPU
 The raw percentage of CPU usage and the default field on which the
 display is sorted.
-.It COMMAND
+.It Li COMMAND
 The name (and arguments if
 .Fl C
 is specified) of the command that the process is currently running.