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

Previous Next

Full log

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

Previous Next

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