4 ms·

While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name emai

While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name email login Which is it? $ bin/rails --generate=scaffold --user=name --email=login Or: $ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name Or: $ bin/rails --generate --scaffold=user --name=fullname --email=address --login=login_name Or what?

bombcar 4y ago
Especially when we have the entirety of modern monitors available to us, use color to indicate which parts of the command/code are mandatory/boilerplate and which are optional, and which are the actual "values" you'll be using.
- teddyh 4y ago
  Color might not be available, like here in HN comments. In older texts, the <angle-brackets> convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).
seri4l 4y ago
I'd say it's the last one, with a "subcommand based position dependant syntax" like git or zfs. It's a matter of taste but personally I prefer it to the traditional one. As long as the behavior is consistent remembering the order of the arguments is often easier than remembering the exact keywords.
ekimekim 4y ago
The long-standing convention here, particularly for command line usage, is that: - String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK") - Metavariables (stuff the user should fill in) should be in ALL-CAPS. - Not as strictly adhered to but still useful, [optional part] and {repeatable part}. So eg. your example might look like: $ bin/rails generate scaffold --user=NAME --email=LOGIN and an example usage would then be: $ bin/rails generate scaffold --user=ekimekim --email=ekimekim@example.com As far as I'm concerned, for documenting command usage, there is no excuse not to use this scheme.
- teddyh 4y ago
  > Metavariables (stuff the user should fill in) should be in ALL-CAPS. If possible, (like it is here on HN), metavariables should be in ALL_CAPS_AND_ITALICS, because that’s how it’s done in Unix manual pages. If italics is not available, it might be more clear to use the $SHELL_VARIABLE convention, depending on the audience.
vivegi 4y ago
Its trivial. The obvious solution is to just simply read the extremely friendly documentation. /s
nickjj 4y ago
In your example you're using rails but isn't this a problem with every command line tool ever that has positional arguments? cp a b rm -f a b c etc. Is "a" a sub-command of cp or is it data? Is "a" in the rm command data or a value for the -f flag?

bombcar 4y ago

Especially when we have the entirety of modern monitors available to us, use color to indicate which parts of the command/code are mandatory/boilerplate and which are optional, and which are the actual "values" you'll be using.

teddyh 4y ago
Color might not be available, like here in HN comments. In older texts, the <angle-brackets> convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).

seri4l 4y ago

I'd say it's the last one, with a "subcommand based position dependant syntax" like git or zfs. It's a matter of taste but personally I prefer it to the traditional one. As long as the behavior is consistent remembering the order of the arguments is often easier than remembering the exact keywords.

ekimekim 4y ago

The long-standing convention here, particularly for command line usage, is that: - String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK") - Metavariables (stuff the user should fill in) should be in ALL-CAPS. - Not as strictly adhered to but still useful, [optional part] and {repeatable part}. So eg. your example might look like: $ bin/rails generate scaffold --user=NAME --email=LOGIN and an example usage would then be: $ bin/rails generate scaffold --user=ekimekim --email=ekimekim@example.com As far as I'm concerned, for documenting command usage, there is no excuse not to use this scheme.

teddyh 4y ago
> Metavariables (stuff the user should fill in) should be in ALL-CAPS. If possible, (like it is here on HN), metavariables should be in ALL_CAPS_AND_ITALICS, because that’s how it’s done in Unix manual pages. If italics is not available, it might be more clear to use the $SHELL_VARIABLE convention, depending on the audience.

vivegi 4y ago

Its trivial. The obvious solution is to just simply read the extremely friendly documentation. /s

nickjj 4y ago

In your example you're using rails but isn't this a problem with every command line tool ever that has positional arguments? cp a b rm -f a b c etc. Is "a" a sub-command of cp or is it data? Is "a" in the rm command data or a value for the -f flag?