[pacman-dev] Question about the '-h' switch of pacman utils
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.
On Tue, Jun 11, 2013 at 11:23 AM, Karol Blazewicz <karol.blazewicz@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
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.
If you prefer less chatty and more formal style of writing, please tell me.
I prefer straight to the point (although with full details) so it takes me a little time as possible to read and understand the issue. Allan
On Sun, Jun 16, 2013 at 8:10 AM, Allan McRae <allan@archlinux.org> 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.
On Sun, Jun 23, 2013 at 11:36 PM, Karol Blazewicz <karol.blazewicz@gmail.com> wrote:
On Sun, Jun 16, 2013 at 8:10 AM, Allan McRae <allan@archlinux.org> 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.
Karol, yeah, I can do this. I'm a bit busy right now, so it may be a few days until I can send in a patch. Jason
participants (3)
-
Allan McRae
-
Jason St. John
-
Karol Blazewicz