Hi Klemens, Jason McIntyre wrote on Tue, Dec 20, 2022 at 10:35:19AM +0000: > On Tue, Dec 20, 2022 at 09:36:39AM +0000, Klemens Nanni wrote:
>> Both styles are used, but I argue that the former fails to distinguish >> between >> $ program 'args in one shell word' >> and >> $ program one arg per shell word >> >> It's a minor thing, imho, but perhaps we can decide for one and stick to >> it throughout the tree? >> >> Triple dots also make it immediately clear that many arguments may >> follow, no matter what the "arg"ument is named. >> >> Here's one examplatory diff for timeout(1). >> >> Feedback? > i prefer "arg ..." too. Seconded. Or rather, what, fourthed? > by comparison, it would probably look weird to > write "files" instead of "file ...". indeed the Ar macro without args > outputs exactly that. > > still it would be good to get an idea of how many pages would be > affected by this. $ man -k Ar=args gives me a relatively short list, and the only clear offenders appear to be: doas(1), openssl(1), timeout(1), route(8), and possibly boot(8) on a handful of platforms. Strangely, in build-debug-info(1), cdio(1), csplit(1), tput(1), update-plist(1), ddb(4) we have "..." after plural "args" and i'm unsure what that is even intended to mean in some of the cases. I guess i ought to fix mdoc(7) myself. > if we have only a few pages using "args" it would seem to make sense. That seems to be the case. I think kn@ is welcome to go ahead and fix them - not in a completely mechanical way, of course, the text should still be clear and read well afterwards. > if it's 50/50 we might want to look for more complex Certainly not 50/50: $ man -k Ar=... | wc -l gives me well over three hundred pages. > examples and figure out whether all the change will be worth it. > > also some things will use argument vs arg. for example ssh(1). do you > propose to change those? $ man -k Ar=argument gives me fifty results. I think that is a completely separate question and need not be handled together with the "args vs. arg ..." issue. FWIW, i personally like .Ar argument ... , at least in many cases. Avoiding unnessecary abbreviations often makes text easier and more pleasant to read. There are also a handful of "Ar=arguments" that might deserve fixing, in particular su(1), tmux(1), bgpd.conf(5), bgpctl(8), and rcctl(8). And time(1) and btrace(8) might need .Ar arguments -> .Ar argument Ns s in the vein mentioned by millert@. Yours, Ingo >> Index: timeout.1 >> =================================================================== >> RCS file: /cvs/src/usr.bin/timeout/timeout.1,v >> retrieving revision 1.3 >> diff -u -p -r1.3 timeout.1 >> --- timeout.1 4 Sep 2021 11:58:31 -0000 1.3 >> +++ timeout.1 29 Oct 2022 20:53:05 -0000 >> @@ -41,14 +41,14 @@ >> .Op Fl -preserve-status >> .Ar duration >> .Ar command >> -.Op Ar args >> +.Op Ar arg ... >> .Sh DESCRIPTION >> The >> .Nm >> utility executes >> .Ar command , >> with any >> -.Ar args , >> +.Ar arg ... , >> and kills it if it is still running after the >> specified >> .Ar duration . >> Index: timeout.c >> =================================================================== >> RCS file: /cvs/src/usr.bin/timeout/timeout.c,v >> retrieving revision 1.21 >> diff -u -p -r1.21 timeout.c >> --- timeout.c 2 Jul 2022 19:00:35 -0000 1.21 >> +++ timeout.c 29 Oct 2022 21:08:40 -0000 >> @@ -57,7 +57,7 @@ usage(void) >> fprintf(stderr, >> "usage: timeout [-k time] [-s sig] [--foreground]" >> " [--preserve-status] duration\n" >> - " command [args]\n"); >> + " command [arg ...]\n"); >> >> exit(1); >> }
