[PATCH 1/2] textual: fix the usage message of kill

[PATCH 1/2] textual: fix the usage message of kill

[Benno Schulenberg]

Using angular brackets around each individual argument, indenting a
continuation line, not using a space before =, improving some wordings,
and the argument of --queue is a value (a piece of data), not a signal.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 misc-utils/kill.c |   20 ++++++++++----------
 1 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/misc-utils/kill.c b/misc-utils/kill.c
index 5d2f27d..f2362c3 100644
--- a/misc-utils/kill.c
+++ b/misc-utils/kill.c
@@ -303,17 +303,17 @@ static int arg_to_signum(char *arg, int maskbit)
 static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
-	fprintf(out, _(" %s [options] <pid|name>...\n"), program_invocation_short_name);
+	fprintf(out, _(" %s [options] <pid>|<name>...\n"), program_invocation_short_name);
 
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -a, --all              do not restrict the name-to-pid conversion to processes\n"
-		"                        with the same uid as the present process\n"), out);
-	fputs(_(" -s, --signal <sig>     send specified signal\n"), out);
+		"                          with the same uid as the present process\n"), out);
+	fputs(_(" -s, --signal <signal>  send this <signal> instead of SIGTERM\n"), out);
 #ifdef HAVE_SIGQUEUE
-	fputs(_(" -q, --queue <sig>      use sigqueue(2) rather than kill(2)\n"), out);
+	fputs(_(" -q, --queue <value>    use sigqueue(2), not kill(2), and pass <value> as data\n"), out);
 #endif
 	fputs(_(" -p, --pid              print pids without signaling them\n"), out);
-	fputs(_(" -l, --list [=<signal>] list signal names, or convert one to a name\n"), out);
+	fputs(_(" -l, --list[=<signal>]  list signal names, or convert a signal number to a name\n"), out);
 	fputs(_(" -L, --table            list signal names and numbers\n"), out);
 	fputs(_("     --verbose          print pids that will be signaled\n"), out);
 
@@ -423,15 +423,15 @@ static char **parse_arguments(int argc, char **argv, struct kill_control *ctl)
 		 * So it's probably something like -HUP, or -1/-n try to
 		 * deal with it.
 		 *
-		 * -n could be signal n, or pid -n (i.e., process group
-		 * number).  In case of doubt POSIX tells us to assume a
-		 * signal.  If a signal has been parsed, assume it is a
-		 * pid, break.  */
+		 * -n could be either signal n or pid -n (a process group
+		 * number).  In case of doubt, POSIX tells us to assume a
+		 * signal.  But if a signal has already been parsed, then
+		 * assume it is a process group, so stop parsing options. */
 		if (ctl->do_kill)
 			break;
 		arg++;
 		if ((ctl->numsig = arg_to_signum(arg, 0)) < 0)
-			errx(EXIT_FAILURE, _("invalid sigval argument"));
+			errx(EXIT_FAILURE, _("invalid signal name or number: %s"), arg);
 		ctl->do_kill = 1;
 		if (ctl->do_pid)
 			errx(EXIT_FAILURE, _("%s and %s are mutually exclusive"), "--pid", "--signal");
-- 
1.7.0.4

[PATCH 2/2] docs: fix many wording and some formatting issues in the man page of kill

[Benno Schulenberg]

Also, add the most-used form of '-signal' to the synopsis.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 misc-utils/kill.1 |  100 +++++++++++++++++++++++++++-------------------------
 1 files changed, 52 insertions(+), 48 deletions(-)

diff --git a/misc-utils/kill.1 b/misc-utils/kill.1
index dd1b1ee..0d430ef 100644
--- a/misc-utils/kill.1
+++ b/misc-utils/kill.1
@@ -1,40 +1,44 @@
 .\" Copyright 1994 Salvatore Valente (svalente@mit.edu)
 .\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)
 .\" May be distributed under the GNU General Public License
-.TH KILL 1 "March 2013" "util-linux" "User Commands"
+.TH KILL 1 "July 2014" "util-linux" "User Commands"
 .SH NAME
 kill \- terminate a process
 .SH SYNOPSIS
 .B kill
-.RB [ \-s
-.IR signal  | \fB\-p\fP ]
+.RB [ \- \fIsignal\fR| \-s
+.IR signal | \fB-p\fP ]
 .RB [ \-q
-.IR sigval ]
+.IR value ]
 .RB [ \-a ]
 .RB [ \-\- ]
-.IR pid|name ...
+.IR pid | name ...
 .br
-.B kill -l
-.RI [ signal ]
+.B kill \-l
+.RI [ number ]
+.RB "| " \-L
 .SH DESCRIPTION
 The command
 .B kill
