[PATCH 00/14]: usage() fixes for translators

[PATCH 00/14]: usage() fixes for translators

[Sami Kerola]

The first patch, and it's comment, tells why the rest exist.  The usage()
outputs I chose to split has changed since previous release (2.22.2), so
they are becoming fuzzy to translators.

[PATCH 01/14] docs: usage function and gettext

[Sami Kerola]

I made following survey which was sent to all email addresses in po/
directory that had the on-going millenium as time when translator had
been active.

  There are two quite common styles to write a command usage print out,
  which one you prefer?

  1. Each option as separated translatable string.	18 votes
  2. Or the whole thing as one big output.		 1 vote
  3. No preference.					 1 vote

The questionaire had also free text field asking 'Why do you prefer
that?', and here are the answers.

  [Separately] It is easier to follow changes with the translations.  If
  you change only one line or two, the big string would change to fuzzy
  and I have to check the whole thing to see what was changed in the
  original.  If the changed line is a single string, the string to check
  is a lot shorter.

  [No preference] Usually, if there is no reason to separate strings,
  better keep them together so that the context is obvious.  In the case at
  hand, it might help if in some language e.g.  one translated line is too
  wide for the screen.  This is unlikely, but...  OTOH, with this solution,
  if you change one string the whole translation will be discarded until a
  translator comes and updates it...

  [Separately] It may be a bit harder to get the formatting right, but it
  is much easier in maintenance.  With one option changing, the
  translator immediately sees the spot.  And even with a lazy translator,
  program author will have all the options translated that have not
  changed at all.

  [Separately] First one would be more in elegant I believe

  [Separately] I prefer to have them separately because they don't form a
  single text paragraph.  In other words, they can be translated
  separately because they are complete and separate "sentences".  Of
  course consistency of format and word choices need to be taken care of,
  but the fact that the messages appear next to each other in the PO file
  should be enough.  Also if the options are not translated separately,
  adding or editing one option causes the translation of all options to
  become fuzzy and if for some reason it isn't checked before next
  release (happens sometimes), all of them will show untranslated to the
  user.

  [Separately] Translations are a lot easier to update that way.  If an
  option is added, removed or changed, only a small amount of text
  becomes fuzzy.  If everything is in one big output, a lot of text
  becomes fuzzy, and you have to read a lot more text to discover what
  exactly changed.

  [Separately] When updating a fuzzy translation, with one big output
  it's very tedious and error-prone to find out the reason for fuzziness,
  i.e.  what actually has changed in the msgid.

  [Separately] Way easier to translate, and especially to spot
  translation updates when one string gets removed, added or modified.

  [Separately] Makes translation memory more efficient.  Some hard terms
  in the list don't prevent translation of the whole block.  Actually the
  beginning of the strings don't need any translation ta all before []
  part.  Information about the context can be provided in comments or the
  context parameter.

  [Separately] Please consider the case when a part of string, (= msgid)
  is changed.  It is marked as fuzzy in the .po files, we translators
  have to check whole sentences for the difference between it and
  previous version.

  [Separately] Every sentence must be a separate translation unit.

  [One big output] for performance to ouput strings

  [Separately] In the second case, if only one option changes (or a new
  one is added), the translator will see as if all of the options
  changed, having to find out which one of them is really new or has
  actually changed.  Also, if the translator has had no time to update
  the string, only one of the options will be shown in the original
  language (which is arguably ugly, but better than nothing for many
  users).

  [Separately] It's easier to translate the options separately using
  translation memory.

  [Separately] Easier to separate and see changes

  [Separately] more translator friendly

  [Separately] From the user POV I found the separeted version more
  interesting because if a maintainer can't update the translation fast
  enough between releases the user will still get the current translated
  string with the new ones untraslated.  From the translator POV the big
  output will give more context information as one can see the whole
  command options.  With a new string added while the rest is translated
  having some context can be more difficult.

  [Separately] Additions to the list or changes to one options means you
  don't have to check all lines each time.

So unless you have very, _very_ good reason you should not output all
usage as one big table.  This implies also that when large usage output
is changed it should be split to small hunks.  That may be a bit more
work once, but the next change will pay the extrawork off so never
hesitate when splitting.

Reference: http://www.surveymonkey.com/s/QKZ75HK
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 Documentation/howto-usage-function.txt | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index 1944bb7..371ff32 100644
--- a/Documentation/howto-usage-function.txt
+++ b/Documentation/howto-usage-function.txt
@@ -105,9 +105,19 @@ bellow what that means.
 	fprintf(out, _(" -x[=<foo>]  default foo is %s"), x);
 	fputs(       _(" -y          some text"), out);
 
