Puppet

[ben@paresthesia:puppet]% puppet help help help                                                                                                                     1 G  ✱/master
Display Puppet help.

USAGE: puppet help  

OPTIONS:
  --mode MODE                    - The run mode to use (`user`, `agent`, or
                                   `master`).
  --render-as FORMAT             - The rendering format to use.
  --verbose                      - Whether to log verbosely.
  --debug                        - Whether to log debug information.

ACTIONS:
  help    Display help about faces and their actions.

COPYRIGHT AND LICENSE:
  Copyright 2011 by Puppet Labs

Looks like help help help works fine to me.

Dan is still a bug to you please?

Thanks for the calcification Dan.

Dan’s right. The ideal message for puppet help foo would be similar to what you get typing puppet foo:

Error: Unknown Puppet subcommand 'bar'
See 'puppet help' for help on available puppet subcommands

I am rejecting this, because it is based on a flawed premise: the actual behaviour is nothing like the imagined behaviour, and until we have a suggested resolution that addresses the real state of play, I am not going to take code changes to “fix” this.

The reason that Try 'puppet help help help' for usage is displayed is that the user has requested the help face be loaded, the help action be invoked, and the argument foo (representing the face to display help on) be passed to that.

The help action then, correctly, fails, returning an error indicating exactly what is going on, which is that the foo face can’t be loaded.

The additional line, indicating that you should ask for help on showing help is because that was suggested as a good thing to follow every error message, regardless of context or whatever, to encourage the user toward the right place to show help.

To show the same problem with less surprise, grab any other face that has a default action (or explicitly specify the action) and invoke it in the same way, which is with an argument that causes an exception to be raised.

If you do that you will get the same output, but different words: if the face were foo, and the default action bar, the input would bepuppet foo banana, and output would beTry puppet help foo bar for usage`. Much less confusing than the help case, which uses the same term in three places.

Please also note that the output of puppet help and puppet help help are distinct and different things – and this is equally true of the less confusing case, where puppet help foo and puppet help foo bar are different things. (One the action, the other the face and all the actions.)

Additionally, please note that when you eliminate the face and action from the error you would turn any other error except this one into a much more confusing result. :)

As to improving this, I would certainly accept any of:

A change that entirely eliminated that message from the generic failure case; given that the face has reported a much more specific error, appending this doesn’t seem to add much value to me.

A change that modified the help action of the help face to report that failure mode some other way. This would probably be completely horrible for anyone trying to use the Ruby API if done carelessly, so please do consider that use case at the same time.

A change that modifies the error to omit the action if, and only if, the action is the default for the face. This would render that down to puppet help help for the case in point, and would give the user a marginally less confusing experience without breaking everything for other faces with default actions.

A change that made puppet help a special case, rather than a face, and eliminated the help face and all associated bits. They can be replaced / mutated into whatever shape the magic special case code requires to work.

A change that makes puppet help a special case, and does away with default actions entirely. This eliminates the confusion, but means that you can never have puppet agent do anything helpful in a fully faces universe – unless you have magic special-case code for agent, also.