Terminal command conventions

[branchtheory]

Preflight Checklist

• I have read the Contributing Guidelines.
• I have searched the issue tracker for an existing report of this issue and found none.
• I understand that the issue tracker is for bugs in the game itself and feature requests, not for issues with my own scripts.

Description

(1) Currently we always use square brackets, whether or not things are mandatory.

For example:

Incorrect usage of nano command. Usage: nano [scriptname], instead of, say, nano <scriptname> or just nano scriptname

Or:

mem [script] [-t n]              Displays the amount of RAM required to run the script
run [script] [-t n] [--tail]     Run a program, a script, or a coding contract
        [--ram-override n]
        [--temporary] [args...]

Instead of, say:

mem script [-t n]              Displays the amount of RAM required to run the script
run script [-t n] [--tail]     Run a program, a script, or a coding contract
        [--ram-override n]
        [--temporary] [args...]

or run <script> etc. / men <script> etc.

(2) We also use upper case and lower case inconsistently (rm [OPTIONS]... [FILE]... vs mv [src] [dest]).

(3) We're inconsistent about small things like file vs file name vs filename.

(4) ps is missing args in the help read-out -- it's ps [-g, --grep pattern]. Others may be too. Also ls has [-g] in the help read-out, but also supports --grep.

Finally, lots of players won't understand what these conventions even denote. I don't think they have an easy way to find out either. When I first played the game I'd hardly used a terminal before, and assumed that the commands and syntax were Bitburner's own invention. I wouldn't have thought to Google "Linux CLI command conventions".

So it would be helpful to add a couple of lines to the help command read-out to explain things. E.g.

• square brackets mean optional, and no brackets / angle brackets mean mandatory
• lower case means literal, upper means placeholder
• [-g, --grep] means you can use either flag, and they do the same thing

[E9cipher]

Agree. I would also propose to organize the help page a little better, i.e. enum-erize (internally) the commands, optional params... I have a draft branch where I started with those changes, I'll get to it in a few hours.

About terminal conventions: I would put this in the docs, because it's gonna get too long and too short at the same time if we do it on the terminal

[d0sboots]

I did a brief survey of man pages and I'm excited to report that they're not consistent either XD

Specifically, GNU utilities (mv/ls/etc., most of the base commands) use ALLCAPS for arguments. Pretty much everyone else uses lowercase. Because of that, I have very little preference for either, although standardizing on one send smart.

What is universal is that square brackets are used for optional things. {} are used for a choice of required things, and purely required things have no delimiters at all. I'd suggest that for consistency (see something like https://linux.die.net/man/1/mplayer for a complicated example), and I guess I'd lean slightly towards ALLCAPS args to distinguish from literal characters, which will usually be lowercase.