From: kerhand Subject: Re: top.1: symbolize the names of columns To: tech@openbsd.org, Ingo Schwarze , Evan Silberman Date: Mon, 19 May 2025 16:51:00 +0100 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 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. >