Hi Benno, sorry for the late reply, but Jay was still waiting for my signed papers anyway (I hope it's done now).
On 02/10/2013 10:01 PM, Benno Schulenberg wrote: > On Fri, Feb 8, 2013, at 23:01, Bernhard Voelker wrote: >> Here's the fix. > > Looks good, except... I don't like the misalignment caused > by specifying optional arguments also for the short option. > Why not extend the introductory phrase to say: > > "Mandatory and optional arguments to long options are > also mandatory or optional for the short option.\n" > > Gnulib, glibc and tar, for example, use the following phrase: > > "Mandatory or optional arguments to long options are also > mandatory or optional for any corresponding short options." I slightly disagree - it's sometimes not so easy for the user to remember how mandatory and optional option's arguments have to be or can be passed. The following example illustrates this: -I R same as --replace=R (R must be specified) -i[R], --replace[=R] replace R in initial arguments with names read While R *can* be separated by a space from the -I option (i.e. mandatory), it *must* be passed without a space for the -i option (i.e. optional). Therefore, this reminds the user about how to do it correctly. You mentioned coreutils below - they're doing it like this. ;-) > In my opnion it is not necessary to say that square brackets > indicate optional arguments -- the reader has to know this > already in order to understand the synopsis. Removed. > And for --help and --version, why not use the standard ones > and put them at the end, like several coreutils and util-linux > commands start doing? Done, plus * splitted the "mandatory" sentence from the program description, * capitalized MAX-PROCS in the -P description as you noted in the other mail, * moved the equal sign into the square brackets: --replace[=R]. Attached you'll find the updated patch. Have a nice day, Berny
>From 170056035c64a2ef3a1fd6182dbf8649cb5ad539 Mon Sep 17 00:00:00 2001 From: Bernhard Voelker <[email protected]> Date: Mon, 25 Feb 2013 12:01:12 +0100 Subject: [PATCH] xargs: split usage text to help translators Smaller chunks are easier to handle for translators, ideally one msgid per option. Separate them. Fix -e option: optional arguments to short options cannot be separated by whitespace. Therefore, write "-e[END]" instead of the plain wrong "-e [END]". Similar, as the -i option has an optional argument, it must be listed as "-i[R]" instead of a bare "-i". In the long --replace option, the equal sign must go into the square brackets: --replace[=R]. In the description of the -P option, the MAX_PROCS argument must be capitalized. Clarify -l option: separate from -L to emphasize that MAX-LINES is optional for the -l option; therefore, mention the optional argument with the option as "-l[MAX-LINES]". Remove the general note about the meaning of square brackets - the reader has to know this already. * xargs/xargs.c (usage): Define HTL macro to print one help text line (or entry). Split the option descriptions up by using the above macro. Refine the messages to adapt to the common way: change the start of each option's description to lower case, do not use periods at the end, use semicolons where needed, indent secondary lines. Reported by Benno Schulenberg in http://lists.gnu.org/archive/html/bug-findutils/2013-02/msg00017.html --- xargs/xargs.c | 84 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/xargs/xargs.c b/xargs/xargs.c index 5fd93cd..a1f65ed 100644 --- a/xargs/xargs.c +++ b/xargs/xargs.c @@ -1584,46 +1584,46 @@ parse_num (char *str, int option, long int min, long int max, int fatal) static void usage (FILE *stream) { - fprintf (stream, _("\ -Usage: %s [OPTION]... COMMAND INITIAL-ARGS...\n\ -Run COMMAND with arguments INITIAL-ARGS and more arguments read from input.\n"), - program_name); - fprintf (stream, _("\n\ -Mandatory arguments to long options are mandatory for short options too.\n\ -Non-mandatory arguments are indicated by [square brackets]\n\ - -0, --null Items are separated by a null, not whitespace.\n\ - Disables quote and backslash processing\n\ - -a, --arg-file=FILE Read arguments from FILE, not standard input\n\ - -d, --delimiter=CHARACTER Input items are separated by CHARACTER, not by\n\ - blank space. Disables quote and backslash\n\ - processing\n\ - -E END If END occurs as a line of input, the rest of\n\ - the input is ignored.\n\ - -e [END], --eof[=END] Equivalent to -E END if END is specified.\n\ - Otherwise, there is no end-of-file string\n\ - --help Print a summary of the options to xargs.\n\ - -I R same as --replace=R (R must be specified)\n\ - -i,--replace=[R] Replace R in initial arguments with names\n\ - read from standard input. If R is\n\ - unspecified, assume {}\n\ - -L,-l, --max-lines=MAX-LINES Use at most MAX-LINES nonblank input lines per\n\ - command line\n\ - -l Use at most one nonblank input line per\n\ - command line\n\ - -n, --max-args=MAX-ARGS Use at most MAX-ARGS arguments per command\n\ - line\n\ - -P, --max-procs=MAX-PROCS Run up to max-procs processes at a time\n\ - -p, --interactive Prompt before running commands\n\ - --process-slot-var=VAR Set environment variable VAR in child\n\ - processes\n\ - -r, --no-run-if-empty If there are no arguments, run no command.\n\ - If this option is not given, COMMAND will be\n\ - run at least once.\n\ - -s, --max-chars=MAX-CHARS Limit commands to MAX-CHARS at most\n\ - --show-limits Show limits on command-line length.\n\ - -t, --verbose Print commands before executing them\n\ - --version Print the version number\n\ - -x, --exit Exit if the size (see -s) is exceeded\n\ -")); - fputs (_("\nReport bugs to <[email protected]>.\n"), stream); + fprintf (stream, + _("Usage: %s [OPTION]... COMMAND INITIAL-ARGS...\n"), + program_name); + +#define HTL(t) fputs (t, stream); + + HTL (_("Run COMMAND with arguments INITIAL-ARGS and more arguments read from input.\n" + "\n")); + HTL (_("Mandatory arguments to long options are mandatory for short options too.\n")); + HTL (_(" -0, --null items are separated by a null, not whitespace;\n" + " disables quote and backslash processing\n")); + HTL (_(" -a, --arg-file=FILE read arguments from FILE, not standard input\n")); + HTL (_(" -d, --delimiter=CHARACTER input items are separated by CHARACTER, not by\n" + " blank space; disables quote and backslash\n" + " processing\n")); + HTL (_(" -E END if END occurs as a line of input, the rest of\n" + " the input is ignored\n")); + HTL (_(" -e[END], --eof[=END] equivalent to -E END if END is specified;\n" + " otherwise, there is no end-of-file string\n")); + HTL (_(" -I R same as --replace=R (R must be specified)\n")); + HTL (_(" -i[R], --replace[=R] replace R in initial arguments with names read\n" + " from standard input; if R is unspecified,\n" + " assume {}\n")); + HTL (_(" -L, --max-lines=MAX-LINES use at most MAX-LINES nonblank input lines per\n" + " command line\n")); + HTL (_(" -l[MAX-LINES] similar to -L but defaults to at most one\n" + " nonblank input line if MAX-LINES not specified\n")); + HTL (_(" -n, --max-args=MAX-ARGS use at most MAX-ARGS arguments per command line\n")); + HTL (_(" -P, --max-procs=MAX-PROCS run up to MAX-PROCS processes at a time\n")); + HTL (_(" -p, --interactive prompt before running commands\n")); + HTL (_(" --process-slot-var=VAR set environment variable VAR in child processes\n")); + HTL (_(" -r, --no-run-if-empty if there are no arguments, run no command;\n" + " if this option is not given, COMMAND will be\n" + " run at least once\n")); + HTL (_(" -s, --max-chars=MAX-CHARS limit commands to MAX-CHARS at most\n")); + HTL (_(" --show-limits show limits on command-line length\n")); + HTL (_(" -t, --verbose print commands before executing them\n")); + HTL (_(" -x, --exit exit if the size (see -s) is exceeded\n")); + HTL (_(" --help print a summary of the options to xargs\n")); + HTL (_(" --version print the version number\n")); + HTL (_("\n" + "Report bugs to <[email protected]>.\n")); } -- 1.8.1.3.619.g7b6e784
