From: Jason McIntyre Subject: Re: [PATCH] man 1 pkill: Add where signals can be found To: Ingo Schwarze Cc: tech@openbsd.org Date: Sun, 20 Apr 2025 21:26:13 +0100 On Sun, Apr 20, 2025 at 10:03:47PM +0200, Ingo Schwarze wrote: > Hi Jason, > hi. > 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. > 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*. i.e. let's amke sure we have a good enough reason to change this. or propose to other projects the same change > 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. > i'm fine with improving it, just want to make sure it is an improvement. > 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! 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'm ok with this i guess, but maybe leave it sit overnight... jmc > 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); > }