On Tue, Jun 11, 2013 at 11:23 AM, Karol Blazewicz wrote:

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.

Some standardization in this area would be nice. If the developers approve of changing this, I'm willing to send in some patches to address these issues. Jason

On Sun, Jun 16, 2013 at 8:10 AM, Allan McRae wrote:

On 11/06/13 19:23, Karol Blazewicz wrote: <snip>

...

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.

I would be fine with adding a short description to the --help output.

Jason St. John, do you want to do this? I'm not a native English speaker, so things might go smoother if you do it. If you're not interested, I'll start working on the patches.