add chapter on general UI principles of sq

Closes #2

1 files changed, 48 insertions, 0 deletions

diff --git a/sq-guide.md b/sq-guide.md
index 266cfd0..f5f8f5d 100644
--- a/sq-guide.md
+++ b/sq-guide.md
@@ -372,6 +372,54 @@ advice you follow. This guide is not likely to be all you need to
 know.
 
 
+# General principles of the `sq` interface
+
+`sq` is a command line tool using subcommands and options. Global
+options come before subcommand on the command line, and options
+specific to the subcommand come after.
+
+Some options have both long and short forms. Thus, for example,
+`--output` may be shortened to just `-o` if the user wants to. The
+examples in this guide use the long form, as that's clearer and easier
+to understand without explanation. In practice, the short form is
+often more convenient to write.
+
+Some options are "flags", and the use of the option is enough. For
+example, to request binary output, the option` --binary` is enough.
+Other options require more information to be provided. For example,
+the option `--recipient-key` to specify what key to use for a
+recipient when encrypting needs to be provided the name of the file in
+which the key is stored. Such option values can be specified as the
+command line argument after the option, or appended to the option
+itself using `=foo` syntax. Thus, the following are exactly
+equivalent:
+
+```
+sq encrypt --recipient-cert cert.pgp --signer-key key.pgp --output bar.pgp foo.md
+sq encrypt --recipient-cert=cert.pgp --signer-key=key.pgp --output=bar.pgp foo.md
+```
+
+This guide uses the latter syntax to make it clearer when an option is
+given a value without the reader having to look up each option.
+
+The `sq` command has built-in help text that can be accessed using the
+`help` command or the `--help` option:
+
+```
+sq help
+sq --help
+sq help key
+sq key --help
+sq help key generate
+sq key generate --help
+```
+
+Use the help feature liberally to find out all the subcommands and
+options, and whether an option is a flag or takes a value, and what
+other arguments the command takes.
+
+
+
 # Managing one's own key
 
 This chapter concentrates on creating and managing a key for oneself.