[Docs] Make Getting started guide explain use of quotes for arguments with spaces #3555
Conversation
docs/getting_started.rst
Outdated
| @@ -351,6 +351,9 @@ The cog guides are formatted the same. They're divided into 3 sections: | |||
|
|
|||
| Arguments enclosed in ``[ ]`` means that the argument is **optional** | |||
| for the command; you can decide to use it or not. | |||
|
|
|||
| If your argument includes spaces like ``Hello world!`` you need to place | |||
There was a problem hiding this comment.
Hmmmm this is not true for every command though... so generelizing here can leave to confusion.
There was a problem hiding this comment.
I'm not aware of any differantiation. How could the end user tell they need or don't need quotes?
jack1142
changed the title
|
Any other thoughts on this? |
|
There's no differentiation between the arguments that require quotes and those that don't, but the only arguments that may not require quotes are the last arguments. It is a convention of sorts to not require quotes for last argument, however it is not used in all commands (probably even some commands in core cogs may not use the "consume all" for last argument) and also, if last argument is shown in usage with ellipsis (e.g. Probably the things I said should be somehow nicely explained in the guide even with the limited knowledge you can get from command's usage. IMO, saying last argument usually doesn't require quotes around it + maybe mentioning ellipsis would be good enough, we can't make this perfect because usage of a command doesn't show any difference between consume all and regular argument. Also, while I think it wouldn't be a bad idea to have some indicator in usage when last argument doesn't require spaces, that would have to be a separate discussion (probably not an easy one). |
|
Yeah, okay so we're pretty much where we left off. Just for the sake of people not unintentionally not using quotes wouldn't it be better to say they are always required instead of having a "maybe eventually in some cases" in a guide that's meant for absolute beginners? I'd personally leave it as is but if you think it needs to be changed before this can be approved I'll try to find a good explanation. |
|
It may not be always required though if I have a consume all and add quotes ... things .. mess up |
|
Re. quotes "mess up", I have at least one consume all command on a cog of mine that addresses that very thing: if users expect quotes to work, especially if the entity is one that in other commands does require quotes, then the command should deal with the possibility the user typed them even though they're not required. So I wrote the code to do that. This is in line with my feeling users will learn "quotes are required" as a general rule anyway, even though in some corner cases they may not be. |
|
. |
|
I am happy with this considering what we can do with how the UX shows it. |
jack1142
added
the
Type: Enhancement
|
Wait how did I dismiss something? |
|
That's normal, you dismissed Draper's approving review cause you made changes since he made the review. Nothing to worry :) |
|
Ah I see. |
Type
Description of the changes
This closes #3111