-The usage output should be split to manageable chunks, in practice one or
-few lines.
-
+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,"
+		"                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.
 
 Synopsis
 --------
-- 
1.8.1.1

[PATCH 02/14] nsenter: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/nsenter.c | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/sys-utils/nsenter.c b/sys-utils/nsenter.c
index 0a4985c..c16b8d1 100644
--- a/sys-utils/nsenter.c
+++ b/sys-utils/nsenter.c
@@ -64,17 +64,17 @@ static void usage(int status)
 		program_invocation_short_name);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -t, --target <pid>     target process to get namespaces from\n"
-		" -m, --mount [=<file>]  enter mount namespace\n"
-		" -u, --uts   [=<file>]  enter UTS namespace (hostname etc)\n"
-		" -i, --ipc   [=<file>]  enter System V IPC namespace\n"
-		" -n, --net   [=<file>]  enter network namespace\n"
-		" -p, --pid   [=<file>]  enter pid namespace\n"
-		" -U, --user  [=<file>]  enter user namespace\n"
-		" -r, --root  [=<dir>]   set the root directory\n"
-		" -w, --wd    [=<dir>]   set the working directory\n"
-		" -a, --all              set root and cwd and enter namespaces listed above\n"
-		" -F, --no-fork          don't fork before exec'ing <program>\n"), out);
+	fputs(_(" -t, --target <pid>     target process to get namespaces from\n"), out);
+	fputs(_(" -m, --mount [=<file>]  enter mount namespace\n"), out);
+	fputs(_(" -u, --uts   [=<file>]  enter UTS namespace (hostname etc)\n"), out);
+	fputs(_(" -i, --ipc   [=<file>]  enter System V IPC namespace\n"), out);
+	fputs(_(" -n, --net   [=<file>]  enter network namespace\n"), out);
+	fputs(_(" -p, --pid   [=<file>]  enter pid namespace\n"), out);
+	fputs(_(" -U, --user  [=<file>]  enter user namespace\n"), out);
+	fputs(_(" -r, --root  [=<dir>]   set the root directory\n"), out);
+	fputs(_(" -w, --wd    [=<dir>]   set the working directory\n"), out);
+	fputs(_(" -a, --all              set root and cwd and enter namespaces listed above\n"), out);
+	fputs(_(" -F, --no-fork          do not fork before exec'ing <program>\n"), out);
 	fputs(USAGE_SEPARATOR, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
-- 
1.8.1.1

[PATCH 03/14] partx: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 disk-utils/partx.c | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/disk-utils/partx.c b/disk-utils/partx.c
index 45bf773..9fa9587 100644
--- a/disk-utils/partx.c
+++ b/disk-utils/partx.c
@@ -704,19 +704,19 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 		program_invocation_short_name);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -a, --add            add specified partitions or all of them\n"
-		" -d, --delete         delete specified partitions or all of them\n"
-		" -l, --list           list partitions (DEPRECATED)\n"
-		" -s, --show           list partitions\n\n"
-		" -u, --update         update specified partitions or all of them\n"
-		" -b, --bytes          print SIZE in bytes rather than in human readable format\n"
-		" -g, --noheadings     don't print headings for --show\n"
-		" -n, --nr <n:m>       specify the range of partitions (e.g. --nr 2:4)\n"
-		" -o, --output <type>  define which output columns to use\n"
-		" -P, --pairs          use key=\"value\" output format\n"
-		" -r, --raw            use raw output format\n"
-		" -t, --type <type>    specify the partition type (dos, bsd, solaris, etc.)\n"
-		" -v, --verbose        verbose mode\n"), out);
+	fputs(_(" -a, --add            add specified partitions or all of them\n"), out);
+	fputs(_(" -d, --delete         delete specified partitions or all of them\n"), out);
+	fputs(_(" -l, --list           list partitions (DEPRECATED)\n"), out);
+	fputs(_(" -s, --show           list partitions\n\n"), out);
+	fputs(_(" -u, --update         update specified partitions or all of them\n"), out);
+	fputs(_(" -b, --bytes          print SIZE in bytes rather than in human readable format\n"), out);
+	fputs(_(" -g, --noheadings     don't print headings for --show\n"), out);
+	fputs(_(" -n, --nr <n:m>       specify the range of partitions (e.g. --nr 2:4)\n"), out);
+	fputs(_(" -o, --output <type>  define which output columns to use\n"), out);
+	fputs(_(" -P, --pairs          use key=\"value\" output format\n"), out);
+	fputs(_(" -r, --raw            use raw output format\n"), out);
+	fputs(_(" -t, --type <type>    specify the partition type (dos, bsd, solaris, etc.)\n"), out);
+	fputs(_(" -v, --verbose        verbose mode\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(USAGE_HELP, out);
-- 
1.8.1.1

[PATCH 04/14] su-common: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 login-utils/su-common.c | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/login-utils/su-common.c b/login-utils/su-common.c
index 9daae72..47e05ff 100644
--- a/login-utils/su-common.c
+++ b/login-utils/su-common.c
@@ -646,18 +646,16 @@ usage (int status)
     fputs(USAGE_OPTIONS, stdout);
   }
 
-  fputs (_(
-    " -m, -p, --preserve-environment  do not reset environment variables\n"
-    " -g, --group <group>             specify the primary group\n"
-    " -G, --supp-group <group>        specify a supplemental group\n\n"), stdout);
-
-  fputs (_(
-    " -, -l, --login                  make the shell a login shell\n"
-    " -c, --command <command>         pass a single command to the shell with -c\n"
-    " --session-command <command>     pass a single command to the shell with -c\n"
-    "                                 and do not create a new session\n"
-    " -f, --fast                      pass -f to the shell (for csh or tcsh)\n"
-    " -s, --shell <shell>             run shell if /etc/shells allows it\n"), stdout);
+  fputs (_(" -m, -p, --preserve-environment  do not reset environment variables\n"), stdout);
+  fputs (_(" -g, --group <group>             specify the primary group\n"), stdout);
+  fputs (_(" -G, --supp-group <group>        specify a supplemental group\n\n"), stdout);
+
+  fputs (_(" -, -l, --login                  make the shell a login shell\n"), stdout);
+  fputs (_(" -c, --command <command>         pass a single command to the shell with -c\n"), stdout);
+  fputs (_(" --session-command <command>     pass a single command to the shell with -c\n"), stdout);
+  fputs (_("                                 and do not create a new session\n"), stdout);
+  fputs (_(" -f, --fast                      pass -f to the shell (for csh or tcsh)\n"), stdout);
+  fputs (_(" -s, --shell <shell>             run shell if /etc/shells allows it\n"), stdout);
 
   fputs(USAGE_SEPARATOR, stdout);
   fputs(USAGE_HELP, stdout);
-- 
1.8.1.1

[PATCH 05/14] findmnt: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 misc-utils/findmnt.c | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index f6c864f..3089cce 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -1050,12 +1050,11 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	" -N, --task <tid>       use alternative namespace (/proc/<tid>/mountinfo file)\n"
 	" -n, --noheadings       don't print column headings\n"
 	" -u, --notruncate       don't truncate text in columns\n"));
