New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow separate help output for each command / make --help the same as -h #579

Closed
varac opened this Issue Jul 5, 2017 · 15 comments

Comments

Projects
None yet
4 participants
@varac

varac commented Jul 5, 2017

I.e. hledger add --help should print a help for only this command, like most other cli tools do.
Currently, it shows the whole monolithic help for hledger.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 5, 2017

Owner

Which other cli tools ?

Currently, hledger CMD --help prints the full hledger manual, at least for the builtin commands, and hledger CMD -h shows the short command-specific usage.

Owner

simonmichael commented Jul 5, 2017

Which other cli tools ?

Currently, hledger CMD --help prints the full hledger manual, at least for the builtin commands, and hledger CMD -h shows the short command-specific usage.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 5, 2017

Owner

(See hledger -h for some examples.)

Owner

simonmichael commented Jul 5, 2017

(See hledger -h for some examples.)

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 5, 2017

Owner

Ohh I get it. CLI tools other than hledger.

Using -h and --help for short and long help respectively is a little "modern", but we are following in the footsteps of git which is a big precedent..

Owner

simonmichael commented Jul 5, 2017

Ohh I get it. CLI tools other than hledger.

Using -h and --help for short and long help respectively is a little "modern", but we are following in the footsteps of git which is a big precedent..

@varac

This comment has been minimized.

Show comment
Hide comment
@varac

varac Jul 5, 2017

Currently, hledger CMD --help prints the full hledger manual, at least for the builtin commands, and hledger CMD -h shows the short command-specific usage.

Oh, I was not aware of this distinction. For my point of view, this is confusing for the user, because -h is considered as the short version of --help and I don't see why both should behave differently.
Maybe I'm just used that they behave the same and somewhat "unmodern" in this sense :D

varac commented Jul 5, 2017

Currently, hledger CMD --help prints the full hledger manual, at least for the builtin commands, and hledger CMD -h shows the short command-specific usage.

Oh, I was not aware of this distinction. For my point of view, this is confusing for the user, because -h is considered as the short version of --help and I don't see why both should behave differently.
Maybe I'm just used that they behave the same and somewhat "unmodern" in this sense :D

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 6, 2017

Owner

I find the short and long help distinction useful. I wouldn't be against making --help a synonym for -h again. But, what name would you use for the current --help and help functionality ? There is a certain symmetry and consistency with the current --help/--man/--info & help/man/info.

Owner

simonmichael commented Jul 6, 2017

I find the short and long help distinction useful. I wouldn't be against making --help a synonym for -h again. But, what name would you use for the current --help and help functionality ? There is a certain symmetry and consistency with the current --help/--man/--info & help/man/info.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 6, 2017

Owner

PS maybe start a discussion on the mail list to get more input on this.

Owner

simonmichael commented Jul 6, 2017

PS maybe start a discussion on the mail list to get more input on this.

@cfellinger

This comment has been minimized.

Show comment
Hide comment
@cfellinger

cfellinger Jul 6, 2017

Collaborator

Lately I use -h/-help for the short and -H/--HELP for the long help text. Seems to work. When you're unfamiliar with the program the standard -h/--help tells you there is an option to get more help, and the
uppercase variant is close enough to be easy to remember.

Collaborator

cfellinger commented Jul 6, 2017

Lately I use -h/-help for the short and -H/--HELP for the long help text. Seems to work. When you're unfamiliar with the program the standard -h/--help tells you there is an option to get more help, and the
uppercase variant is close enough to be easy to remember.

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 6, 2017

Owner

Interesting, but -H is used for --historical.

Owner

simonmichael commented Jul 6, 2017

Interesting, but -H is used for --historical.

@cwarden

This comment has been minimized.

Show comment
Hide comment
@cwarden

cwarden Jul 6, 2017

Collaborator

I always use git help <command> rather than git <command> --help. I also expect --help and -h to be synonyms.

Collaborator

cwarden commented Jul 6, 2017

I always use git help <command> rather than git <command> --help. I also expect --help and -h to be synonyms.

@simonmichael simonmichael changed the title from Allow seperate help output for each command to Allow separate help output for each command Jul 6, 2017

