Date: Sun, 21 Oct 2018 22:09:11 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Tobias Kortkamp <tobik@freebsd.org> Cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r339448 - head/usr.sbin/vidcontrol Message-ID: <20181021211041.O1174@besplex.bde.org> In-Reply-To: <201810201659.w9KGxiT3092274@repo.freebsd.org> References: <201810201659.w9KGxiT3092274@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 20 Oct 2018, Tobias Kortkamp wrote: > ... > Log: > vidcontrol(1): Fix a typo in the description of -f > > While here: > - Fix markup in -c This was supposed to be consistent with nearby style, but I changed the main .Cm to .Ar so it was inconsistent with itself. There are many other misuses of .Cm in this file and probably in others. I think the only correct uses of .Cm are when there is no flags arg. stty(1) gives many examples. E.g., 'sane' in "stty sane" really is a command modifier -- it modifies the command 'stty. But here .Cm was misused for args of -c. Those really are args. > ... > Modified: head/usr.sbin/vidcontrol/vidcontrol.1 > ============================================================================== > --- head/usr.sbin/vidcontrol/vidcontrol.1 Sat Oct 20 16:52:18 2018 (r339447) > +++ head/usr.sbin/vidcontrol/vidcontrol.1 Sat Oct 20 16:59:43 2018 (r339448) > ... > @@ -109,10 +109,10 @@ below. > .It Ar foreground Op Ar background This has the reverse bug. There is no flags arg, so the args modify the command directly so should use .Cm, as for stty(1). stty.1 gets this wrong too. Most commands use flags and not many direct command modifiers. stty.1 does the opposite. It starts correctly by using .Ar for its -f arg. Then it misuses .Ar for its speed command modifier. Then it does correct things like ".It Cm ispeed Ar number". Here ispeed is a command modifier for stty and number is an arg for ispeed. vidcontrol.1 apparently uses a mixture of .Cm and .Ar to try to do something similar. It is correct for it to switch to .Ar for args of a .Cm, but often incorrect to start with .Cm. stty.1 misuses .Ar for the C struct member name c_lflag and the C struct tag name termios. These seem to be its only misuses of .Ar. > @@ -128,13 +128,13 @@ Clear the history buffer. > .It Fl c Ar setting Ns Op , Ns Ar setting ... > Change the cursor appearance. > The change is specified by a non-empty comma-separated list of > -.Cm setting Ns s . > +.Ar setting Ns s . Old versions used "... c Cm normal | blink | destructive". .Cm was incorrect here. I fixed it in the flags line but seem to have left it broken for all other instances of 'setting. Here are most of the current misuses of .Cm in vidcontrol.1: - after the [imST] flags - after the t flag, the first alternative uses the correct .Ar but the second alternative misuses .Cm. - for the normal, blink, noblock, destructive, height and base args for -c (missed in this commit). These are all 'settings', so they are more like args than command modifiers (they are the names of instances of args and distinguishing them the names of args, or distingishing names from what they name, would be too subtle). - .Cm value after '... Cm base Ns = Ns Ar value". If 'base' were a command modifier, then its 'value' would still be an arg, but 'base' should be an arg too. Then the second 'value' should not change from an arg to a command modifier. - zillions more .Cm's for args of -c should be .Ar's. ISTR spending a lot of time making these consistent. Now I think they are consistently wrong. - .Cm's for 8x8, 8x14 and 8x16. Again these are names of instances of args. They are not quite args or names of args, but they are much closer to args than they are to command modifiers. - consistently for names of instances of args for the [imSTt] flags Most or all uses of .Ar in vidcontrol.1 are correct. There are many examples where .Ar is used for the name of an instance of an arg, so the extensive use of .Cm for names of instances of args doesn't seem to be because there is a special convention for this. I wrote more than half of the latter for -c by copying bad examples. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20181021211041.O1174>