-	fprintf(out, _(
-	" -O, --options <list>   limit the set of filesystems by mount options\n"
-	" -o, --output <list>    the output columns to be shown\n"
-	" -P, --pairs            use key=\"value\" output format\n"
-	" -r, --raw              use raw output format\n"
-	" -t, --types <list>     limit the set of filesystems by FS types\n"));
+fputs (_(" -O, --options <list>   limit the set of filesystems by mount options\n"), out);
+fputs (_(" -o, --output <list>    the output columns to be shown\n"), out);
+fputs (_(" -P, --pairs            use key=\"value\" output format\n"), out);
+fputs (_(" -r, --raw              use raw output format\n"), out);
+fputs (_(" -t, --types <list>     limit the set of filesystems by FS types\n"), out);
 	fprintf(out, _(
 	" -v, --nofsroot         don't print [/dir] for bind or btrfs mounts\n"
 	" -R, --submounts        print all submounts for the matching filesystems\n"
-- 
1.8.1.1

[PATCH 06/14] lsblk: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 misc-utils/lsblk.c | 49 ++++++++++++++++++++++++-------------------------
 1 file changed, 24 insertions(+), 25 deletions(-)

diff --git a/misc-utils/lsblk.c b/misc-utils/lsblk.c
index 8ee6974..a9674c1 100644
--- a/misc-utils/lsblk.c
+++ b/misc-utils/lsblk.c
@@ -1325,31 +1325,30 @@ static void __attribute__((__noreturn__)) help(FILE *out)
 {
 	size_t i;
 
-	fprintf(out, _(
-		"\nUsage:\n"
-		" %s [options] [<device> ...]\n"), program_invocation_short_name);
-
-	fprintf(out, _(
-		"\nOptions:\n"
-		" -a, --all            print all devices\n"
-		" -b, --bytes          print SIZE in bytes rather than in human readable format\n"
-		" -d, --nodeps         don't print slaves or holders\n"
-		" -D, --discard        print discard capabilities\n"
-		" -e, --exclude <list> exclude devices by major number (default: RAM disks)\n"
-		" -I, --include <list> show only devices with specified major numbers\n"
-		" -f, --fs             output info about filesystems\n"
-		" -h, --help           usage information (this)\n"
-		" -i, --ascii          use ascii characters only\n"
-		" -m, --perms          output info about permissions\n"
-		" -l, --list           use list format output\n"
-		" -n, --noheadings     don't print headings\n"
-		" -o, --output <list>  output columns\n"
-		" -P, --pairs          use key=\"value\" output format\n"
-		" -r, --raw            use raw output format\n"
-		" -s, --inverse        inverse dependencies\n"
-		" -t, --topology       output info about topology\n"
-		" -S, --scsi           output info about SCSI devices\n"
-		" -V, --version        output version information and exit\n"));
+	fputs(USAGE_HEADER, out);
+	fprintf(out, _(" %s [options] [<device> ...]\n"), program_invocation_short_name);
+	fputs(USAGE_OPTIONS, out);
+	fputs(_(" -a, --all            print all devices\n"), out);
+	fputs(_(" -b, --bytes          print SIZE in bytes rather than in human readable format\n"), out);
+	fputs(_(" -d, --nodeps         don't print slaves or holders\n"), out);
+	fputs(_(" -D, --discard        print discard capabilities\n"), out);
+	fputs(_(" -e, --exclude <list> exclude devices by major number (default: RAM disks)\n"), out);
+	fputs(_(" -I, --include <list> show only devices with specified major numbers\n"), out);
+	fputs(_(" -f, --fs             output info about filesystems\n"), out);
+	fputs(_(" -h, --help           usage information (this)\n"), out);
+	fputs(_(" -i, --ascii          use ascii characters only\n"), out);
+	fputs(_(" -m, --perms          output info about permissions\n"), out);
+	fputs(_(" -l, --list           use list format output\n"), out);
+	fputs(_(" -n, --noheadings     don't print headings\n"), out);
+	fputs(_(" -o, --output <list>  output columns\n"), out);
+	fputs(_(" -P, --pairs          use key=\"value\" output format\n"), out);
+	fputs(_(" -r, --raw            use raw output format\n"), out);
+	fputs(_(" -s, --inverse        inverse dependencies\n"), out);
+	fputs(_(" -t, --topology       output info about topology\n"), out);
+	fputs(_(" -S, --scsi           output info about SCSI devices\n"), out);
+	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_HELP, out);
+	fputs(USAGE_VERSION, out);
 
 	fprintf(out, _("\nAvailable columns (for --output):\n"));
 
-- 
1.8.1.1

[PATCH 07/14] rename: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 misc-utils/rename.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/misc-utils/rename.c b/misc-utils/rename.c
index 21bd522..a36caec 100644
--- a/misc-utils/rename.c
+++ b/misc-utils/rename.c
@@ -95,17 +95,17 @@ static int do_rename(char *from, char *to, char *s, int verbose, int symtarget)
 
 static void __attribute__ ((__noreturn__)) usage(FILE * out)
 {
-	fputs(_("\nUsage:\n"), out);
+	fputs(USAGE_HEADER, out);
 	fprintf(out,
 	      _(" %s [options] expression replacement file...\n"),
 		program_invocation_short_name);
-
-	fputs(_("\nOptions:\n"), out);
-	fputs(_(" -v, --verbose    explain what is being done\n"
-		" -V, --version    output version information and exit\n"
-		" -s, --symlink    act on symlink target\n"
-		" -h, --help       display this help and exit\n\n"), out);
-
+	fputs(USAGE_OPTIONS, out);
+	fputs(_(" -v, --verbose    explain what is being done\n"), out);
+	fputs(_(" -s, --symlink    act on symlink target\n"), out);
+	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_HELP, out);
+	fputs(USAGE_VERSION, out);
+	fprintf(out, USAGE_MAN_TAIL("rename(1)"));
 	exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
 }
 
-- 
1.8.1.1

[PATCH 08/14] dmesg: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/dmesg.c | 75 ++++++++++++++++++++++++++-----------------------------
 1 file changed, 35 insertions(+), 40 deletions(-)

diff --git a/sys-utils/dmesg.c b/sys-utils/dmesg.c
index f95db40..14c3e18 100644
--- a/sys-utils/dmesg.c
+++ b/sys-utils/dmesg.c
@@ -198,51 +198,46 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	size_t i;
 
-	fputs(_("\nUsage:\n"), out);
-	fprintf(out,
-	      _(" %s [options]\n"), program_invocation_short_name);
-
-	fputs(_("\nOptions:\n"), out);
-	fputs(_(" -C, --clear                 clear the kernel ring buffer\n"
-		" -c, --read-clear            read and clear all messages\n"
-		" -D, --console-off           disable printing messages to console\n"
-		" -d, --show-delta            show time delta between printed messages\n"
-		" -e, --reltime               show local time and time delta in readable format\n"
-		" -E, --console-on            enable printing messages to console\n"
-		" -F, --file <file>           use the file instead of the kernel log buffer\n"
-		" -f, --facility <list>       restrict output to defined facilities\n"
-		" -h, --help                  display this help and exit\n"
-		" -k, --kernel                display kernel messages\n"
-		" -L, --color                 colorize messages\n"
-		" -l, --level <list>          restrict output to defined levels\n"
-		" -n, --console-level <level> set level of messages printed to console\n"
-		" -r, --raw                   print the raw message buffer\n"
-		" -S, --syslog                force to use syslog(2) rather than /dev/kmsg\n"
-		" -s, --buffer-size <size>    buffer size to query the kernel ring buffer\n"
-		" -T, --ctime                 show human readable timestamp (could be \n"
-		"                             inaccurate if you have used SUSPEND/RESUME)\n"
-		" -t, --notime                don't print messages timestamp\n"
-		" -u, --userspace             display userspace messages\n"
-		" -V, --version               output version information and exit\n"
-		" -w, --follow                wait for new messages\n"
-		" -x, --decode                decode facility and level to readable string\n"), out);
-
+	fputs(USAGE_HEADER, out);
+	fprintf(out, _(" %s [options]\n"), program_invocation_short_name);
+	fputs(USAGE_OPTIONS, out);
+	fputs(_(" -C, --clear                 clear the kernel ring buffer\n"), out);
+	fputs(_(" -c, --read-clear            read and clear all messages\n"), out);
+	fputs(_(" -D, --console-off           disable printing messages to console\n"), out);
+	fputs(_(" -d, --show-delta            show time delta between printed messages\n"), out);
+	fputs(_(" -e, --reltime               show local time and time delta in readable format\n"), out);
+	fputs(_(" -E, --console-on            enable printing messages to console\n"), out);
+	fputs(_(" -F, --file <file>           use the file instead of the kernel log buffer\n"), out);
+	fputs(_(" -f, --facility <list>       restrict output to defined facilities\n"), out);
+	fputs(_(" -k, --kernel                display kernel messages\n"), out);
+	fputs(_(" -L, --color                 colorize messages\n"), out);
+	fputs(_(" -l, --level <list>          restrict output to defined levels\n"), out);
+	fputs(_(" -n, --console-level <level> set level of messages printed to console\n"), out);
+	fputs(_(" -r, --raw                   print the raw message buffer\n"), out);
+	fputs(_(" -S, --syslog                force to use syslog(2) rather than /dev/kmsg\n"), out);
+	fputs(_(" -s, --buffer-size <size>    buffer size to query the kernel ring buffer\n"), out);
+	fputs(_(" -T, --ctime                 show human readable timestamp (could be \n"
+		"                               inaccurate if you have used SUSPEND/RESUME)\n"), out);
+	fputs(_(" -t, --notime                don't print messages timestamp\n"), out);
+	fputs(_(" -u, --userspace             display userspace messages\n"), out);
+	fputs(_(" -w, --follow                wait for new messages\n"), out);
+	fputs(_(" -x, --decode                decode facility and level to readable string\n"), out);
+	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_HELP, out);
+	fputs(USAGE_VERSION, out);
 	fputs(_("\nSupported log facilities:\n"), out);
