From: Ingo Schwarze Subject: Re: [PATCH] man 1 pkill: Add where signals can be found To: tech@openbsd.org Date: Tue, 22 Apr 2025 19:50:31 +0200 Hello Jason, Jason McIntyre wrote on Sun, Apr 20, 2025 at 09:26:13PM +0100: > On Sun, Apr 20, 2025 at 10:03:47PM +0200, Ingo Schwarze wrote: >> Jason McIntyre wrote on Sun, Apr 20, 2025 at 06:10:58PM +0100: >>> - our current usage() does not match either what SYNOPSIS currently is >>> or what you propose. so whichever way you go, we want that fixed [...] >> You have a number of points here, but they seems relatively easy to fix >> by simply switching the order, see the patch below. [...] > so, i'm not worried about portability. it's more that if pretty much > everyone reading a kill page sees it in one format (and it;s a pretty > basic, standard command) then the bigger picture of changing our page > might not be helpful *overall*. It's not quite as uniform as you seem to think. The GNU coreutils page already says - try `man gkill` - SYNOPSIS kill [-s SIGNAL | -SIGNAL] PID... which suffers from the ambiguity you pointed out, but avoids using three separate synopses for the same thing. > i.e. let's amke sure we have a good enough reason to change this. Saving two lines from the SYNOPSIS and usage() and two entries from the options table, all of which provide no additional information but require additional scrutiny from users to find out whether there are any differences (even though there are none), seems like a pretty good reason to me. Conciseness and clarity. > or propose to other projects the same change I'd very much prefer spending my time on improving OpenBSD documentation rather than on sending patches to NetBSD and FreeBSD - which might consume even more time than the original OpenBSD patch because sending a patch to them requires checking that the patch actually describes what *their* code does, which i'm typically less familiar with than with our own code. [...] >> While here, let's also fix the weasely wording "more complete". >> The sigaction(2) manual is definitely intended to be and to remain >> complete. > so, that text does not mean that sigaction(2) is less than complete! Sorry for using the misleading word "fix". I did not intend to call the existing text incorrect. > it is just a way of saying that it's got the missing bits. as a native > speaker, i don;t think the change is needed. but if you think it could > confuse, i'm ok with it. I think just "complete" is better than "more complete" because it is both a stronger statement and more concise (even though both are correct). > i'm ok with this i guess, but maybe leave it sit overnight... Thanks. Unless someone objects, i'll commit tomorrow. Yours, Ingo Index: kill.1 =================================================================== RCS file: /cvs/src/bin/kill/kill.1,v diff -u -r1.42 kill.1 --- kill.1 22 Apr 2025 16:49:14 -0000 1.42 +++ kill.1 22 Apr 2025 17:24:54 -0000 @@ -41,17 +41,11 @@ .Nd terminate or signal a process .Sh SYNOPSIS .Nm kill -.Op Fl s Ar signal_name +.Op Fl Ar signal_number | Fl Ar signal_name | Fl s Ar signal_name .Ar pid ... .Nm kill .Fl l .Op Ar exit_status -.Nm kill -.Fl Ar signal_name -.Ar pid ... -.Nm kill -.Fl Ar signal_number -.Ar pid ... .Sh DESCRIPTION The .Nm @@ -80,18 +74,10 @@ or a signal number. .Pp If no operand is given, display the names of all the signals. -.It Fl s Ar signal_name -A symbolic signal name specifying the signal to be sent instead of the -default -.Cm TERM . -.It Fl Ar signal_name -A symbolic signal name specifying the signal to be sent instead of the -default +.It Fl Ar signal_number | Fl Ar signal_name | Fl s Ar signal_name +A non-negative decimal integer or a symbolic name +specifying the signal to be sent instead of the default .Cm TERM . -.It Fl Ar signal_number -A non-negative decimal integer specifying the signal to be sent instead -of the default -.Dv SIGTERM . .El .Pp The following PIDs have special meanings: @@ -118,7 +104,7 @@ .It 15 Ta Cm TERM Ta Pq software termination signal .El .Pp -For a more complete list, consult the +For a complete list, consult the .Xr signal 3 manual page. .Pp Index: kill.c =================================================================== RCS file: /cvs/src/bin/kill/kill.c,v diff -u -r1.14 kill.c --- kill.c 29 Mar 2017 22:40:15 -0000 1.14 +++ kill.c 22 Apr 2025 17:24:54 -0000 @@ -174,12 +174,8 @@ void usage(void) { - (void)fprintf(stderr, "usage: %s [-s signal_name] pid ...\n", - __progname); + (void)fprintf(stderr, "usage: %s [-signal_number | -signal_name |" + " -s signal_name] pid ...\n", __progname); (void)fprintf(stderr, " %s -l [exit_status]\n", __progname); - (void)fprintf(stderr, " %s -signal_name pid ...\n", - __progname); - (void)fprintf(stderr, " %s -signal_number pid ...\n", - __progname); exit(1); }