-sends the specified signal to the specified process or process group.  If no
-signal is specified, the TERM signal is sent.  The TERM signal will kill
-processes which do not catch this signal.  For other processes, it may be
-necessary to use the KILL (9) signal, since this signal cannot be caught.
+sends the specified \fIsignal\fR to the specified processes or process groups.
+If no signal is specified, the TERM signal is sent.  This TERM signal will kill
+processes that do not catch it; for other processes it may be necessary to use
+the KILL signal (number 9), since this signal cannot be caught.
 .PP
 Most modern shells have a builtin kill function, with a usage rather similar to
-that of the command described here.  The \-\-all, \-\-pid, and \-\-queue options,
-and the possibility to specify processes by command name are a local extension.
+that of the command described here.  The
+.BR \-\-all ,
+.BR \-\-pid ", and"
+.BR \-\-queue
+options, and the possibility to specify processes by command name, are local extensions.
 .PP
-If sig is 0, then no signal is sent, but error checking is still performed.
-.SH OPTIONS
+If \fIsignal\fR is 0, then no actual signal is sent, but error checking is still performed.
+
+.SH ARGUMENTS
+The list of processes to be signaled can be a mixture of names and pids.
 .TP
-.IR pid ...
-Specify the list of processes that
-.B kill
-should signal.  Each
+.I pid
+Each
 .I pid
 can be one of four things:
 .RS
@@ -44,13 +48,13 @@ where
 .I n
 is larger than 0.  The process with pid
 .I n
-will be signaled.
+is signaled.
 .TP
 .B 0
 All processes in the current process group are signaled.
 .TP
 .B -1
-All processes with pid larger than 1 will be signaled.
+All processes with a pid larger than 1 are signaled.
 .TP
 .BI - n
 where
@@ -58,25 +62,26 @@ where
 is larger than 1.  All processes in process group
 .I n
 are signaled.  When an argument of the form '-n' is given, and it is meant to
-denote a process group, either the signal must be specified first, or the
+denote a process group, either a signal must be specified first, or the
 argument must be preceded by a '--' option, otherwise it will be taken as the
 signal to send.
 .RE
 .TP
 .I name
-All processes invoked using that name will be signaled.
+All processes invoked using this \fIname\fR will be signaled.
+
+.SH OPTIONS
 .TP
 \fB\-s\fR, \fB\-\-signal\fR \fIsignal\fR
-Specify the signal to send.  The signal may be given as a signal name or
-number.
+The signal to send.  It may be given as a name or a number.
 .TP
-\fB\-l\fR, \fB\-\-list\fR [\fIsignal\fR]
-Print a list of signal names, or convert signal given as argument to a name.
-The signals are found in
+\fB\-l\fR, \fB\-\-list\fR [\fInumber\fR]
+Print a list of signal names, or convert the given signal number to a name.
+The signals can be found in
 .I /usr/\:include/\:linux/\:signal.h
 .TP
 \fB\-L\fR, \fB\-\-table\fR
-Similar to \-l, but will print signal names and their corresponding
+Similar to \fB\-l\fR, but it will print signal names and their corresponding
 numbers.
 .TP
 \fB\-a\fR, \fB\-\-all\fR
@@ -84,47 +89,46 @@ Do not restrict the commandname-to-pid conversion to processes with the same
 uid as the present process.
 .TP
 \fB\-p\fR, \fB\-\-pid\fR
-Specify that
-.B kill
-should only print the process id (pid) of the named processes, and not send any
+Only print the process id (pid) of the named processes, do not send any
 signals.
 .IP
-The \-\-pid option functionality is also enabled when the command
-copied or linked to name
+The \fB\-\-pid\fR option is automatically enabled when the \fBkill\fR command
+is invoked with the name of
 .BR pid .
-This functionality is deprecated, and will not be removed in March 2016.
+This functionality is deprecated, and will be removed in March 2016.
 .TP
-\fB\-q\fR, \fB\-\-queue\fR \fIsigval\fR
+\fB\-q\fR, \fB\-\-queue\fR \fIvalue\fR
 Use
 .BR sigqueue (2)
 rather than
-.BR kill (2)
-and the
-.I sigval
-argument is used to specify an integer to be sent with the signal.  If the
+.BR kill (2).
+The
+.I value
+argument is an integer that is sent along with the signal.  If the
 receiving process has installed a handler for this signal using the SA_SIGINFO
 flag to
 .BR sigaction (2),
-then it can obtain this data via the si_value field of the siginfo_t structure.
+then it can obtain this data via the si_sigval field of the siginfo_t structure.
+
 .SH NOTES