-	for (i = 0; i < ARRAY_SIZE(level_names); i++) {
+	for (i = 0; i < ARRAY_SIZE(level_names); i++)
 		fprintf(stderr, " %7s - %s\n",
-				facility_names[i].name,
-				_(facility_names[i].help));
-	}
+			facility_names[i].name,
+			_(facility_names[i].help));
 
 	fputs(_("\nSupported log levels (priorities):\n"), out);
-	for (i = 0; i < ARRAY_SIZE(level_names); i++) {
+	for (i = 0; i < ARRAY_SIZE(level_names); i++)
 		fprintf(stderr, " %7s - %s\n",
-				level_names[i].name,
-				_(level_names[i].help));
-	}
-
-	fputc('\n', out);
-
+			level_names[i].name,
+			_(level_names[i].help));
+	fputc(USAGE_SEPARATOR, out);
+	fprintf(out, USAGE_MAN_TAIL("dmesg(q)"));
 	exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
 }
 
-- 
1.8.1.1

[PATCH 09/14] hwclock: make usage() change translator friendly

[Sami Kerola]

The --compare option from 83765871ef0d6c554c46027577648b77c7351a78 is
made to be separate fputs() line.

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/hwclock.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 04aa650..c7c14df 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1443,8 +1443,8 @@ static void usage(const char *fmt, ...)
 		" -w, --systohc        set the hardware clock from the current system time\n"
 		"     --systz          set the system time based on the current timezone\n"
 		"     --adjust         adjust the RTC to account for systematic drift since\n"
