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

[Jason St. John]

On Tue, Jun 11, 2013 at 11:23 AM, Karol Blazewicz
<karol.blazewicz at gmail.com> 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