[pacman-dev] Question about the '-h' switch of pacman utils

[Karol Blazewicz]

I've noticed some commands provided by the pacman package have help
messages that could be improved. Is it something that already is on
some todo list?
What kind of suggestions are welcome and which ones draw ire of the
developers? Anyone cares about colons, dashes and capital letters?
There is a significant variability in style, in which the '-h' output
is presented and I'd appreciate standardizing this.


I think '$command_name -h' should provide s brief description of what
the command does and methods of use. At least in some cases an example
is very helpful.

For example, compare

$ pacsort -h
pacsort v4.1.1
Usage: pacsort [options] [files...]

<options listed here>

to

$ makepkg -h
makepkg (pacman) 4.1.1

Usage: /usr/bin/makepkg [options]

Options:
<listed here>

Hey, '$command_name ($package_name) $package_version' is a neat idea,
I like it much more than '$command_name v$package_version' style of
pacsort.
But ... what does makepkg do? I think it should explicitly say this.
It's a text file, so let's see what's inside:

$ head -3 /usr/bin/makepkg
#!/usr/bin/bash
#
#   makepkg - make packages compatible for use with pacman

OK, I think I get it.
pacsort is a binary, so what it does remains a secret ;P

What about the empty line between the command name and 'Usage' line?
Can we decide whether to add it to other pacman utilities' -h' output
or remove it from the ones that have it now? Is writing 'Options:'
necessary or can we just list them?

Some more examples can be found in the thread I opened on the forum:
https://bbs.archlinux.org/viewtopic.php?id=164943


I don't know if there's any interest among the developers in making
the -h' output (and later the man pages) better and if the ideas I
presented above do make it better in the eyes of those who matter or
it just nitpicking and fluff.

If you prefer less chatty and more formal style of writing, please tell me.