@simonmichael simonmichael changed the title from Allow separate help output for each command to Allow separate help output for each command / make --help the same as -h Jul 6, 2017

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 6, 2017

Owner

I use git-CMD --help and didn't notice git help. I'm also used to the long ledger --help.

Owner

simonmichael commented Jul 6, 2017

I use git-CMD --help and didn't notice git help. I'm also used to the long ledger --help.

@cfellinger

This comment has been minimized.

Show comment
Hide comment
@cfellinger

cfellinger Jul 6, 2017

Collaborator
Collaborator

cfellinger commented Jul 6, 2017

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 7, 2017

Owner

Some thoughts:

** principles
*** docs (usage, manuals, tutorials..) should be available reliably and instantly from the software you are running (without net or filesystem access and on windows too)
*** docs should by default be provided in the native UI of the tool you request them from
*** each tool should provide the full set of docs
*** within a tool, there should be one clear way to call up any particular doc

** mockup

hledger -h/--help                         general usage
hledger CMD -h/--help                     command usage
hledger help                              list manuals/topics
hledger help [--man|--info] MANUAL/TOPIC  show MANUAL/TOPIC as plain text[/man page/info manual]
hledger help this                         show manual for the current tool
hledger-ui, hledger-web                   (manuals provided in-app)
Owner

simonmichael commented Jul 7, 2017

Some thoughts:

** principles
*** docs (usage, manuals, tutorials..) should be available reliably and instantly from the software you are running (without net or filesystem access and on windows too)
*** docs should by default be provided in the native UI of the tool you request them from
*** each tool should provide the full set of docs
*** within a tool, there should be one clear way to call up any particular doc

** mockup

hledger -h/--help                         general usage
hledger CMD -h/--help                     command usage
hledger help                              list manuals/topics
hledger help [--man|--info] MANUAL/TOPIC  show MANUAL/TOPIC as plain text[/man page/info manual]
hledger help this                         show manual for the current tool
hledger-ui, hledger-web                   (manuals provided in-app)

simonmichael added a commit that referenced this issue Jul 7, 2017

simonmichael added a commit that referenced this issue Jul 7, 2017

help: add --info/--man/--pager/--cat flags, & choose best one by defa…
…ult (#579)

You can select a docs format/viewer with one of the `--info`, `--man`, `--pager`, `--cat` flags.
Otherwise, it will use info if available, otherwise man if available,
otherwise $PAGER if defined, otherwise less if available, otherwise it
prints on stdout (and always prints on stdout when piped).

Preferring info over man might not suit everyone.
@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 7, 2017

Owner

Let's try it this way. --help and -h are synonyms again, and all more detailed help is provided by a single powerful help command (and an equivalent feature in hledger-ui/hledger-web, some day).

Git's scheme was more scalable, in that you could always get the manual for any new executable by running it with --help. Our help command is monolithic, it has to have the docs built in. There might be a way around that some day. Eg, hledger help could query other hledger-* executables in path for additional manuals via --manual/--man/--info (or --manual/--manual-nroff/--manual-texi) flags.

Owner

simonmichael commented Jul 7, 2017

Let's try it this way. --help and -h are synonyms again, and all more detailed help is provided by a single powerful help command (and an equivalent feature in hledger-ui/hledger-web, some day).

Git's scheme was more scalable, in that you could always get the manual for any new executable by running it with --help. Our help command is monolithic, it has to have the docs built in. There might be a way around that some day. Eg, hledger help could query other hledger-* executables in path for additional manuals via --manual/--man/--info (or --manual/--manual-nroff/--manual-texi) flags.

simonmichael added a commit that referenced this issue Jul 7, 2017

@simonmichael simonmichael added the A WISH label Jul 7, 2017

@simonmichael

This comment has been minimized.

Show comment
Hide comment
@simonmichael

simonmichael Jul 11, 2017

Owner

Fixed.

Owner

simonmichael commented Jul 11, 2017

Fixed.

@varac

This comment has been minimized.

Show comment
Hide comment
@varac

varac commented Jul 11, 2017

Thx !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment