From: Ingo Schwarze Subject: Re: [PATCH] man 1 pkill: Add where signals can be found To: Jason McIntyre Cc: tech@openbsd.org Date: Sun, 20 Apr 2025 22:03:47 +0200 Hi Jason, 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 > > - with your proposal, it looks very much like all three versions require > "-s", even though only the first does. that ambiguity is present in > the current usage() too. it's possible this is the reason why it was > split in the first place. > > we could get away with it in usage()/SYNOPSIS, but i think we'd have > to be really clear in the description of -s how it works. either by > indicating -s is optional (might make the summary more complex) or > maybe by listing it like: > > -s signal > -signame > -signum > A symbolic name or number ... You have a number of points here, but they seems relatively easy to fix by simply switching the order, see the patch below. Arguably, -s name might be minimally more portable than -name because -s is in POSIX proper and -name is only in the X/Open System Interfaces option of POSIX. Then again, the latter has been around for so long that i would not be seriously concerned about portability. On the other hand, listing the variant first that requires less typing doesn't feel that bad either. > also note that free/net/posix all use this format. may be another > reason not to poke... That doesn't sound like a strong reason. POSIX is often excessively verbose or complicated and not our model for user-friendly documentation. The uniformity probably arose from this tradition: https://man.bsd.lv/4.4BSD-Lite2/kill.1 According to the SCCS log, the four-line SYNOPSIS was introduced by Keith Bostic on 1995/04/28 with the log message "POSIX.2 compliance From: Charles Hannum " so it does indeed seem plausible that it may have been influenced in all BSDs by the POSIX version right before this one: https://pubs.opengroup.org/onlinepubs/007908799/xcu/kill.html That, however, doesn't mean we cannot improve it. We often aim for higher quality of documentation than what is found in NetBSD and FreeBSD. While here, let's also fix the weasely wording "more complete". The sigaction(2) manual is definitely intended to be and to remain complete. OK for this variant? Ingo > i'm fine with the other parts. Thanks for checking, i commited those other parts. Index: kill.1 =================================================================== RCS file: /cvs/src/bin/kill/kill.1,v diff -u -r1.41 kill.1 --- kill.1 20 Apr 2025 18:55:24 -0000 1.41 +++ kill.1 20 Apr 2025 19:33:56 -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 sigaction 2 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 20 Apr 2025 19:33:56 -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); }