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

'hugo help' command undocumented in --help output #2349

Closed
MarkDBlackwell opened this Issue Aug 10, 2016 · 4 comments

Comments

Projects
None yet
4 participants
@MarkDBlackwell
Contributor

MarkDBlackwell commented Aug 10, 2016

The final line printed by hugo help is:

Use "hugo [command] --help" for more information about a command.

(hugo --help prints the same, BTW.)

Typing hugo help new (for example) works fine.

Typing hugo new --help also works. (That's natural, since hugo --help recommends it.)

The command hugo help is undocumented, in the sense that help isn't included in the list of Available Commands printed by hugo --help.

Generally speaking, new users can feel "lost in a thicket" of new syntax. To help promote Hugo to new users, IMO hugo help should be included as an Available Command.

Some of the discussion in this Cobra PR seems relevant.

@bep bep added the Enhancement label Aug 11, 2016

@traveller42

This comment has been minimized.

Show comment
Hide comment
@traveller42

traveller42 Oct 13, 2016

This appears to be the opposite situation, but I agree help should be in the Available Commands list as it is an available command.

I'm looking for the right place to make this change right now, but I think I need to understand Cobra better.

ETA:
It looks like the requested behavior could be added in Cobra.

I can use the Usage "override" to implement this in hugo directly. Another option is to add the ability to include help in the Available Commands list in Cobra and then use that option in hugo.

Thoughts?

traveller42 commented Oct 13, 2016

This appears to be the opposite situation, but I agree help should be in the Available Commands list as it is an available command.

I'm looking for the right place to make this change right now, but I think I need to understand Cobra better.

ETA:
It looks like the requested behavior could be added in Cobra.

I can use the Usage "override" to implement this in hugo directly. Another option is to add the ability to include help in the Available Commands list in Cobra and then use that option in hugo.

Thoughts?

@MarkDBlackwell

This comment has been minimized.

Show comment
Hide comment
@MarkDBlackwell

MarkDBlackwell Nov 15, 2016

Contributor

@traveller42 the second option (adding to Cobra "the ability to include help in the Available Commands list") seems more useful in the long run—especially for Cobra users beyond Hugo (of course).

[It's] a good point about the root help being essential. If the only subcommand is Help [note: this isn't the case, with Hugo], then don't display Available Commands at all. Otherwise, [Help] should be included in the list.

This seems like the ideal behavior for Cobra, and fits exactly with the Unix tool philosophy, as well as the subcommand philosophy.

Part of the above comments can be rephrased as follows:

"If other top-level commands exist, then Cobra should include Help in the displayed list of Available Commands."

Also, the location where Steve Francia made the above two comments (i.e., in the Cobra repository) seems to imply he prefers the second option (i.e., implementing this in Cobra).

LOWER LEVELS

BTW, as I understand it, Cobra displays a (different) list of Available Commands (among other things) when Help is invoked at each level, not just at the top level of an application (i.e., for its root command).

Steve Francia IMO didn't aim his comments (above) at the Help information provided for lower levels (e.g., regarding applications' sub-subcommands). An example would be drafts, in hugo list drafts.

hugo list help demonstrates that help is a valid sub-subcommand of hugo, and a valid subcommand of hugo list. Yet the following (IMO correctly) all exclude help from their displayed lists of Available Commands (i.e., of the subcommands of hugo list):

  1. hugo list help
  2. hugo list --help
  3. hugo help list
Contributor

MarkDBlackwell commented Nov 15, 2016

@traveller42 the second option (adding to Cobra "the ability to include help in the Available Commands list") seems more useful in the long run—especially for Cobra users beyond Hugo (of course).

[It's] a good point about the root help being essential. If the only subcommand is Help [note: this isn't the case, with Hugo], then don't display Available Commands at all. Otherwise, [Help] should be included in the list.

This seems like the ideal behavior for Cobra, and fits exactly with the Unix tool philosophy, as well as the subcommand philosophy.

Part of the above comments can be rephrased as follows:

"If other top-level commands exist, then Cobra should include Help in the displayed list of Available Commands."

Also, the location where Steve Francia made the above two comments (i.e., in the Cobra repository) seems to imply he prefers the second option (i.e., implementing this in Cobra).

LOWER LEVELS

BTW, as I understand it, Cobra displays a (different) list of Available Commands (among other things) when Help is invoked at each level, not just at the top level of an application (i.e., for its root command).

Steve Francia IMO didn't aim his comments (above) at the Help information provided for lower levels (e.g., regarding applications' sub-subcommands). An example would be drafts, in hugo list drafts.

hugo list help demonstrates that help is a valid sub-subcommand of hugo, and a valid subcommand of hugo list. Yet the following (IMO correctly) all exclude help from their displayed lists of Available Commands (i.e., of the subcommands of hugo list):

  1. hugo list help
  2. hugo list --help
  3. hugo help list
@bogem

This comment has been minimized.

Show comment
Hide comment
@bogem

bogem Feb 28, 2017

Contributor

Fixed in spf13/cobra#394

Contributor

bogem commented Feb 28, 2017

Fixed in spf13/cobra#394

@bep bep closed this in b7a672f Feb 28, 2017

@bogem

This comment has been minimized.

Show comment
Hide comment
@bogem

bogem Mar 25, 2017

Contributor

@bep sorry for bothering you, but b7a672f didn't actually fix this issue. govendor didn't update it correctly.
As you can see revision time is 2017-02-23, but fix is merged on 1st March.
I tried to make PR and update it by myself, but govendor always updates vendor.json to commit of newest PR to cobra, so I didn't figure out, how to use it :(

Contributor

bogem commented Mar 25, 2017

@bep sorry for bothering you, but b7a672f didn't actually fix this issue. govendor didn't update it correctly.
As you can see revision time is 2017-02-23, but fix is merged on 1st March.
I tried to make PR and update it by myself, but govendor always updates vendor.json to commit of newest PR to cobra, so I didn't figure out, how to use it :(

bogem added a commit to bogem/hugo that referenced this issue Apr 1, 2017

vendor: Update cobra
Really fix #2349
b7a672f didn't actually the issue.

bep added a commit that referenced this issue Apr 1, 2017

vendor: Update cobra
Really fix #2349
b7a672f didn't actually the issue.

@bep bep added this to the v0.20 milestone Apr 2, 2017

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