From f93d67ece10ea110661871a2084a7b81fdcde795 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Mon, 18 Jan 2021 20:50:07 +0100 Subject: [PATCH] btrfs-progs: docs: document command line conventions First draft of the command line conventions regarding options, wording, style and formatting. Signed-off-by: David Sterba --- Documentation/CmdLineConventions | 66 ++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 Documentation/CmdLineConventions diff --git a/Documentation/CmdLineConventions b/Documentation/CmdLineConventions new file mode 100644 index 00000000..f62c67b0 --- /dev/null +++ b/Documentation/CmdLineConventions @@ -0,0 +1,66 @@ +# Command line, formatting, UI guidelines + +## Command line options + +### Short options + +* reserved for the most common operations +* should follow some common scheme + * verbose, recursive, force, output redirection, ... + * same option means the same thing in a group of related options +* most have an equivalent long option + +### Long options + +* short but descriptive +* long-worded long options are acceptable for rare but seemingly unique operations + * example: `btrfs check --clear-space-cache v1` + +### Help text + +* short help for *--help* output: `btrfs subcommand [options] param1 param2` + * the number of options gets unwieldy for many options so it's better to + insert the stub and document properly all of them in the detailed section +* short description after command line: terse but understandable explanation + what the command does +* long description after the short description + * explain in more detail what the command does, different use cases, things to notice + * more complex things should be documented in the manual pages and pointed to + +## Command output, verbosity + +### Structured output + +* `Key: value` +* indentation used for visual separation +* value column alignment for quick skimming +* must be parseable by scripts but primary consumer of the output is a human, and greppable for logs + +### Default output + +* unix commands do one thing and say nothing, we may diverge a bit from that +* default output is one line shortly describing the action + * why: running commands from scripts or among many other commands should be + noticeable due to progres tracking or for analysis if something goes wrong + * there's a global option to make the commands silent `btrfs -q subcommand`, + this can be easily scripted eg. storing the global verbosity option in a + variable, `btrfs $quiet subcommand` and then enabling or disabling as needed +* line length should not exceed 80 columns if possible but this is not a strict + limit and we want to put the relevant information there rather abbreviate too + much + +### Formatting + +* numeric values are not quoted +* string values are quoted if they would be confused when parsed word by word + (eg. file paths) + * quoting is by single apostrophe on both ends +* all messages follow a few known and understood schemes + +### Verbosity levels + +* 0 - quiet, only errors to stderr, nothing to stdout +* 1 - default, one line, see above +* 2 - inform about main steps that happen +* 3 - a little bit more details about what happens during level 2 +* 4 - lots of information, for debugging and close inspection what happens