Issue #7764 has been updated by Daniel Pittman.
You missed that we use 'unknown option' where we mean 'undocumented option' in the templates. Probably because we have documented 'em all. :) > puppet help > 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. > Does copyright need to take three lines? Can we put it all on one? The copyright text is reasonably short, but the license is free-form text. We just happen to use a short version right now. So, maybe? > 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. 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. > Some commands return “Examples” sections. I don’t think we should do this, > but regardless we should be consistent. In every product, and platform, I know that gets talked about having good documentation, the single most important feature for people is the set of examples. Good, useful examples make the documentation! > Some commands have options in USAGE that run together, e.g., USAGE: puppet > certificate sign [—terminus TERMINUS][—ca-location LOCATION] That needs a code change, potentially, not just a template change. Not hard, but not as trivial, either. > 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? > Catalog has two “destroy” actions (and non-helpful help for them). That bug is fixed. > puppet help catalog download > > doesn’t seem to have help I think you need to update your code; this has help in the code slated to be the next RC. (eg: head of 2.7rc branch.) > puppet help catalog search > doesn’t seem to have help Actually, worse than that. It seems that just interacting with it as lightly as we do causes some code to execute, reporting an error message to the user. That is kind of scary, actually. > puppet help facts find > 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. How do you want to handle the conflict between needing to explain the Ruby API and the CLI in the same code? > puppet help man & puppet help man man > these should be the same. I don’t imagine that’s easy to do :) Impossible. Unless, perhaps, you wanted to declare that there was absolutely no way to ever see the other actions of a face with a default action. Which, when `man` also generates HTML and other output, is probably less helpful than you really want. > “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? Yes. An empty list, in Ruby, no textual output, for a human. If you asked it to --render-as json you should see an empty array. > RETURNS: An array of resource objects. > how is it formatted? should we provide formatting advice? The way the user requested, which varies. The default format aims to be human-usable, which is plain text or JSON depending on the structure of the object. If you request a serialization then you get that format. ...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? > puppet help resource_type find > this is huge help. Are all the details necessary? Only if we expect people to be able to use the action, I guess. Although it is missing the explanation of what the input format is like, which is a relatively complex search language, and needs to have a whole bunch of detail explained. We could always replace the short help with a pointer to the output of 'puppet man resource_type' and pack all that common detail in there, I guess? ---------------------------------------- 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.
