How can I bake a single controllers templates? about bake

[antograssiot]

@davidyell bin/cake bake template Users index seeme to works normaly for me.

[davidyell]

Then I think that the options for the template command need updating to be clearer

[lorenzo]

@davidyell would you be able to propose a fix or improvement to the options?

[davidyell]

My issue was that the options parser only showed the all command. There was no help text about the possibility of omitting the sub-command in order to bake templates.

As I tried bin/cake bake template -h and the return is a pattern of

cake bake.bake template [subcommand] [options] [<controller>] [<action>] [<alias>]

Which doesn't tell you that the subcommand is optional. Perhaps the options parser needs to be updated to add to the copy describing the all subcommand as being optional.

[ADmad]

Which doesn't tell you that the subcommand is optional.

The square brackets around subcommand indicate it's optional.

[davidyell]

That's incredibly nuanced and unclear in my opinion. Enough that as a 'seasoned' cake developer, I had no idea that was even a convention. I believe in making things as obvious as possible for these reasons.

[dakota]

At least in the *nix world, square brackets [ ] have always been used to denote optional arguments, options and sub-commands (http://stackoverflow.com/a/9727046 and http://docopt.org/).

[davidyell]

So how does that help users who develop on Windows? I can appreciate the origins, but it's just not obvious enough in it's current state, and relies on knowledge that some users might not have. I certainly had no idea that square brackets meant optional, and I've been a developer for years.

Making things obvious and easier to work with is not a bad thing, I'm surprised we are discussing it. Surely helping users to get stuff done is important, whether they posses knowledge which is innate to you or not.

[dakota]

Windows follows the exact same standard 😄 (Based on my limited run if a few windows commands). For the record, I'm not disagreeing with you, and I think it would be a good idea to explicitly state optional arguments on the CLI help.

[davidyell]

Cool, well I'll pin my hopes to the PR 🍭

[rchavik]

I don't see why we need to document optional arguments when it's already enclosed within []. I think It's common enough convention and not really UNIX specific.

• "Optional items enclosed in square brackets: []."
  http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form
• "Any items inside a bracket are optional. Brackets are not to be taken literally so don't use them when executing a command."
  http://pcsupport.about.com/od/commandlinereference/a/command-syntax.htm
• "Brackets ([ ]) indicate optional items. A parameter and its value can be optional, or the name of a required parameter can be optional"
  https://technet.microsoft.com/en-us/library/hh847867.aspx
• "Items in square brackets [ ] are optional KEYWORDs or parameters that do not have to be used in the statement."
  http://www.qb64.net/wiki/index.php?title=Syntax_Notation_Conventions
• "Optional arguments should always be surrounded by square brackets."
  http://courses.cms.caltech.edu/cs11/material/general/usage.html