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