your reasoning is solid ingo. i hate to say it, but ok by me. 

jmc

On 19 May 2025 15:10:29 BST, Ingo Schwarze <schwarze@usta.de> wrote:
>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.
>