GNU bug report logs - #44248
Indentation of --help and --version

Previous Next

To reply to this bug, email your comments to 44248 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Roland Illig <roland.illig <at> gmx.de>
To: bug-coreutils <at> gnu.org
Subject: Indentation of --help and --version
Date: Tue, 27 Oct 2020 01:03:19 +0100

Hi,

As the German translator of coreutils, I fixed the indentation of the
--help output today, for coreutils 8.31.90.  While doing that, I noticed
that the option "-z, --zero-terminated" is used by several programs that
have different "native" indentation widths.  Therefore their --help
output looks inconsistent.  The affected programs are: join shuf sort
uniq.  Could you perhaps give each of these programs its own message,
properly indented to match the other options?

I also noticed that the --help and --version strings are only translated
once, which is good as it saved me some boring work.  But they are
indented at a different width than the other options.  Some of the
programs add an empty line before the --help and --version lines, which
looks ok.  Several others do not add a line, which looks wrong.  This
should be consistent among all coreutils.

In src/cat.c:115, the German translation for the first example takes 2
lines instead of 1.  The second line should be aligned nicely with the
first line, but there's no way to know beforehand how long the %s from
the first line will be, since the program name may be prefixed with "g"
or "gnu-" or pretty much any other string.  What is the correct way of
solving this problem?

Roland

Message #8 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Roland Illig <roland.illig <at> gmx.de>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Mon, 26 Oct 2020 19:19:10 -0700

[Message part 1 (text/plain, inline)]

One way to attack the problem is (1) use only one-liners for option help, and 
(2) not worry about indentation so much (either in English or in German) as the 
excess indenting doesn't help readability enough to justify the translation 
hassle. To do that, I propose changes like the attached for comm. This will 
cause 'comm --help' output to look like the following, which is good enough and 
which will still work with help2man:

Usage: comm [OPTION]... FILE1 FILE2
Compare sorted files FILE1 and FILE2 line by line.

When FILE1 or FILE2 (not both) is -, read standard input.

With no options, produce three-column output.  Column one contains
lines unique to FILE1, column two contains lines unique to FILE2,
and column three contains lines common to both files.

  -1  suppress column 1 (lines unique to FILE1)
  -2  suppress column 2 (lines unique to FILE2)
  -3  suppress column 3 (lines that appear in both files)

  --check-order  check that the input is correctly sorted
  --nocheck-order  do not check that the input is correctly sorted
  --output-delimiter=STR  separate columns with STR
  --total  output a summary
  -z, --zero-terminated  line delimiter is NUL, not newline
      --help     display this help and exit
      --version  output version information and exit

Note, comparisons honor the rules specified by 'LC_COLLATE'.

Examples:
  comm -12 file1 file2  Print only lines present in both file1 and file2.
  comm -3 file1 file2  Print lines in file1 not in file2, and vice versa.

GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
Full documentation <https://www.gnu.org/software/coreutils/comm>
or available locally via: info '(coreutils) comm invocation'

[coreutils-comm-help.diff (text/x-patch, attachment)]

Message #11 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Roland Illig <roland.illig <at> gmx.de>, 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Tue, 27 Oct 2020 14:13:50 +0000

[Message part 1 (text/plain, inline)]

On 27/10/2020 00:03, Roland Illig wrote:
> Hi,
 > Some of the programs add an empty line before the --help and --version lines, which
> looks ok.  Several others do not add a line, which looks wrong.  This
> should be consistent among all coreutils.

I agree we should make things as consistent as possible.
Though most utils do _not_ have a blank line before --help,--version.
The following utils do have a blank line:

$ ./build-aux/gen-lists-of-programs.sh --list-progs | while read p; do
  src/$p --help | grep -B1 -- --help | grep -q '^$' && echo $p; done | fmt

