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 <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.
> 

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);
>  }