btrfs-progs: docs: update command line and UI conventions

Signed-off-by: David Sterba <[email protected]>

Documentation/dev/CmdLineConventions.rst

@@ -1,67 +1,148 @@
 Command line, formatting, UI guidelines
 =======================================
 
-## Command line options
+The guidelines try to follow common principles and build on experience based on
+user feedback or practices seen in other projects. There are no strict rules
+but rather vague statements or principles that is recommended to follow.
+It's recommended to follow them or use them as review checklist. Optimize for
+humans.
+
+- *sane defaults*
+- *principle of least surprise*
+- *it does what it says*
+- *it says what it does*
+- *frequently performed actions have shortcuts*
+- *easy thing easy, hard things possible*
+- *dangerous actions are explicit or need a confirmation*
+- *same name means the same thing everywhere*
+- *it's hard to change things once they are released*
+
+Command line options
+--------------------
+
+Unless there's a precedent for using a well known short option name, using
+long option for first implementation is always safe.
+
+All options parsers use :manref:`getopt(3)`, the behaviour is known and
+consistent with most tools and utilities found elsewhere. Options and parameters
+are sorted (options first) up to the ``--`` delimiter. Global options follow right
+after the main command and are parsed separately from the subcommand, :command:`btrfs`,
+following syntax
+:command:`btrfs [global options] subcommand [options] <parameters...>`.
+
+Short options
+^^^^^^^^^^^^^
+
+Short options are in short supply, ``a-z`` and ``A-Z``.
+
+*  reserved for the most common operations
+*  should follow some common scheme
+
+   * verbose (-v), recursive (-r, -R), force (-f), output redirection (-o), ...
+   * same option means the same thing in a group of related options
+   * mnemonic naming when possible, e.g. first letter of the action like
+     *-l* for *length* but with growing number of features clashes can and will
+     happen
+
+*  *upper case* could mean negating or extending meaning of lower case if it
+   exists, using both upper and lower case for different purposes can be
+   confusing
+*  most short options should have an equivalent long option
+*  rarely done actions do not need short options at all
+
+Long options
+^^^^^^^^^^^^
+
+Long options are meant to be descriptive, e.g. when used in scripts, documentation
+or change descriptions.
+
+*  brief but descriptive
+*  long and descriptive can be used in justified cases (e.g. conversion options
+   in :doc:`btrfstune` because of the single command without subcommands)
+
+Option parameters
+^^^^^^^^^^^^^^^^^
+
+.. note::
+   **Avoid using optional parameter.** This is a usability misfeature of
+   *getopt()* because of the mandatory short option syntax where the parameter
+   *must* be glued to the option name, like *-czstd* so this looks like a group
+   of short options but it is not. In this example *-c zstd* is not the same,
+   the parameter will take default value and *zstd* will be understood as
+   another parameter. Unfortunate examples are :command:`btrfs filesystem
+   defrag -c` and :command:`btrfs balance start -d`. Both quite common and we
+   probably cannot fix this without breaking existing scripts.
+
+Help text
+^^^^^^^^^
+
+Description in the help text should be long enough to describe what it does, mention default
+value and should not be too long or detailed. Referring to documentation is recommended
+when it's really wise to read it first before using it. Otherwise it's a reminder
+to user who has probably used it in the past.
+
+*  short help for *--help* output: :command:`btrfs subcommand [options] param1 param2`
+
+   * the number of options gets unwieldy for a command with many tunable features
+     so it's better to write a short description and document properly everything
+     in the manual page or in the followup text
+
+*  short description after command line: terse but understandable explanation
+   what the command does, mention dangers
+
+*  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
+      (examples)
+
+Command output, verbosity
+-------------------------
+
+Structured output
+^^^^^^^^^^^^^^^^^
+
+If the output consists of a lot of information, try to present it in a concise
+way and structure related information together using some known formats
+or already used ones in this project.
 
-### 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
+* `Key: value`, spacing by tabs or spaces
+* use indentation and empty lines 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
+* must be parseable and also visually comprehensible, related information
+  on one line usually satisfies both (*greppable*)
 
-### Default output
+Default output
+^^^^^^^^^^^^^^
 
-* unix commands do one thing and say nothing, we may diverge a bit from that
+* UNIX commands do one thing and say nothing, we diverge from that as it does
+  not work well for a multi-command tools
 * default output is one line shortly describing the action
- * why: running commands from scripts or among many other commands should be
-   noticeable due to progress 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 e.g. 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
+  * why: running commands from scripts or among many other commands should be
+    noticeable due to progress tracking or for analysis if something goes wrong
+  * there's a global option to make the commands silent :command:`btrfs -q subcommand`,
+    this can be easily scripted e.g. storing the global verbosity option in a
+    variable, :command:`btrfs $quiet subcommand` and then enabling or disabling as needed
+
+* there should be a line length limit so the output visually fits to one line without
+  wrapping, there's no exact number of columns, assume something around 100,
+  keep related information on one line (printed) rather then breaking it.
+
+Formatting
+^^^^^^^^^^
 
 * numeric values are not quoted
 * string values are quoted if they would be confused when parsed word by word
   (e.g. file paths)
-  * quoting is by single apostrophe on both ends
+  * quoting is by single apostrophe on both ends, no fancy backtick+quote
 * all messages follow a few known and understood schemes
 
-### Verbosity levels
+Verbosity levels
+^^^^^^^^^^^^^^^^
 
-* 0 - quiet, only errors to stderr, nothing to stdout
+* 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
+* 3 - a little bit more detailed about what happens during level 2
+* 4 - possibly lots of information, for debugging and close inspection what happens