llvm dev - Jun 2019 - Short aliases in help text

Hi all,

GNU binary tools list both their long and short form aliases in
command-line help text, but by default, LLVM tools using the cl::opt
interface only show the "main" form, which is usually the long-form.
It is
possible to override this behaviour, but it is not that common to do so in
many tools. In some tools, there's a mixture of behaviour between the two.
I'd like to propose changing the default behaviour of cl::alias to not hide
the short switch, or even better, find a way to wrap them into a single
help text entry like GNU tools do.

Example GNU nm --help snippet:
-a, --debug-syms       Display debugger-only symbols

Equivalent llvm-nm output:
--debug-syms      - Show all symbols, even debugger only

Example llvm-readelf output:
-l                           - Alias for --program-headers
<lots of other options...>
--program-headers            - Display ELF program headers

These are just some examples. I'm sure there is (was?) a reason that
aliases were hidden by default, but doing so can make it hard for people
who are more familiar with short options, and lead to lots of unnecessary
typing.

Thoughts?

James
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190610/c858da46/attachment.html>

Heavy +1 in favor of changing --help so it automatically combines
alias+flag together. Perhaps that's one of the reasons aliases are hidden
by default; so they don't clutter --help. If aliases are provided w/ their
command, there's very little added clutter.

--help lists "-a, --debug-syms" but man pages list it as
"[-a|--debug-syms]". I think either (or something else entirely) is
fine.

On Mon, Jun 10, 2019 at 10:12 AM James Henderson via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> Hi all,
>
> GNU binary tools list both their long and short form aliases in
> command-line help text, but by default, LLVM tools using the cl::opt
> interface only show the "main" form, which is usually the
long-form. It is
> possible to override this behaviour, but it is not that common to do so in
> many tools. In some tools, there's a mixture of behaviour between the
two.
> I'd like to propose changing the default behaviour of cl::alias to not
hide
> the short switch, or even better, find a way to wrap them into a single
> help text entry like GNU tools do.
>
> Example GNU nm --help snippet:
> -a, --debug-syms       Display debugger-only symbols
>
> Equivalent llvm-nm output:
> --debug-syms      - Show all symbols, even debugger only
>
> Example llvm-readelf output:
> -l                           - Alias for --program-headers
> <lots of other options...>
> --program-headers            - Display ELF program headers
>
> These are just some examples. I'm sure there is (was?) a reason that
> aliases were hidden by default, but doing so can make it hard for people
> who are more familiar with short options, and lead to lots of unnecessary
> typing.
>
> Thoughts?
>
> James
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190610/e22aeafd/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4849 bytes
Desc: S/MIME Cryptographic Signature
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190610/e22aeafd/attachment-0001.bin>