Command help messages could use more content

[GoogleCodeExporter]

The command help messages include the 'Usage' and 'Options' sections, but have 
no summary of the function of that command. At the least it would be helpful to 
copy the one-line summary over from the main `beet help` message for each 
command.

Ideally there could eventually be more detailed summaries and/or a link to the 
relevant page(s) in the online beets documentation.

I appreciate that this is possibly difficult if you're using some sort of 
command-line-argument-parsing library to handle the help messages, but I find 
myself referring automatically to the command help messages all the time only 
to remember that I have to go hunt down the doc page online instead...

Example:

CURRENT
$ beet help ls
Usage: beet list [options]

Options:
  -h, --help            show this help message and exit
  -a, --album           show matching albums instead of tracks
  -p, --path            print paths for matched items or albums
  -f FORMAT, --format=FORMAT
                        print with custom format

PROPOSED
$ beet help ls
Usage: beet list [options]
Query the library.

Documentation Links:
  - beet list
    http://beets.readthedocs.org/en/1.0b14/reference/cli.html#list
  - query strings
    http://beets.readthedocs.org/en/1.0b14/reference/query.html

Options:
  -h, --help            show this help message and exit
  -a, --album           show matching albums instead of tracks
  -p, --path            print paths for matched items or albums
  -f FORMAT, --format=FORMAT
                        print with custom format

$ beet version
beets version 1.0b14
plugins: embedart, info, scrub, lastgenre, replaygain, chroma

Original issue reported on code.google.com by c...@contraflo.ws on 20 May 2012 at 12:48

[GoogleCodeExporter]

You're right that these messages should include help strings. In fact, every 
command already has a help string, but optparse is choosing to ignore them. :( 
So, as you've guessed, the command-line-parsing library is the limiting factor 
here. This ticket is blocked on transitioning beets to a newer library (e.g., 
argparse).

Remember that beets has manpages too.

Original comment by adrian.sampson on 20 May 2012 at 6:25

• Changed state: Accepted
• Added labels: Type-Enhancement, Priority-Low, Component-CLI

[GoogleCodeExporter]

Sorry, I wasn't aware that there were manpages. I'm still new to python 
packaging, having come from the ruby community (where most people seem to treat 
manpages as exotic rather than routine). I'll contribute more usefully when I 
get a chance to study up on the code, rather than reporting these tiny bugs :)

Original comment by c...@contraflo.ws on 20 May 2012 at 7:02

[untitaker]

Do not comment here, but on sampsyo/beets#188