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 <mycroft@NetBSD.ORG>" 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);
 }