From dc6ffd831b5f6189b1516007b1966070ba8613f9 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@sequoia-pgp.org>
Date: Tue, 15 Feb 2022 10:12:14 +0200
Subject: doc: add section on document conventions

Sponsored-by: pep.foundation
---
 sq-guide.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

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
-- 
cgit v1.2.1