-		"                        the clock was last set or adjusted\n"
-		" -c, --compare        periodically compare the system clock with the CMOS clock\n"), usageto);
+		"                        the clock was last set or adjusted\n"), usageto);
+	fputs(_(" -c, --compare        periodically compare the system clock with the CMOS clock\n"), usageto);
 #ifdef __linux__
 	fputs(_("     --getepoch       print out the kernel's hardware clock epoch value\n"
 		"     --setepoch       set the kernel's hardware clock epoch value to the \n"
-- 
1.8.1.1

[PATCH 10/14] losetup: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/losetup.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/sys-utils/losetup.c b/sys-utils/losetup.c
index 2c81e69..45e46c8 100644
--- a/sys-utils/losetup.c
+++ b/sys-utils/losetup.c
@@ -360,14 +360,14 @@ static void usage(FILE *out)
 		" -j, --associated <file>       list all devices associated with <file>\n"), out);
 	fputs(USAGE_SEPARATOR, out);
 
-	fputs(_(" -l, --list                    list info about all or specified\n"
-		" -o, --offset <num>            start at offset <num> into file\n"
-		" -O, --output <cols>           specify columns to output for --list\n"
-		"     --sizelimit <num>         device limited to <num> bytes of the file\n"
-		" -P, --partscan                create partitioned loop device\n"
-		" -r, --read-only               setup read-only loop device\n"
-		"     --show                    print device name after setup (with -f)\n"
-		" -v, --verbose                 verbose mode\n"), out);
+	fputs(_(" -l, --list                    list info about all or specified\n"), out);
+	fputs(_(" -o, --offset <num>            start at offset <num> into file\n"), out);
+	fputs(_(" -O, --output <cols>           specify columns to output for --list\n"), out);
+	fputs(_("     --sizelimit <num>         device limited to <num> bytes of the file\n"), out);
+	fputs(_(" -P, --partscan                create partitioned loop device\n"), out);
+	fputs(_(" -r, --read-only               setup read-only loop device\n"), out);
+	fputs(_("     --show                    print device name after setup (with -f)\n"), out);
+	fputs(_(" -v, --verbose                 verbose mode\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(USAGE_HELP, out);
-- 
1.8.1.1

[PATCH 11/14] umount: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/umount.c | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/sys-utils/umount.c b/sys-utils/umount.c
index 396052c..e5a8650 100644
--- a/sys-utils/umount.c
+++ b/sys-utils/umount.c
@@ -78,22 +78,19 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 		program_invocation_short_name);
 
 	fputs(USAGE_OPTIONS, out);
-	fprintf(out, _(
-	" -a, --all               umount all filesystems\n"
-	" -c, --no-canonicalize   don't canonicalize paths\n"
-	" -d, --detach-loop       if mounted loop device, also free this loop device\n"
-	"     --fake              dry run; skip the umount(2) syscall\n"
-	" -f, --force             force unmount (in case of an unreachable NFS system)\n"));
-	fprintf(out, _(
-	" -i, --internal-only     don't call the umount.<type> helpers\n"
-	" -n, --no-mtab           don't write to /etc/mtab\n"
-	" -l, --lazy              detach the filesystem now, and cleanup all later\n"));
-	fprintf(out, _(
-	" -O, --test-opts <list>  limit the set of filesystems (use with -a)\n"
-	" -R, --recursive         recursively unmount a target with all its children\n"
-	" -r, --read-only         In case unmounting fails, try to remount read-only\n"
-	" -t, --types <list>      limit the set of filesystem types\n"
-	" -v, --verbose           say what is being done\n"));
+	fputs(_(" -a, --all               umount all filesystems\n"), out);
+	fputs(_(" -c, --no-canonicalize   don't canonicalize paths\n"), out);
+	fputs(_(" -d, --detach-loop       if mounted loop device, also free this loop device\n"), out);
+	fputs(_("     --fake              dry run; skip the umount(2) syscall\n"), out);
+	fputs(_(" -f, --force             force unmount (in case of an unreachable NFS system)\n"), out);
+	fputs(_(" -i, --internal-only     don't call the umount.<type> helpers\n"), out);
+	fputs(_(" -n, --no-mtab           don't write to /etc/mtab\n"), out);
+	fputs(_(" -l, --lazy              detach the filesystem now, and cleanup all later\n"), out);
+	fputs(_(" -O, --test-opts <list>  limit the set of filesystems (use with -a)\n"), out);
+	fputs(_(" -R, --recursive         recursively unmount a target with all its children\n"), out);
+	fputs(_(" -r, --read-only         In case unmounting fails, try to remount read-only\n"), out);
+	fputs(_(" -t, --types <list>      limit the set of filesystem types\n"), out);
+	fputs(_(" -v, --verbose           say what is being done\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(USAGE_HELP, out);
-- 
1.8.1.1

[PATCH 12/14] unshare: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 sys-utils/unshare.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c
index c891cb5..804c882 100644
--- a/sys-utils/unshare.c
+++ b/sys-utils/unshare.c
@@ -39,12 +39,12 @@ static void usage(int status)
 	      _(" %s [options] <program> [args...]\n"),	program_invocation_short_name);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -m, --mount       unshare mounts namespace\n"
-		" -u, --uts         unshare UTS namespace (hostname etc)\n"
-		" -i, --ipc         unshare System V IPC namespace\n"
-		" -n, --net         unshare network namespace\n"
-		" -p, --pid         unshare pid namespace\n"
-		" -U, --user        unshare user namespace\n"), out);
+	fputs(_(" -m, --mount       unshare mounts namespace\n"), out);
+	fputs(_(" -u, --uts         unshare UTS namespace (hostname etc)\n"), out);
+	fputs(_(" -i, --ipc         unshare System V IPC namespace\n"), out);
+	fputs(_(" -n, --net         unshare network namespace\n"), out);
+	fputs(_(" -p, --pid         unshare pid namespace\n"), out);
+	fputs(_(" -U, --user        unshare user namespace\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(USAGE_HELP, out);
-- 
1.8.1.1

[PATCH 13/14] agetty: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 term-utils/agetty.c | 70 ++++++++++++++++++++++++++---------------------------
 1 file changed, 35 insertions(+), 35 deletions(-)

diff --git a/term-utils/agetty.c b/term-utils/agetty.c
index ed97bc5..2f2c019 100644
--- a/term-utils/agetty.c
+++ b/term-utils/agetty.c
@@ -1629,42 +1629,42 @@ static speed_t bcode(char *s)
 	return 0;
 }
 
-static void __attribute__ ((__noreturn__)) usage(FILE * out)
+static void __attribute__ ((__noreturn__)) usage(FILE *out)
 {
-	fprintf(out, _("\nUsage:\n"
-		       " %1$s [options] line baud_rate,... [termtype]\n"
-		       " %1$s [options] baud_rate,... line [termtype]\n"),
-		program_invocation_short_name);
-
-	fprintf(out, _("\nOptions:\n"
-		       " -8, --8bits                assume 8-bit tty\n"
-		       " -a, --autologin <user>     login the specified user automatically\n"
-		       " -c, --noreset              do not reset control mode\n"
-		       " -f, --issue-file <file>    display issue file\n"
-		       " -h, --flow-control         enable hardware flow control\n"
-		       " -H, --host <hostname>      specify login host\n"
-		       " -i, --noissue              do not display issue file\n"
-		       " -I, --init-string <string> set init string\n"
-		       " -l, --login-program <file> specify login program\n"
-		       " -L, --local-line           force local line\n"
-		       " -m, --extract-baud         extract baud rate during connect\n"
-		       " -n, --skip-login           do not prompt for login\n"
-		       " -o, --login-options <opts> options that are passed to login\n"
-		       " -p, --loginpause           wait for any key before the login\n"
-		       " -R, --hangup               do virtually hangup on the tty\n"
-		       " -s, --keep-baud            try to keep baud rate after break\n"
-		       " -t, --timeout <number>     login process timeout\n"
-		       " -U, --detect-case          detect uppercase terminal\n"
-		       " -w, --wait-cr              wait carriage-return\n"
-		       "     --noclear              do not clear the screen before prompt\n"
-		       "     --nohints              do not print hints\n"
-		       "     --nonewline            do not print a newline before issue\n"
-		       "     --no-hostname          no hostname at all will be shown\n"
-		       "     --long-hostname        show full qualified hostname\n"
-		       "     --erase-chars <string> additional backspace chars\n"
-		       "     --kill-chars <string>  additional kill chars\n"
-		       "     --version              output version information and exit\n"
-		       "     --help                 display this help and exit\n\n"));
+	fputs(USAGE_HEADER, out);
+	fprintf(out, _(" %1$s [options] line baud_rate,... [termtype]\n"
+		       " %1$s [options] baud_rate,... line [termtype]\n"), program_invocation_short_name);
+	fputs(USAGE_OPTIONS, out);
+	fputs(_(" -8, --8bits                assume 8-bit tty\n"), out);
+	fputs(_(" -a, --autologin <user>     login the specified user automatically\n"), out);
+	fputs(_(" -c, --noreset              do not reset control mode\n"), out);
+	fputs(_(" -f, --issue-file <file>    display issue file\n"), out);
+	fputs(_(" -h, --flow-control         enable hardware flow control\n"), out);
+	fputs(_(" -H, --host <hostname>      specify login host\n"), out);
+	fputs(_(" -i, --noissue              do not display issue file\n"), out);
+	fputs(_(" -I, --init-string <string> set init string\n"), out);
+	fputs(_(" -l, --login-program <file> specify login program\n"), out);
+	fputs(_(" -L, --local-line           force local line\n"), out);
+	fputs(_(" -m, --extract-baud         extract baud rate during connect\n"), out);
+	fputs(_(" -n, --skip-login           do not prompt for login\n"), out);
+	fputs(_(" -o, --login-options <opts> options that are passed to login\n"), out);
+	fputs(_(" -p, --loginpause           wait for any key before the login\n"), out);
+	fputs(_(" -R, --hangup               do virtually hangup on the tty\n"), out);
+	fputs(_(" -s, --keep-baud            try to keep baud rate after break\n"), out);
+	fputs(_(" -t, --timeout <number>     login process timeout\n"), out);
+	fputs(_(" -U, --detect-case          detect uppercase terminal\n"), out);
+	fputs(_(" -w, --wait-cr              wait carriage-return\n"), out);
+	fputs(_("     --noclear              do not clear the screen before prompt\n"), out);
+	fputs(_("     --nohints              do not print hints\n"), out);
+	fputs(_("     --nonewline            do not print a newline before issue\n"), out);
+	fputs(_("     --no-hostname          no hostname at all will be shown\n"), out);
+	fputs(_("     --long-hostname        show full qualified hostname\n"), out);
+	fputs(_("     --erase-chars <string> additional backspace chars\n"), out);
+	fputs(_("     --kill-chars <string>  additional kill chars\n"), out);
+	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_HELP, out);
+	fputs(USAGE_VERSION, out);
+	fprintf(out, USAGE_MAN_TAIL("agetty(8)"));
 
 	exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
 }