-It is not possible to send a signal to explicitly selected thread in a
-multithreaded process by
+It is not possible to send a signal to an explicitly selected thread in a
+multithreaded process using the
 .BR kill (2)
 syscall.  If
 .BR kill(2)
-is used to send a signal to a thread group, then kernel selects arbitrary
+is used to send a signal to a thread group, then the kernel selects an arbitrary
 member of the thread group that has not blocked the signal.  For more details
 see
-.BR clone (2)
-CLONE_THREAD description.
+.BR clone (2),
+the CLONE_THREAD description.
 .PP
 The command
 .BR kill (1)
 as well as syscall
 .BR kill (2)
-accepts TID (thread ID, see
+accept a TID (thread ID, see
 .BR gettid (2))
-as argument.  In this case the kill behavior is not changed and the signal is
+as an argument.  In this case the kill behavior is not changed and the signal is
 also delivered to the thread group rather than to the specified thread.
 
 .SH RETURN CODES
-- 
1.7.0.4

Re: [PATCH 2/2] docs: fix many wording and some formatting issues in the man page of kill

[Karel Zak]

On Wed, Jul 09, 2014 at 03:29:10PM +0200, Benno Schulenberg wrote:
>  misc-utils/kill.1 |  100 +++++++++++++++++++++++++++-------------------------
>  1 files changed, 52 insertions(+), 48 deletions(-)

 Applied, thanks.

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 1/2] textual: fix the usage message of kill

[Karel Zak]

On Wed, Jul 09, 2014 at 03:29:09PM +0200, Benno Schulenberg wrote:
>  misc-utils/kill.c |   20 ++++++++++----------
>  1 files changed, 10 insertions(+), 10 deletions(-)

 I guess we want to merge this patch (that modifies already translated
 strings) after release, right?

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 1/2] textual: fix the usage message of kill

[Benno Schulenberg]

On Mon, Jul 14, 2014, at 15:48, Karel Zak wrote:
> On Wed, Jul 09, 2014 at 03:29:09PM +0200, Benno Schulenberg wrote:
> >  misc-utils/kill.c |   20 ++++++++++----------
> >  1 files changed, 10 insertions(+), 10 deletions(-)
> 
>  I guess we want to merge this patch (that modifies already translated
>  strings) after release, right?

Don't know...  Better do it now, so you can also apply Sami's patch
and have things working correctly.  Very few people will be using
this version of kill, so few will experience missing translations.

It's a pity that it invalidates already translated strings, but it
can't be helped.  It's kind of my fault; I should have had a look
at rc-1.

Benno

-- 
http://www.fastmail.fm - Faster than the air-speed velocity of an
                          unladen european swallow

Re: [PATCH 1/2] textual: fix the usage message of kill

[Karel Zak]

On Mon, Jul 14, 2014 at 03:55:09PM +0200, Benno Schulenberg wrote:
> 
> On Mon, Jul 14, 2014, at 15:48, Karel Zak wrote:
> > On Wed, Jul 09, 2014 at 03:29:09PM +0200, Benno Schulenberg wrote:
> > >  misc-utils/kill.c |   20 ++++++++++----------
> > >  1 files changed, 10 insertions(+), 10 deletions(-)
> > 
> >  I guess we want to merge this patch (that modifies already translated
> >  strings) after release, right?
> 
> Don't know...  Better do it now, so you can also apply Sami's patch
> and have things working correctly.  Very few people will be using
> this version of kill, so few will experience missing translations.

Well, procps version is deprecated in favour of kill(1) from u-l ;-)
(The built-in shell kill command is another story.)

> It's a pity that it invalidates already translated strings, but it
> can't be helped.  It's kind of my fault; I should have had a look
> at rc-1.

Yep, it would be nice to found a way how to solve this kind of problem
next time, almost always we have bug reports from translators, but
it's too late...

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 1/2] textual: fix the usage message of kill

[Benno Schulenberg]

On Mon, Jul 14, 2014, at 16:17, Karel Zak wrote:
> On Mon, Jul 14, 2014 at 03:55:09PM +0200, Benno Schulenberg wrote:
> > It's a pity that it invalidates already translated strings, but it
> > can't be helped.  It's kind of my fault; I should have had a look
> > at rc-1.
> 
> Yep, it would be nice to found a way how to solve this kind of problem
> next time, almost always we have bug reports from translators, but
> it's too late...

I had already kind of resolved that on the next rc1 I would
forward the POT file to a few of the more active translators,
and ask them to help look for errors and unclarities.  So with
a little luck, 2.26 will ship with several complete translations.

Benno

-- 
http://www.fastmail.fm - Choose from over 50 domains or use your own