arch coreutils hostname hostid uptime users [ b2sum base64 base32 chcon
chgrp chown cksum dd expr factor false link logname md5sum nohup printf
realpath runcon sha1sum sha224sum sha256sum sha384sum sha512sum sleep
true tsort unlink whoami yes

Of those above, those that also have other options are:

base64 chcon chgrp chown md5sum realpath runcon

Now chcon, chgrp, chown, md5sum discuss the options before --help,--version
as a group and so a blank line is best there.
Therefore to improve consistency we should remove the blank line from:
base64, realpath, and runcon, which is done in the attached.

cheers,
Pádraig

[help-blank.patch (text/x-patch, attachment)]

Message #14 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Roland Illig <roland.illig <at> gmx.de>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Tue, 27 Oct 2020 14:15:03 +0000

On 27/10/2020 02:19, Paul Eggert wrote:
> One way to attack the problem is (1) use only one-liners for option help, and
> (2) not worry about indentation so much (either in English or in German) as the
> excess indenting doesn't help readability enough to justify the translation
> hassle. To do that, I propose changes like the attached for comm. This will
> cause 'comm --help' output to look like the following, which is good enough and
> which will still work with help2man:
> 
> Usage: comm [OPTION]... FILE1 FILE2
> Compare sorted files FILE1 and FILE2 line by line.
> 
> When FILE1 or FILE2 (not both) is -, read standard input.
> 
> With no options, produce three-column output.  Column one contains
> lines unique to FILE1, column two contains lines unique to FILE2,
> and column three contains lines common to both files.
> 
>     -1  suppress column 1 (lines unique to FILE1)
>     -2  suppress column 2 (lines unique to FILE2)
>     -3  suppress column 3 (lines that appear in both files)
> 
>     --check-order  check that the input is correctly sorted
>     --nocheck-order  do not check that the input is correctly sorted
>     --output-delimiter=STR  separate columns with STR
>     --total  output a summary
>     -z, --zero-terminated  line delimiter is NUL, not newline
>         --help     display this help and exit
>         --version  output version information and exit
> 
> Note, comparisons honor the rules specified by 'LC_COLLATE'.
> 
> Examples:
>     comm -12 file1 file2  Print only lines present in both file1 and file2.
>     comm -3 file1 file2  Print lines in file1 not in file2, and vice versa.

I feel using only one liners for all utils would lose too much information.

I feel less strongly about removing indentation,
though do feel we would lose reability.
Consider `ls --help` for example.
comm --help is already quite unreadable and so less
affected by such changes.

Also a mass change like this could invalidate existing translations,
and cause too much churn.

We did discuss a long time ago that a mass change
to warrant the churn would be to split each
option to a separate string, i.e. a separate translation.
Also that we could take advantage of the mbsalign module
to more dynamically align the option description.


cheers,
Pádraig

Message #17 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>,
 Paul Eggert <eggert <at> cs.ucla.edu>, Roland Illig <roland.illig <at> gmx.de>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Wed, 28 Oct 2020 21:55:22 +0100

On 10/27/20 3:15 PM, Pádraig Brady wrote:
> On 27/10/2020 02:19, Paul Eggert wrote:
>> One way to attack the problem is (1) use only one-liners for option help, and
>> (2) not worry about indentation so much (either in English or in German) as the
>> excess indenting doesn't help readability enough to justify the translation
>> hassle. To do that, I propose changes like the attached for comm. This will
>> cause 'comm --help' output to look like the following, which is good enough and
>> which will still work with help2man:

>>     --check-order  check that the input is correctly sorted
>>     --nocheck-order  do not check that the input is correctly sorted
>>     --output-delimiter=STR  separate columns with STR
>>     --total  output a summary
>>     -z, --zero-terminated  line delimiter is NUL, not newline
>>         --help     display this help and exit
>>         --version  output version information and exit

> I feel using only one liners for all utils would lose too much information.

I think this "unaligned" output is hard to read, and we'd get a lot
of either negative feedback or fixup patches.

> Also a mass change like this could invalidate existing translations,
> and cause too much churn.
> 
> We did discuss a long time ago that a mass change
> to warrant the churn would be to split each
> option to a separate string, i.e. a separate translation.
> Also that we could take advantage of the mbsalign module
> to more dynamically align the option description.

We have so many utils that it may be worth writing some utility functions
to automatically do the alignment.  Usually, that part of the usage output
has 3 columns:
a) the short option (if any),
b) the long option (if any),
c) the description (maybe multiline).

E.g. for ls.c:usage:
   usage_param("-a", "--all", _("do not ignore entries starting with ."));
   ...
   usage_param(NULL, "--dereference-command-line-symlink-to-dir",
                     _("follow each command line symbolic link\n"
                       "that points to a directory"));
  usage_param_help();
  usage_param_version();
and a final:
  usage_param_finish();

The usage_param calls would aggregate the text - suitable for translators -, and
the final usage_param_finish() would then calculate the width of column a) and b),
and the description text of column c) could be output directly ... possibly warning
if any of the chunks until '\n' would grow excessively large.

Could something like that be a possible way out of the mass change for the translators?

Have a nice day,
Berny

Message #20 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Paul Eggert <eggert <at> cs.ucla.edu>, Roland Illig <roland.illig <at> gmx.de>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Wed, 28 Oct 2020 21:28:53 +0000

On 28/10/2020 20:55, Bernhard Voelker wrote:
> On 10/27/20 3:15 PM, Pádraig Brady wrote:
>> On 27/10/2020 02:19, Paul Eggert wrote:
>>> One way to attack the problem is (1) use only one-liners for option help, and
>>> (2) not worry about indentation so much (either in English or in German) as the
>>> excess indenting doesn't help readability enough to justify the translation
>>> hassle. To do that, I propose changes like the attached for comm. This will
>>> cause 'comm --help' output to look like the following, which is good enough and
>>> which will still work with help2man:
> 
>>>      --check-order  check that the input is correctly sorted
>>>      --nocheck-order  do not check that the input is correctly sorted
>>>      --output-delimiter=STR  separate columns with STR
>>>      --total  output a summary
>>>      -z, --zero-terminated  line delimiter is NUL, not newline
>>>          --help     display this help and exit
>>>          --version  output version information and exit
> 
>> I feel using only one liners for all utils would lose too much information.
> 
> I think this "unaligned" output is hard to read, and we'd get a lot
> of either negative feedback or fixup patches.
> 
>> Also a mass change like this could invalidate existing translations,
>> and cause too much churn.
>>
>> We did discuss a long time ago that a mass change
>> to warrant the churn would be to split each
>> option to a separate string, i.e. a separate translation.
>> Also that we could take advantage of the mbsalign module
>> to more dynamically align the option description.
> 
> We have so many utils that it may be worth writing some utility functions
> to automatically do the alignment.  Usually, that part of the usage output
> has 3 columns:
> a) the short option (if any),
> b) the long option (if any),
> c) the description (maybe multiline).
> 
> E.g. for ls.c:usage:
>      usage_param("-a", "--all", _("do not ignore entries starting with ."));
>      ...
>      usage_param(NULL, "--dereference-command-line-symlink-to-dir",
>                        _("follow each command line symbolic link\n"
>                          "that points to a directory"));
>     usage_param_help();
>     usage_param_version();
> and a final:
>     usage_param_finish();
> 
> The usage_param calls would aggregate the text - suitable for translators -, and
> the final usage_param_finish() would then calculate the width of column a) and b),
> and the description text of column c) could be output directly ... possibly warning
> if any of the chunks until '\n' would grow excessively large.
> 
> Could something like that be a possible way out of the mass change for the translators?

