Issue #7764 has been updated by Randall Hansen.
Daniel Pittman wrote:
> > Render format: what are the options? How do I find out?
>
> You can't. We can introspect that data, though, so it can be
> reasonably dumped out.
We have this help item, and we should tell the user what formats are acceptable.
--render-as FORMAT - The rendering format to use.
> > Does copyright need to take three lines? Can we put it all on one?
Better yet, we shouldn't show copyright info in the CLI short help. It can
live in "man".
> That feels, to me, like we are absolutely failing in "provide a
> concise, single-line definition of this face". Better we display the
> summary, then write the description knowing that the summary will
> always be visible to the user.
That's a good idea. I agree.
> Good, useful examples make the documentation!
Absolutely. Examples should live in the man page, not in the CLI short help.
> > Some commands (perhaps all?) show the following for ... help save: “Create
> > or overwrite an object. Save actions cannot currently be invoked from the
> > command line, and are for API use only.”
> >
> > I don’t understand this. Does it mean you can’t used this “save” action at
> > all? If that’s the case, we shouldn’t expose it in the CLI help.
>
> Yes, except where you can. Also, given we have no machinery for
> marking something as "broken", we would need to withdraw access to it
> entirely, which would *also* withdraw it from access in Ruby, where it
> can be used. Which, in turn, would break the code we have that does
> use those things.
>
> How do you want that handled?
I'd like us not to show anything in the CLI short help that isn't actionable
via CLI invocation of `puppet`. I don't think that's realistic for 2.7.0, but
it's where we need to go.
As an intermediate step, I'm not sure. Nick is thinking about this.
> > What does this imply? RETURNS: A Puppet::Node::Facts object.
>
> That the API is less helpful than you might hope? That, indeed, is
> what it returns to someone interacting with the Ruby API. We then
> render it out for the human, if invoked from the command-line.
There are other places in the help where we're more helpful in this type of
case. That's all I mean. If it can output to the CLI, we should provide some
guidance about what to expect.
> How do you want to handle the conflict between needing to explain the
> Ruby API and the CLI in the same code?
By not doing that.
> > RETURNS: An array of resource objects.
> > how is it formatted? should we provide formatting advice?
>
> ...and, given that the formatting comes from a machine, there isn't
> much "formatting advice" I can understand us providing. Can you
> explain what you expected it might look like?
There are other places in help where we advise users to use "render-as" to make
something more readable. This might be a similar case.
----------------------------------------
Bug #7764: Many small issues with Faces CLI short help
https://projects.puppetlabs.com/issues/7764
Author: Randall Hansen
Status: Accepted
Priority: Normal
Assignee:
Category:
Target version: 2.7.0
Affected Puppet version:
Keywords:
Branch:
puppet help
* We should be consistent about using "subcommand" versus "face". I've been
thinking that we should use "subcommand" anywhere visible from the CLI, and
"face" only for the internal API. What do you think?
* Render format: what are the options? How do I find out?
* Does copyright need to take three lines? Can we put it all on one?
* The first sentence of the description is sometimes the summary, sometimes
similar to the summary, and sometimes different. We should make the call about
this and be consistent. My current best idea is to not show the summary.
* Some commands return "Examples" sections. I don't think we should do this,
but regardless we should be consistent.
* can we make the "--mode" option description live on 1 line? That would make
every help command look better.
* same for "--terminus"
* Some commands we have a "RETURNS" section. This should be consistent for
every command that returns data.
* E.g., `puppet help certificate_revocation_list info` says "Prints" when it
should have a RETURNS section.
* In fact, I kind of like it when it's blank (e.g., puppet help
certificate_revocation_list destroy)
* Some commands have options in USAGE that run together, e.g., USAGE: puppet
certificate sign [--terminus TERMINUS][--ca-location LOCATION]
* we should put a space between ][
* We should write a test that runs all help commands and looks for broken
things, like "invalid for this face"
* Some commands (perhaps all?) show the following for `... help save`: "Create
or overwrite an object. Save actions cannot currently be invoked from the
command line, and are for API use only."
* I don't understand this. Does it mean you can't used this "save" action at
all? If that's the case, we shouldn't expose it in the CLI help.
puppet help catalog
* Catalog:apply -- this help doesn't help me :) It's a more verbose way ot
saying it, but it doesn't define "catalog" or "apply".
* Catalog has two "destroy" actions (and non-helpful help for them).
* Catalog has two "search" actions (and non-helpful help for them).
puppet help catalog destroy
* this returns help, but it should return an error
puppet help catalog download
* doesn't seem to have help
* does show what seems to be boilerplate from secret_agent, which seems bad
puppet help catalog find
* no help, only description. is this enough?
* also, "name" in description but "<key>" in usage
puppet help catalog info
* help text is duplicated ("Prints the default terminus class for this face.")
puppet help catalog save
* help text is duplicated ("Create or overwrite an object.")
puppet help catalog search
* doesn't seem to have help
puppet help certificate
* find Retrieve a certificate # no period at end of sentence. We should
address this globally.
* save Invalid for this face. # should not appear
* search Invalid for this face. # should not appear
puppet help certificate destroy
* It would be nice to provide more guidance here. Tell them to use "cert"
instead? "Deletes a certificate. This action currently only works with a local
CA."
puppet help certificate list
* RETURNS section instead of description
puppet help certificate_request
* destroy Invalid for this face.
puppet help certificate_revocation_list
* save Invalid for this face.
* search Invalid for this face.
puppet help config print
* the RETURNS section is broken up, and it's not immediately clear that the
second paragraph is part of it
puppet help facts
* destroy Invalid for this face.
* search Query format unknown; potentially invalid for this face.
puppet help facts find
* What does this imply? RETURNS: A Puppet::Node::Facts object.
puppet help file
* destroy Invalid for this face.
* search Invalid for this face.
puppet help file download
* I don't understand the USAGE: USAGE: puppet file download [--terminus
TERMINUS] ( {md5}<checksum> | puppet:///... )
puppet help file key
* "key" seems like a weird name for this subcommand
* "Delete an object." is too brief. What object?
puppet help file key
* "Retrieve an object by name." is better, but still brief. What object?
puppet help file search
* "Search for an object or retrieve multiple objects." is too generic. This is
a common problem.
puppet help man & puppet help man man
* these should be the same. I don't imagine that's easy to do :)
puppet help node
* destroy Invalid for this face.
* save Invalid for this face.
* search Invalid for this face.
puppet help plugin download
* "RETURNS: A display-formatted list of the files downloaded. If all plugin
files were in sync, this list will be empty."
* Is it an empty list, or no return at all?
puppet help report
* destroy Invalid for this face.
* find Invalid for this face.
* search Invalid for this face.
puppet help report submit
* This action is essentially a shortcut and wrapper for the `save` action
with the `rest` terminus, which provides additional details in the
event of a report submission failure. It is not intended for use from
a command line.
* If something's not usable from the CLI, we shouldn't be exposing it in CLI
help.
puppet help resource
* destroy Invalid for this face.
puppet help resource find
* RETURNS: A resource object.
* We should be consistent about this. Some places we give the full Ruby
object name, some places we give the more generic name. In either case we
should provide more context about what "object" means.
puppet help resource search
* RETURNS: An array of resource objects.
* how is it formatted? should we provide formatting advice?
puppet help resource_type
* destroy Invalid for this face.
* save Invalid for this face.
puppet help resource_type find
* this is huge help. Are all the details necessary?
puppet help resource_type search
* RETURNS: An array of resource collection info hashes. (See "RETURNS" under
`find`.)
* s/`find`/`puppet help resource_type find`/
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