-- 
1.8.1.1

[PATCH 14/14] column: make usage() translator friendly

[Sami Kerola]

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
---
 text-utils/column.c | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/text-utils/column.c b/text-utils/column.c
index 33bc28d..1f1a0a2 100644
--- a/text-utils/column.c
+++ b/text-utils/column.c
@@ -88,21 +88,20 @@ static void __attribute__((__noreturn__)) usage(int rc)
 {
 	FILE *out = rc == EXIT_FAILURE ? stderr : stdout;
 
-	fprintf(out, _("\nUsage: %s [options] [file ...]\n"),
-				program_invocation_short_name);
-	fprintf(out, _("\nOptions:\n"));
-
-	fprintf(out, _(
-	" -h, --help               displays this help text\n"
-	" -V, --version            output version information and exit\n"
-	" -c, --columns <width>    width of output in number of characters\n"
-	" -t, --table              create a table\n"
-	" -s, --separator <string> possible table delimiters\n"
-	" -o, --output-separator <string>\n"
-	"                          table output column separator, default is two spaces\n"
-	" -x, --fillrows           fill rows before columns\n"));
-
-	fprintf(out, _("\nFor more information see column(1).\n"));
+	fputs(USAGE_HEADER, out);
+	fprintf(out, _(" %s [options] [file ...]\n"), program_invocation_short_name);
+	fputs(USAGE_OPTIONS, out);
+	fputs(_(" -c, --columns <width>    width of output in number of characters\n"), out);
+	fputs(_(" -t, --table              create a table\n"), out);
+	fputs(_(" -s, --separator <string> possible table delimiters\n"), out);
+	fputs(_(" -o, --output-separator <string>\n"), out);
+	fputs(_("                          table output column separator, default is two spaces\n"), out);
+	fputs(_(" -x, --fillrows           fill rows before columns\n"), out);
+	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_HELP, out);
+	fputs(USAGE_VERSION, out);
+	fprintf(out, USAGE_MAN_TAIL("column(1)"));
+
 	exit(rc);
 }
 
-- 
1.8.1.1

Re: [PATCH 00/14]: usage() fixes for translators

[Karel Zak]

On Tue, Jan 22, 2013 at 11:26:59PM +0000, Sami Kerola wrote:
> The first patch, and it's comment, tells why the rest exist.  The usage()
> outputs I chose to split has changed since previous release (2.22.2), so
> they are becoming fuzzy to translators.

 Applied, thanks.

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