Right that's what I was thinking with the alignment of the description.

Having separate strings to translate, that don't have to
deal with spacing or alignment etc. are generally easier
to handle for translators (though there will be churn
in the transition to this model).

I'll have a go at this for the next release I think,
as the next release will probably be a major version bump anyway,
due to fundamental default changes to how cp (--reflink=auto) is handled for example.

cheers,
Pádraig

Message #23 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Roland Illig <roland.illig <at> gmx.de>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>,
 Pádraig Brady <P <at> draigBrady.com>,
 Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Thu, 29 Oct 2020 22:25:43 +0100

On 28.10.2020 21:55, Bernhard Voelker wrote:
> We have so many utils that it may be worth writing some utility functions
> to automatically do the alignment.  Usually, that part of the usage output
> has 3 columns:
> a) the short option (if any),
> b) the long option (if any),
> c) the description (maybe multiline).

I completely agree. This would be nice to have, both for users and for
translators.

> E.g. for ls.c:usage:
>     usage_param("-a", "--all", _("do not ignore entries starting with ."));
>     ...
>     usage_param(NULL, "--dereference-command-line-symlink-to-dir",
>                       _("follow each command line symbolic link\n"
>                         "that points to a directory"));
>    usage_param_help();
>    usage_param_version();
> and a final:
>    usage_param_finish();

This code adds a bit of redundancy.  The relation between -a and --all
is already expressed when setting up the getopt_long.  It is repeated here.

Ideally there would be a single definition from which both the
getopt_long options and the --help string are derived.  Some prior art
can be found at https://golang.org/pkg/flag/.

I don't like the hard line break in the option description.  The line
breaks should be computed based on the terminal size or a fixed line
width.  It's not possible to predict the screen column in which in the
option description will start, since that depends on the names of the
other options.  Therefore, the option descriptions should be wrapped as
necessary.  See fold(1).

Roland

Message #26 received at 44248 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Roland Illig <roland.illig <at> gmx.de>,
 Bernhard Voelker <mail <at> bernhard-voelker.de>, Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 44248 <at> debbugs.gnu.org
Subject: Re: bug#44248: Indentation of --help and --version
Date: Thu, 29 Oct 2020 21:50:12 +0000

On 29/10/2020 21:25, Roland Illig wrote:
> On 28.10.2020 21:55, Bernhard Voelker wrote:
>> We have so many utils that it may be worth writing some utility functions
>> to automatically do the alignment.  Usually, that part of the usage output
>> has 3 columns:
>> a) the short option (if any),
>> b) the long option (if any),
>> c) the description (maybe multiline).
> 
> I completely agree. This would be nice to have, both for users and for
> translators.
> 
>> E.g. for ls.c:usage:
>>      usage_param("-a", "--all", _("do not ignore entries starting with ."));
>>      ...
>>      usage_param(NULL, "--dereference-command-line-symlink-to-dir",
>>                        _("follow each command line symbolic link\n"
>>                          "that points to a directory"));
>>     usage_param_help();
>>     usage_param_version();
>> and a final:
>>     usage_param_finish();
> 
> This code adds a bit of redundancy.  The relation between -a and --all
> is already expressed when setting up the getopt_long.  It is repeated here.
> 
> Ideally there would be a single definition from which both the
> getopt_long options and the --help string are derived.  Some prior art
> can be found at https://golang.org/pkg/flag/.

Maybe, though I don't want to over engineer anything here.
We're not going to be adding new options that often.

> I don't like the hard line break in the option description.  The line
> breaks should be computed based on the terminal size or a fixed line
> width.  It's not possible to predict the screen column in which in the
> option description will start, since that depends on the names of the
> other options.  Therefore, the option descriptions should be wrapped as
> necessary.  See fold(1).

Yes agreed.

Spacing or alignment should not need consideration for translators.
That includes line feeds.

We probably should provide some context to translators also like:
/* TRANSLATORS: --dereference-command-line-symlink-to-dir option  */

cheers,
Pádraig

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.