Hi,
The first few patches remove two duplicate includes, tweak some
comments and usage strings, and normalizes another include.
The sixth patch adds a missing error message to ionice. And as the
usage text of ionice recently changed, the seventh patch seizes the
opportunity to slice it up, standardize its form, and improve some
of the descriptions.
The eighth patch tries to massage the usage howto into a better
grammatical shape.
Sami, there is one thing I changed: the square brackets around the
three dots, as that seems pleonastic to me, and the man-pages man page
suggests the bare three dots: see 'man 1 man' and search for "repeat".
Benno
--
http://www.fastmail.fm - Send your email first class
From 6eed20de0ddf39706ccef525ae98317054fc0967 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Mon, 28 Apr 2014 17:52:42 +0200
Subject: [PATCH 1/8] include/c: remove a duplicate include
Also tweak some comments.
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
include/c.h | 17 +++++++----------
1 files changed, 7 insertions(+), 10 deletions(-)
diff --git a/include/c.h b/include/c.h
index a192fb1..cf30b27 100644
--- a/include/c.h
+++ b/include/c.h
@@ -19,12 +19,8 @@
# include <err.h>
#endif
-#ifndef HAVE_USLEEP
-# include <time.h>
-#endif
-
/*
- * Compiler specific stuff
+ * Compiler-specific stuff
*/
#ifndef __GNUC_PREREQ
# if defined __GNUC__ && defined __GNUC_MINOR__
@@ -70,9 +66,10 @@
# endif
#endif
-/* Force a compilation error if condition is true, but also produce a
+/*
+ * Force a compilation error if condition is true, but also produce a
* result (of value 0 and type size_t), so the expression can be used
- * e.g. in a structure initializer (or where-ever else comma expressions
+ * e.g. in a structure initializer (or wherever else comma expressions
* aren't permitted).
*/
#define UL_BUILD_BUG_ON_ZERO(e) (sizeof(struct { int:-!!(e); }))
@@ -254,9 +251,9 @@ static inline size_t get_hostname_max(void)
}
/*
- * The usleep function is marked obsolete in POSIX.1-2001 and removed in
- * POSIX.1-2008. This is replaced with nanosleep() that provides more
- * advantages (like no interaction with signals and other timer functions.
+ * The usleep function was marked obsolete in POSIX.1-2001 and was removed
+ * in POSIX.1-2008. It was replaced with nanosleep() that provides more
+ * advantages (like no interaction with signals and other timer functions).
*/
#include <time.h>
--
1.7.0.4
From 65f46b06ed0004cfe66f67c04da66b0cd508e5a4 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Mon, 28 Apr 2014 18:08:42 +0200
Subject: [PATCH 2/8] include/carefulputc: remove a duplicate include
Also tweak a comment.
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
include/carefulputc.h | 9 +++++----
1 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/include/carefulputc.h b/include/carefulputc.h
index 2273028..f29dc69 100644
--- a/include/carefulputc.h
+++ b/include/carefulputc.h
@@ -1,11 +1,12 @@
#ifndef UTIL_LINUX_CAREFUULPUTC_H
#define UTIL_LINUX_CAREFUULPUTC_H
-/* putc() for use in write and wall (that sometimes are sgid tty) */
-/* Avoid control characters in our locale, and also ASCII control characters.
- Note that the locale of the recipient is unknown. */
+/*
+ * A putc() for use in write and wall (that sometimes are sgid tty).
+ * It avoids control characters in our locale, and also ASCII control
+ * characters. Note that the locale of the recipient is unknown.
+*/
#include <stdio.h>
-#include <ctype.h>
#include <string.h>
#include <ctype.h>
--
1.7.0.4
From 99ba5c9d3c052eddfe3df874c17045181e16ce9f Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Mon, 28 Apr 2014 18:10:38 +0200
Subject: [PATCH 3/8] lib/colors: change an include to a local one
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
lib/colors.c | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/lib/colors.c b/lib/colors.c
index 8b6f089..1950273 100644
--- a/lib/colors.c
+++ b/lib/colors.c
@@ -4,10 +4,10 @@
* This file may be distributed under the terms of the
* GNU Lesser General Public License.
*/
-#include <c.h>
#include <assert.h>
#include <sys/stat.h>
+#include "c.h"
#include "colors.h"
#include "xalloc.h"
#include "pathnames.h"
--
1.7.0.4
From aa224461804ee1d0615167b8f056952ef0fe4323 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Mon, 28 Apr 2014 18:15:00 +0200
Subject: [PATCH 4/8] include/c: do not gettextize a wordless string
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
include/c.h | 4 +++-
1 files changed, 3 insertions(+), 1 deletions(-)
diff --git a/include/c.h b/include/c.h
index cf30b27..c3378fd 100644
--- a/include/c.h
+++ b/include/c.h
@@ -278,7 +278,7 @@ static inline int xusleep(useconds_t usec)
*/
#define USAGE_HEADER _("\nUsage:\n")
#define USAGE_OPTIONS _("\nOptions:\n")
-#define USAGE_SEPARATOR _("\n")
+#define USAGE_SEPARATOR "\n"
#define USAGE_HELP _(" -h, --help display this help and exit\n")
#define USAGE_VERSION _(" -V, --version output version information and exit\n")
#define USAGE_MAN_TAIL(_man) _("\nFor more details see %s.\n"), _man
--
1.7.0.4
From 5610bed4f13d9b67c647c19b8f28647d58bdfe33 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Mon, 28 Apr 2014 23:12:41 +0200
Subject: [PATCH 5/8] ipcs: do not gettextize wordless strings
Also tweak a few parts of the usage message.
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
sys-utils/ipcs.c | 10 +++++-----
1 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/sys-utils/ipcs.c b/sys-utils/ipcs.c
index 90d6e0e..8ed5698 100644
--- a/sys-utils/ipcs.c
+++ b/sys-utils/ipcs.c
@@ -53,23 +53,23 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
fprintf(out, " %s [resource ...] [output-format]\n", program_invocation_short_name);
fprintf(out, " %s [resource] -i <id>\n", program_invocation_short_name);
fprintf(out, USAGE_OPTIONS);
- fputs(_(" -i, --id <id> print details on resource identified by id\n"), out);
+ fputs(_(" -i, --id <id> print details on resource identified by <id>\n"), out);
fprintf(out, USAGE_HELP);
fprintf(out, USAGE_VERSION);
- fputs(_("\n"), out);
+ fprintf(out, USAGE_SEPARATOR);
fputs(_("Resource options:\n"), out);
fputs(_(" -m, --shmems shared memory segments\n"), out);
fputs(_(" -q, --queues message queues\n"), out);
fputs(_(" -s, --semaphores semaphores\n"), out);
fputs(_(" -a, --all all (default)\n"), out);
- fputs(_("\n"), out);
+ fprintf(out, USAGE_SEPARATOR);
fputs(_("Output format:\n"), out);
fputs(_(" -t, --time show attach, detach and change times\n"), out);
- fputs(_(" -p, --pid show creator and last operations PIDs\n"), out);
+ fputs(_(" -p, --pid show PIDs of creator and last operator\n"), out);
fputs(_(" -c, --creator show creator and owner\n"), out);
fputs(_(" -l, --limits show resource limits\n"), out);
fputs(_(" -u, --summary show status summary\n"), out);
- fputs(_(" --human show sizes in human readable format\n"), out);
+ fputs(_(" --human show sizes in human-readable format\n"), out);
fputs(_(" -b, --bytes show sizes in bytes\n"), out);
fprintf(out, USAGE_MAN_TAIL("ipcs(1)"));
exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
--
1.7.0.4
From 025b7ac4bd9081c88224101c77abf6e6d6432f3e Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Tue, 29 Apr 2014 11:36:22 +0200
Subject: [PATCH 6/8] ionice: add a missing error message
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
schedutils/ionice.c | 1 +
1 files changed, 1 insertions(+), 0 deletions(-)
diff --git a/schedutils/ionice.c b/schedutils/ionice.c
index a3edf55..26b6d7c 100644
--- a/schedutils/ionice.c
+++ b/schedutils/ionice.c
@@ -188,6 +188,7 @@ int main(int argc, char **argv)
if (who)
errx(EXIT_FAILURE,
_("can handle one of pid, pgid or uid at once"));
+ invalid_msg = _("invalid UID argument");
which = strtos32_or_err(optarg, invalid_msg);
who = IOPRIO_WHO_USER;
break;
--
1.7.0.4
From a5396b96d24db290d433124de930289c3ad1ec53 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Tue, 29 Apr 2014 15:42:23 +0200
Subject: [PATCH 7/8] textual: slice up and standardize the usage text of ionice
Done for ease of translation and maintenance. Also improve the
clarity of some of the descriptions, and of one error message.
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
schedutils/ionice.c | 54 +++++++++++++++++++++++++-------------------------
1 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/schedutils/ionice.c b/schedutils/ionice.c
index 26b6d7c..fa43e48 100644
--- a/schedutils/ionice.c
+++ b/schedutils/ionice.c
@@ -100,28 +100,29 @@ static void ioprio_setid(int which, int ioclass, int data, int who)
static void __attribute__ ((__noreturn__)) usage(FILE * out)
{
- fprintf(out,
- _("\n"
- "%1$s - sets or gets process io scheduling class and priority.\n"
- "\n"
- "Usage:\n"
- " %1$s [OPTION] -p PID [PID...]\n"
- " %1$s [OPTION] -P PGID [PGID...]\n"
- " %1$s [OPTION] -u UID [UID...]\n"
- " %1$s [OPTION] COMMAND\n"
- "\n"
- "Options:\n"
- " -c, --class <class> scheduling class name or number\n"
- " 0: none, 1: realtime, 2: best-effort, 3: idle\n"
- " -n, --classdata <num> scheduling class data\n"
- " 0-7 for realtime and best-effort classes\n"
- " -p, --pid <pid> view or modify already running process\n"
- " -P, --pgid <pgrp> view or modify already running process group\n"
- " -t, --ignore ignore failures\n"
- " -u, --uid <uid> view or modify already running processes owned by a user\n"
- " -V, --version output version information and exit\n"
- " -h, --help display this help and exit\n\n"),
- program_invocation_short_name);
+ fputs(_("\nSets or gets the IO scheduling class and priority of processes.\n"), out);
+
+ fputs(USAGE_HEADER, out);
+ fprintf(out, _(" %1$s [options] -p <pid>...\n"
+ " %1$s [options] -P <pgid>...\n"
+ " %1$s [options] -u <uid>...\n"
+ " %1$s [options] <command>\n"), program_invocation_short_name);
+
+ fputs(USAGE_OPTIONS, out);
+ fputs(_(" -c, --class <class> name or number of scheduling class,\n"
+ " 0: none, 1: realtime, 2: best-effort, 3: idle\n"), out);
+ fputs(_(" -n, --classdata <num> priority (0..7) in the specified scheduling class,\n"
+ " only for the realtime and best-effort classes\n"), out);
+ fputs(_(" -p, --pid <pid>... act on these already running processes\n"), out);
+ fputs(_(" -P, --pgid <pgrp>... act on already running processes in these groups\n"), out);
+ fputs(_(" -t, --ignore ignore failures\n"), out);
+ fputs(_(" -u, --uid <uid>... act on already running processes owned by these users\n"), out);
+
+ fputs(USAGE_SEPARATOR, out);
+ fputs(USAGE_HELP, out);
+ fputs(USAGE_VERSION, out);
+
+ fprintf(out, USAGE_MAN_TAIL("ionice(1)"));
exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
}
@@ -171,7 +172,7 @@ int main(int argc, char **argv)
case 'p':
if (who)
errx(EXIT_FAILURE,
- _("can handle one of pid, pgid or uid at once"));
+ _("can handle only one of pid, pgid or uid at once"));
invalid_msg = _("invalid PID argument");
which = strtos32_or_err(optarg, invalid_msg);
who = IOPRIO_WHO_PROCESS;
@@ -179,7 +180,7 @@ int main(int argc, char **argv)
case 'P':
if (who)
errx(EXIT_FAILURE,
- _("can handle one of pid, pgid or uid at once"));
+ _("can handle only one of pid, pgid or uid at once"));
invalid_msg = _("invalid PGID argument");
which = strtos32_or_err(optarg, invalid_msg);
who = IOPRIO_WHO_PGRP;
@@ -187,7 +188,7 @@ int main(int argc, char **argv)
case 'u':
if (who)
errx(EXIT_FAILURE,
- _("can handle one of pid, pgid or uid at once"));
+ _("can handle only one of pid, pgid or uid at once"));
invalid_msg = _("invalid UID argument");
which = strtos32_or_err(optarg, invalid_msg);
who = IOPRIO_WHO_USER;
@@ -196,8 +197,7 @@ int main(int argc, char **argv)
tolerant = 1;
break;
case 'V':
- printf(_("%s from %s\n"),
- program_invocation_short_name, PACKAGE_STRING);
+ printf(UTIL_LINUX_VERSION);
return EXIT_SUCCESS;
case 'h':
usage(stdout);
--
1.7.0.4
From 2ba9e11055f94e907bcad4ecf4badf2633fdb44d Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
Date: Tue, 29 Apr 2014 17:33:04 +0200
Subject: [PATCH 8/8] docs: grammarize the usage howto
Signed-off-by: Benno Schulenberg <bensberg@xxxxxxxxxxxxx>
---
Documentation/howto-usage-function.txt | 158 ++++++++++++++++----------------
1 files changed, 78 insertions(+), 80 deletions(-)
diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index 4daa736..dd1f4ed 100644
--- a/Documentation/howto-usage-function.txt
+++ b/Documentation/howto-usage-function.txt
@@ -1,41 +1,41 @@
Well-known options
------------------
-Following options are well-known, and they should not be used for any
-other purpose.
+The following options are well-known, and should not be used for any
+other purpose:
-h, --help display usage and exit
-V, --version display version and exit
-Rule of thumb with other options is that once they exist you may not
-change how they work, or remove them.
+The rule of thumb with other options is that once they exist, you may
+not change them, nor change how they work, nor remove them.
-Notice that `-?' is not expected to be synonym of --help, but an unknown
-options resulting to a usage print out due getopt failure.
+Notice that '-?' is not expected to be a synonym of '--help', but is an
+unknown option resulting in a usage print-out due to a getopt failure.
-How usage is supposed to look
------------------------------
+How a usage text is supposed to look
+------------------------------------
-The usage output begins with empty line followed by `Usage:' and synopsis
-beginning on the next line. Synopsis and all other lines which vary are
-indented by one space (0x40).
+The usage output begins with an empty line, followed by 'Usage:', and
+then the synopsis on the line after that. The synopsis and option-
+description lines are all indented by one space (0x40).
-The synopsis line describes how to execute the command. Sometimes you may
-need multiple synopsis lines, this is documented separately under Synopsis
-title.
+The synopsis line describes how to compose the command. Sometimes you
+may need multiple synopsis lines -- this is documented separately in the
+Synopsis section.
-Notations; Diamond brackets markup an argument. Anything optional is
-marked with square brackets, such as optional command arguments, or
-optional option arguments. In the later case `=' character in front of
-the option argument, because one has to use it. Square brackets with
-three dots inside mean unlimited repetition of previous.
+Notations. Diamond brackets are used to mark an argument to be filled in.
+Square brackets are used to mark anything that is optional, such as optional
+command arguments, or optional option arguments. In the later case the '='
+character is needed in front of the option argument, because one has to use
+it. Three consecutive dots mean the unlimited repetition of the preceding.
-Short option are always written first followed by long option. Options are
-separated with comma and one space. Lonely short or long option do not
-affect where writing of the option begins.
+The short option is always written first, followed by the long option. They
+are separated with a comma and one space. Lonely short or long options do
+not affect where the writing of the option begins.
-Below, in between snips, is an example of how the usage output should
+Below, in between the snips, is an example of what the usage output should
look like.
-- snip
@@ -44,7 +44,6 @@ Usage:
program [options] <file> [...]
Options:
-
-n, --no-argument option does not use argument
-o, --optional[=<arg>] option argument is optional
-r, --required <arg> option requires an argument
@@ -54,7 +53,7 @@ Options:
use next line for description when needed
-l, --long-explanation an example of very verbose, and chatty option
description on two, or multiple lines, where the
- consecutive lines are intended by two spaces
+ continuation lines are indented by two spaces
-f, --foobar next option description resets indent
-h, --help display this help and exit
@@ -63,95 +62,94 @@ Options:
For more details see program(1).
-- snip
-Notice that there are usage function definitions in c.h include file
-which you must use. Location of example is mentioned at the end of this
-file.
+Note that there are usage-function definitions in the 'c.h' include file
+which you must use. The location of an example file is mentioned at the
+end of this text.
-Option description
-------------------
+Option descriptions
+-------------------
-Option description should not exceed width of 80 characters. If you need
-longer description use multiple lines and indentation.
+An option description should not exceed the width of 80 characters. If
+you need a longer description, use multiple lines and indentation.
-The description begins from the point of longest option plus two spaces.
-In case adding a new option would cause a description re-indentation
-need it either has to be done, or the new option should begin description
-from next line. Usually the later is better. The --help and --version
-will not follow this rule, since they are defined as constants to ease
-translation work.
+The description text begins from the point of the longest option plus two
+spaces. In case adding a new option would necessitate a re-indentation of
+the descriptions, it either has to be done, or the new option should begin
+its description on the next line. Usually the later is better. The --help
+and --version options do not follow this rule, since they are defined as
+constants to ease translation work.
-The argument, e.g. `arg', can be better. For example if an option is
-expecting number as argument a `num' is suitable argument description.
+An argument is preferably worded appropriately. For example, if an option
+expects a number as argument, '<num>' is a suitable argument indicator.
-Order of the options has no special meaning, with a exception of --help and
---version which are expected to be last ones of the list.
+The order of the options has no special meaning, with the exception of
+--help and --version which are expected to be last ones in the list.
-Last line of the usage print out is either empty, or a message informing
-about manual page. For example: `For more details see example(1).' In
-between man page message and options there is empty line.
+The last line of the usage text is either empty, or a message informing
+about the manual page. For example: 'For more details see example(1).'.
+Between the options and the man-page message there is an empty line.
Usage function
--------------
-Standard usage function takes either stderr or stdout as an argument. The
-argument will determine whether the program will exit with error or
-success. Usage function will never return.
+The standard usage() function takes either stderr or stdout as an argument.
+The argument will determine whether the program will exit with an error or
+with success. The usage() function will never return.
-In the code all strings with options have to start at the same position. See
-bellow what that means.
+In the code all the strings with options have to start at the same position.
+See here what this means:
fprintf(out, _(" -x[=<foo>] default foo is %s"), x);
fputs( _(" -y some text"), out);
-Be nice to translators. One gettext entry should be one option, no more,
-no less. For example:
+Be nice to translators. One gettext entry should be one option, no more,
+no less. For example:
fputs(_(" --you-there be nice\n"), out);
fputs(_(" -2 <whom> translators\n"), out);
- fputs(_(" -t, --hey are doing job that we probably cannot,"
+ fputs(_(" -t, --hey are doing a job that we probably cannot,"
" or how is your klingon?\n"), out);
-When existing usage output is changed, and it happens to be one big
-output, split it to chunks size of an option. The extra work for
-translators will pay off at the time of the next change when they do not
-need to search from fuzzy markup what has changed, where, how, and was it
-the only change.
+When existing usage output is changed, and it happens to be one big text,
+split it into chunks the size of one option. The extra work this will
+entail for translators will pay off later, at the time of the next change,
+when they will not need to search in the long fuzzy text what was changed,
+where, how, and whether it was the only change.
Synopsis
--------
-You may need to use multiple synopsis lines to tell that a command does
-fundamentally different things depending on options and/or arguments. For
-example ionice either changes priority of a running command, or executes
-a program with a defined priority. Therefore it is reasonable to have two
-synopsis lines.
+You may need to use multiple synopsis lines to show that a command does
+fundamentally different things depending on options and/or arguments.
+For example, ionice either changes the priority of a running command, or
+executes a program with a defined priority. Therefore it is reasonable
+to have two synopsis lines:
- ionice [options] -p <pid> [...]
- ionice [options] <command> [<args>] [...]
+ ionice [options] -p <pid> ...
+ ionice [options] <command> [<arg> ...]
-Notice that the synopsis is not meant to be repetition of options segment.
-The fundamental difference in execution is a bit difficult to define
-other than usually command author, package maintainer or patch submitter
-will know when it should be done that way.
+Note that the synopsis is not meant to be a repetition of the options
+segment. The fundamental difference in execution is a bit difficult to
+define other than that usually the command author, package maintainer
+or patch submitter will know when it should be done that way.
Legacy options
--------------
-Some commands use peculiar options and arguments. These are supported,
-but such will not be accepted in future. See list bellow for a hint what
-are meant this.
+Some commands use peculiar options and arguments. These will continue
+to be supported, but anything like them will not be accepted as new
+additions. A short list of examples:
-- Other than `-' used to define an option. See `+' for `more'
- commands.
-- Option string used as an option argument. See `more' command and `-num'.
-- Short long option. See `setterm'.
+- Other characters than '-' to start an option. See '+' in 'more'.
+- Using a number as an option argument. See '-<number>' in 'more'.
+- Long options that start with a single '-'. See 'setterm'.
-Example
--------
+Example file
+------------
-Command disk-utils/delpart.c is a minimal example how to do write usage
-function, setup option parsing, version printing and so on.
+The file disk-utils/delpart.c is a minimal example of how to write
+a usage function, set up option parsing, version printing and so on.
--
1.7.0.4
