Hi Jason,

Jason McIntyre wrote on Sun, Apr 20, 2025 at 06:43:55AM +0100:

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

Granted, the signal name is TERM, not -TERM.  I meant that -TERM is
the default option, not the default name.  But since there was no
consensus for this part of the change, i dropped it when i committing.

> 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 don't like duplicating information all that much.  I think for kill(1)
it is acceptable because the -s argument is really central there,
but as you say, for pgrep/pkill, -signal is more tangential.

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

Thanks for checking, committed.

Your remarks made me look at kill(1), and i found multiple issues there.

 * We really only want multiple synopses when there is a very strong
   reason, typically only when two synopses have completely different
   syntax and purpose.  For the last two synopses in kill(1), the
   syntax is very similar and the purpose is identical to the first
   one.  Joining all three in the first synopsis makes it clear
   that these are merely minor syntax variants, shortens the text,
   and even fits comfortable on a single line.

 * Using .Dv in section 1 manuals is usually wrong because
   C preprocessor macros normally cannot be used from the shell
   command line.  Here, it is very wrong because the names in
   the CLI do not even match the names in the C API.
   The kill(1) manual needs to talk about TERM, not SIGTERM,
   and the proper macro is .Cm, not .Dv.

 * Joing the three entries in the option list significantly shortens
   the text.  Even more importantly, it makes it clearer that the
   three syntax variants do not control three different features with
   three independent defaults but all control the same feature with
   just one single default.

 * Using .Bl -column instead of .Bl -tag avoids ugly spacing
   that is too wide in one place and too narrow in another,
   makes more sense semantically because this is really a
   three-column table, and even the mdoc(7) source code becomes
   more compact and more readable.

 * The description of -0 lacks the information that it does not
   send a signal (the truth of which is stated in kill(2) and can
   also be checked with ktrace(1)), abuses the .Li macro for
   something that is not example code but contains a placeholder,
   and repeats part of the EXIT STATUS section in a place where
   that does not belong.

OK?
  Ingo



Index: kill.1
===================================================================
RCS file: /cvs/src/bin/kill/kill.1,v
diff -u -r1.40 kill.1
--- kill.1	9 Feb 2020 00:21:01 -0000	1.40
+++ kill.1	20 Apr 2025 15:32:13 -0000
@@ -41,17 +41,11 @@
 .Nd terminate or signal a process
 .Sh SYNOPSIS
 .Nm kill
-.Op Fl s Ar signal_name
+.Op Fl s Ar signal_name | Fl Ar signal_name | Fl Ar signal_number
 .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
@@ -59,9 +53,9 @@
 by the
 .Ar pid
 operand(s).
-If no signal is specified,
-.Dv SIGTERM
-is used.
+If no signal is specified, the
+.Cm TERM
+signal is used.
 .Pp
 Only the superuser may send signals to other users' processes.
 .Pp
@@ -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
-.Dv SIGTERM .
-.It Fl Ar signal_name
-A symbolic signal name specifying the signal to be sent instead of the
-default
-.Dv SIGTERM .
-.It Fl Ar signal_number
-A non-negative decimal integer specifying the signal to be sent instead
-of the default
-.Dv SIGTERM .
+.It Fl s Ar signal_name | Fl Ar signal_name | Fl Ar signal_number
+A symbolic signal name or a non-negative decimal integer
+specifying the signal to be sent instead of the default
+.Cm TERM .
 .El
 .Pp
 The following PIDs have special meanings:
@@ -108,21 +94,14 @@
 .Pp
 Some of the more commonly used signals:
 .Pp
-.Bl -tag -width Ds -compact -offset indent
-.It 1
-HUP (hang up)
-.It 2
-INT (interrupt)
-.It 3
-QUIT (quit)
-.It 6
-ABRT (abort)
-.It 9
-KILL (non-catchable, non-ignorable kill)
-.It 14
-ALRM (alarm clock)
-.It 15
-TERM (software termination signal)
+.Bl -column MM MMMM -compact -offset indent
+.It 1  Ta Cm HUP  Ta Pq hang up
+.It 2  Ta Cm INT  Ta Pq interrupt
+.It 3  Ta Cm QUIT Ta Pq quit
+.It 6  Ta Cm ABRT Ta Pq abort
+.It 9  Ta Cm KILL Ta Pq non-catchable, non-ignorable kill
+.It 14 Ta Cm ALRM Ta Pq alarm clock
+.It 15 Ta Cm TERM Ta Pq software termination signal
 .El
 .Pp
 For a more complete list, consult the
@@ -130,9 +109,11 @@
 manual page.
 .Pp
 A signal number of 0
-.Pq Li kill \-0 pid
-checks the validity of a certain PID, to see if it exists.
-An exit code of 0 means that the specified process exists.
+.Pq Nm kill Fl 0 Ar pid
+does not send a signal, but only checks the validity of a certain PID.
+It succeeds if
+.Ar pid
+exists or raises an error otherwise.
 .Sh EXIT STATUS
 .Ex -std kill
 .Sh EXAMPLES