On Sat, Apr 19, 2025 at 10:34:36PM +0200, Ingo Schwarze wrote:
> Hello Henrich,
> 

hi both!

> H. Hartzer wrote on Sat, Apr 19, 2025 at 07:50:52PM +0000:
> 
> > Here's a patch that adds where to find signals to the pkill(1) man page.
> 
> I like the basic idea.  The kill(1) manual page also refers
> to sigaction(2) near the end of the DESCRIPTION, and kill(2)
> even does that at the beginning of the DESCRIPTION.
> 
> > sigaction(2) is already referenced under "see also," but without any
> > prior explanation as to why.
> 
> Indeed, the purpose of the existing .Xr may not be obvious
> to less experienced users.
> 
> We generally don't want to talk about "you" in manual pages, though,
> so here is what i suggest.
> 
> Since "TERM" is a string that has to be typed in verbatim, it should
> appear in bold face, and actually, a dash has to be typed in front of it,
> which is exactly what the .Fl macro does.  That macro also makes sense
> semantically because "-TERM" clearly serves the function of a command
> line flag.
> 
> OK?
>   Ingo
> 

regarding the mark up of TERM: kill(1) does not document signals this
way, and i don;t think pkill(1) should start either. it's inconsistent
and, if anything, confusing to document the signal name as "-TERM".

another choice for documenting sigaction(2) would be - again - to follow
kill(1) and list some commonly used sig names, and refer to sigaction(2)
for the full list. that might make less work for the reader and be more
consistent. then again this program isn;t kill(1) and maybe just the
hint is enough.

i.e. i'm ok with the diff, minus the "-TERM" stuff.

jmc

> 
> Index: pkill.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/pkill/pkill.1,v
> diff -u -r1.25 pkill.1
> --- pkill.1	14 Nov 2020 14:06:42 -0000	1.25
> +++ pkill.1	19 Apr 2025 20:28:48 -0000
> @@ -166,8 +166,10 @@
>  is given.
>  The default is to match any substring.
>  .It Fl Ar signal
> -A non-negative decimal number or symbolic signal name specifying the signal
> -to be sent instead of the default TERM.
> +A non-negative decimal number or one of the symbolic names listed in
> +.Xr sigaction 2
> +specifying the signal to be sent instead of the default
> +.Fl TERM .
>  This option is valid only when given as the first argument to
>  .Nm pkill .
>  .El
> 
> 
> > diff --git a/usr.bin/pkill/pkill.1 b/usr.bin/pkill/pkill.1
> > index d8719b79991..91c0970b5e1 100644
> > --- a/usr.bin/pkill/pkill.1
> > +++ b/usr.bin/pkill/pkill.1
> > @@ -170,6 +170,9 @@ A non-negative decimal number or symbolic signal name specifying the signal
> >  to be sent instead of the default TERM.
> >  This option is valid only when given as the first argument to
> >  .Nm pkill .
> > +For a list of signals that you can use, see the
> > +.Xr sigaction 2
> > +manual page.
> >  .El
> >  .Pp
> >  If any
>