Start a "conventions" section to span all the specs

It's short for now, but we will extract more and more things from
the rest of the specifications as we continue editing.

4 files changed, 81 insertions, 25 deletions

diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md
index 6216162..d17a6c0 100644
--- a/spec/SUMMARY.md
+++ b/spec/SUMMARY.md
@@ -5,6 +5,7 @@
 # Introduction
 
 - [A short introduction to Tor](./intro/index.md)
+  - [Notation and conventions](./intro/conventions.md)
 
 # The core Tor protocol
 
diff --git a/spec/intro/conventions.md b/spec/intro/conventions.md
new file mode 100644
index 0000000..3563a33
--- /dev/null
+++ b/spec/intro/conventions.md
@@ -0,0 +1,77 @@
+# Notation and conventions
+
+These conventions apply,
+at least in theory,
+to all of the specification documents
+unless stated otherwise.
+
+> Remember, our specification documents
+> were once a collection of separate text files,
+> written separately
+> and edited over the course of years.
+>
+> While we are trying (as of 2023)
+> to edit them into consistency,
+> you should be aware that these conventions
+> are not now followed uniformly everywhere.
+
+## MUST, SHOULD, and so on {#rfc2119}
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in
+[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+## Data lengths {#data-lengths}
+
+Unless otherwise stated,
+all lengths are given as a number of 8-bit bytes.
+
+> All bytes are 8 bits long.
+> We sometimes call them "octets";
+> the terms as used here are interchangeable.
+
+When referring to longer lengths,
+we use [SI binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix)
+(as in "kibibytes", "mebibytes", and so on)
+to refer unambiguously to increments of 1024<sup>X</sup> bytes.
+
+> If you encounter a reference
+> to "kilobytes", "megabytes", or so on,
+> you cannot safely infer whether the author intended
+> a decimal (1000<sup>N</sup>) or binary (1024<sup>N</sup>) interpretation.
+> In these cases, it is better to revise the specifications.
+
+<a id="tor-spec.txt-0.1.1"></a>
+
+## Integer encoding {#integers}
+
+Unless otherwise stated,
+all multi-byte integers are encoded
+in big-endian ("network") order.
+
+> For example, 4660 (0x1234),
+> when encoded as a two-byte integer,
+> is the byte 0x12 followed by the byte 0x34. (\[12 34\])
+>
+> When encoded as a four-byte integer,
+> it is the byte 0x00, the byte 0x00, the byte 0x12, and the byte 0x34.
+> (\[00 00 12 34\]).
+
+## Notation {#notation}
+
+### Binary literals {#binary-literals}
+
+When we write a series of one-byte hexadecimal literals
+in square brackets,
+it represents a multi-byte binary string.
+
+> For example,
+> `[6f 6e 69 6f 6e 20 72 6f 75 74 69 6e 67]`
+> is a 13-byte sequence representing the unterminated ASCII string,
+> `onion routing`.
+
+
+
+
+
diff --git a/spec/tor-spec/opening-streams.md b/spec/tor-spec/opening-streams.md
index d59e26b..757f776 100644
--- a/spec/tor-spec/opening-streams.md
+++ b/spec/tor-spec/opening-streams.md
@@ -26,8 +26,9 @@ fingerprinting.  Implementations MUST accept strings in any case.
 
 The FLAGS value has one or more of the following bits set, where
 "bit 1" is the LSB of the 32-bit value, and "bit 32" is the MSB.
-(Remember that all values in Tor are big-endian (see
-["Preliminaries » Encoding integers"](./preliminaries.md#encoding)), so
+(Remember that
+[all integers in Tor are big-endian](../intro/conventions.md),
+so
 the MSB of a 4-byte value is the MSB of the first byte, and the LSB
 of a 4-byte value is the LSB of its last byte.)
 
diff --git a/spec/tor-spec/preliminaries.md b/spec/tor-spec/preliminaries.md
index 8cc92b7..60359af 100644
--- a/spec/tor-spec/preliminaries.md
+++ b/spec/tor-spec/preliminaries.md
@@ -2,13 +2,6 @@
 
 # Preliminaries
 
-```text
-      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
-      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
-      "OPTIONAL" in this document are to be interpreted as described in
-      RFC 2119.
-```
-
 <a id="tor-spec.txt-0.1"></a>
 
 ## Notation and encoding{#notation-and-encoding}
@@ -23,26 +16,10 @@
    a|b -- concatenation of 'a' and 'b'.
 ```
 
-\[A0 B1 C2\] -- a three-byte sequence, containing the bytes with
-hexadecimal values A0, B1, and C2, in that order.
-
 H(m) -- a cryptographic hash of m.
 
-We use "byte" and "octet" interchangeably.  Possibly we shouldn't.
-
 Some specs mention "base32".  This means RFC4648, without "=" padding.
 
-<a id="tor-spec.txt-0.1.1"></a>
-
-### Encoding integers{#encoding}
-
-Unless we explicitly say otherwise below, all numeric values in the
-Tor protocol are encoded in network (big-endian) order.  So a "32-bit
-integer" means a big-endian 32-bit integer; a "2-byte" integer means
-a big-endian 16-bit integer, and so forth.
-
-<a id="tor-spec.txt-0.2"></a>
-
 ## Security parameters
 
 Tor uses a stream cipher, a public-key cipher, the Diffie-Hellman