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

Previous Next

Full log

View this message in rfc822 format

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: 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

Previous Next

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