diff options
author | Lars Wirzenius <liw@liw.fi> | 2022-02-15 08:13:48 +0000 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2022-02-15 08:13:48 +0000 |
commit | 5d7b10ed401debae8743d9dd388b6e230f6f8d2f (patch) | |
tree | 834ef4187f8451aef4979b4c82713ac8bce5ccdb | |
parent | 89151f506f87d7db773de204f6ad210a3f8c5e00 (diff) | |
parent | dc6ffd831b5f6189b1516007b1966070ba8613f9 (diff) | |
download | sq-user-guide-5d7b10ed401debae8743d9dd388b6e230f6f8d2f.tar.gz |
Merge branch 'liw/conventions' into 'main'
doc: add section on document conventions
Closes #31
See merge request sequoia-pgp/sq-user-guide!21
-rw-r--r-- | sq-guide.md | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/sq-guide.md b/sq-guide.md index bd35f3a..5f97060 100644 --- a/sq-guide.md +++ b/sq-guide.md @@ -182,6 +182,48 @@ help, which you can get by running `sq help` or `sq encrypt --help`, is always up to date and a good way to look up details. +## Conventions in this guide + +This guide uses the `.pgp` filename suffix for any output file created +by `sq` that contains data in the format specified by OpenPGP. It +doesn't matter what the content of the file is. Thus, a file `foo.pgp` +may be one or more keys or certificates, an encrypted file, a signed +file, a detached signature, or something else. There are a lot of +possible types of file, and it's wiser to use the `sq inspect` command +to see what it actually it than to have an intricate naming system +trying to encode all possibilities to a short suffix. Worse, you can't +rely on suffixes: an attacker may change the name of a file at will. +For this reason, `sq` doesn't care what the name of a file or its +suffix is: you tell what the file is meant to be, and `sq` looks at +what it actually is, and gives an error if it's not what you thought +it was. + +We present "typescripts" of command line use like this: + +```{.sh .numberLines} +$ sq --version +sq 0.25.0 (sequoia-openpgp 1.7.0) +``` + +The first line (number 1) is the shell command. The `$` represents the +_shell prompt_: the dollar sign is traditional for Unix, but it's +likely that your actual prompt is different. The rest of the line is +the command you write to invoke a command. The rest of the typescript +is the output of the command. A typescript may contain multiple +command, and are all identified by a leading dollar sign. The line +numbers are there to make it clearer when a new line starts, and to +allow easily referring to a particular line. + +Sometimes we only show the command you type, without prompt, output, +or line numbers: + +``` +sq --version +``` + +We do this when there is no need to show the output or when we want to +make it extra clear what the command is. + # Installing `sq` This chapter explains how to install `sq` in various ways. It is by |