Merge branch 'motion' into 'main'

Add a new backmatter section, and move/replace parts of spec/README.md, etc.

See merge request tpo/core/torspec!198

5 files changed, 143 insertions, 85 deletions

diff --git a/spec/README.md b/spec/README.md
index f4f8d1a..0ed46e0 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -61,93 +61,8 @@ need to have mdbook installed to do this.)
 We have started a [style guide](./STYLE.md) for writing new parts of
 this spec; as of 2023 it is quite preliminary. You should feel free to
 edit it!
-
-### Managing links
-
-We're in the early stages of this spec organization, but we should
-still be thinking about long term maintainability.
-
-Please think about how to keep links working in the long term.
-If you are going to add a link to a file, make sure that the file's
-name is reasonable.  Before you rename a file, consider adding
-a redirect from the file's old name.  (See the mdbook documentation
-for more information about how.)
-
-If you want to link to a specific section within a file,
-make sure that the section has a defined anchor that makes sense.
-The syntax to define [heading ids] in mdbook looks like this:
-
-`## Heading with a long title that you want shorter name for { #shortname }`
-
-If you need to change a heading, make sure that you keep its
-`id` the same as it was before, so that links will still work.
-
-Finally, when you're looking for specific sections (e.g., to fix
-references that say "See section 5.2.3") you can look for the HTML
-anchors that our conversion process added.  For example,
-if you want to find `dir-spec.txt` section 2.1.3, look for
-the anchor that says `<a id="dir-spec.txt-2.1.3"></a>`.
-
 ______________________________________________________________________
 
-## Permalinks
-
-Additionally, these URLs at `spec.toprorject.org` are intended to be
-long-term permalinks.
-
-<!-- BEGIN AUTO-GENERATED REDIRECTS -->
-<dl>
-<dt><code>/address-spec</code></dt>
-<dd><a href="https://spec.torproject.org/address-spec"><code>https://spec.torproject.org/address-spec</code> (Special Hostnames in Tor)</a></dt>
-<dt><code>/bandwidth-file-spec</code></dt>
-<dd><a href="https://spec.torproject.org/bandwidth-file-spec"><code>https://spec.torproject.org/bandwidth-file-spec</code> (Directory Authority Bandwidth File spec)</a></dt>
-<dt><code>/bridgedb-spec</code></dt>
-<dd><a href="https://spec.torproject.org/bridgedb-spec"><code>https://spec.torproject.org/bridgedb-spec</code> (BridgeDB specification)</a></dt>
-<dt><code>/cert-spec</code></dt>
-<dd><a href="https://spec.torproject.org/cert-spec"><code>https://spec.torproject.org/cert-spec</code> (Ed25519 certificates in Tor)</a></dt>
-<dt><code>/collector-protocol</code></dt>
-<dd><a href="https://gitlab.torproject.org/tpo/network-health/metrics/collector/-/blob/master/src/main/resources/docs/PROTOCOL?ref_type=heads"><code>https://gitlab.torproject.org/tpo/network-health/metrics/collector/-/blob/master/src/main/resources/docs/PROTOCOL?ref_type=heads</code> (Protocol of CollecTor's File Structure)</a></dt>
-<dt><code>/control-spec</code></dt>
-<dd><a href="https://spec.torproject.org/control-spec"><code>https://spec.torproject.org/control-spec</code> (Tor control protocol, version 1)</a></dt>
-<dt><code>/dir-spec</code></dt>
-<dd><a href="https://spec.torproject.org/dir-spec"><code>https://spec.torproject.org/dir-spec</code> (Tor directory protocol, version 3)</a></dt>
-<dt><code>/dir-list-spec</code></dt>
-<dd><a href="https://spec.torproject.org/dir-list-spec"><code>https://spec.torproject.org/dir-list-spec</code> (Tor Directory List file format)</a></dt>
-<dt><code>/ext-orport-spec</code></dt>
-<dd><a href="https://spec.torproject.org/ext-orport-spec"><code>https://spec.torproject.org/ext-orport-spec</code> (Extended ORPort for pluggable transports)</a></dt>
-<dt><code>/gettor-spec</code></dt>
-<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/attic/text_formats/gettor-spec.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/attic/text_formats/gettor-spec.txt?ref_type=heads</code> (GetTor specification)</a></dt>
-<dt><code>/padding-spec</code></dt>
-<dd><a href="https://spec.torproject.org/padding-spec"><code>https://spec.torproject.org/padding-spec</code> (Tor Padding Specification)</a></dt>
-<dt><code>/path-spec</code></dt>
-<dd><a href="https://spec.torproject.org/path-spec"><code>https://spec.torproject.org/path-spec</code> (Tor Path Specification)</a></dt>
-<dt><code>/pt-spec</code></dt>
-<dd><a href="https://spec.torproject.org/pt-spec"><code>https://spec.torproject.org/pt-spec</code> (Tor Pluggable Transport Specification, version 1)</a></dt>
-<dt><code>/rend-spec</code></dt>
-<dd><a href="https://spec.torproject.org/rend-spec"><code>https://spec.torproject.org/rend-spec</code> (Tor Onion Service Rendezvous Specification, latest version)</a></dt>
-<dt><code>/rend-spec-v2</code></dt>
-<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/rend-spec-v2.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/rend-spec-v2.txt?ref_type=heads</code> (Tor Onion Service Rendezvous Specification, Version 2 (Obsolete))</a></dt>
-<dt><code>/rend-spec-v3</code></dt>
-<dd><a href="https://spec.torproject.org/rend-spec"><code>https://spec.torproject.org/rend-spec</code> (Tor Onion Service Rendezvous Specification, Version 3 (Latest))</a></dt>
-<dt><code>/socks-extensions</code></dt>
-<dd><a href="https://spec.torproject.org/socks-extensions"><code>https://spec.torproject.org/socks-extensions</code> (Tor's extensions to the SOCKS protocol)</a></dt>
-<dt><code>/srv-spec</code></dt>
-<dd><a href="https://spec.torproject.org/srv-spec"><code>https://spec.torproject.org/srv-spec</code> (Tor Shared Random Subsystem Specification)</a></dt>
-<dt><code>/tor-fw-helper-spec</code></dt>
-<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/tor-fw-helper-spec.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/tor-fw-helper-spec.txt?ref_type=heads</code> (Tor's (little) Firewall Helper specification)</a></dt>
-<dt><code>/tor-spec</code></dt>
-<dd><a href="https://spec.torproject.org/tor-spec"><code>https://spec.torproject.org/tor-spec</code> (Tor Protocol Specification)</a></dt>
-<dt><code>/torbrowser-design</code></dt>
-<dd><a href="https://2019.www.torproject.org/projects/torbrowser/design/"><code>https://2019.www.torproject.org/projects/torbrowser/design/</code> (The Design and Implementation of the Tor Browser)</a></dt>
-<dt><code>/version-spec</code></dt>
-<dd><a href="https://spec.torproject.org/version-spec"><code>https://spec.torproject.org/version-spec</code> (How Tor Version Numbers Work)</a></dt>
-<dt><code>/tor-design</code></dt>
-<dd><a href="https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf"><code>https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf</code> (Tor: The Second-Generation Onion Router)</a></dt>
-<dt><code>/walking-onions</code></dt>
-<dd><a href="https://spec.torproject.org/proposals/323-walking-onions-full.html"><code>https://spec.torproject.org/proposals/323-walking-onions-full.html</code> (Walking Onions specifications)</a></dt>
-</dl>
-<!-- END AUTO-GENERATED REDIRECTS -->
-
 [git repository]: https://gitlab.torproject.org/tpo/core/torspec/
 [heading ids]: https://github.com/raphlinus/pulldown-cmark/blob/master/specs/heading_attrs.txt
 [mdbook documentation]: https://rust-lang.github.io/mdBook/format/summary.html
diff --git a/spec/STYLE.md b/spec/STYLE.md
index 9fe4584..78b5c8a 100644
--- a/spec/STYLE.md
+++ b/spec/STYLE.md
@@ -114,3 +114,30 @@ Neither of these is really great.  We should find something better.
 > normative text, it is a good idea to put it in quoted text, like
 > this.
 
+
+## Managing links
+
+We're in the early stages of this spec organization, but we should
+still be thinking about long term maintainability.
+
+Please think about how to keep links working in the long term.
+If you are going to add a link to a file, make sure that the file's
+name is reasonable.  Before you rename a file, consider adding
+a redirect from the file's old name.  (See the mdbook documentation
+for more information about how.)
+
+If you want to link to a specific section within a file,
+make sure that the section has a defined anchor that makes sense.
+The syntax to define [heading ids] in mdbook looks like this:
+
+`## Heading with a long title that you want shorter name for { #shortname }`
+
+If you need to change a heading, make sure that you keep its
+`id` the same as it was before, so that links will still work.
+
+Finally, when you're looking for specific sections (e.g., to fix
+references that say "See section 5.2.3") you can look for the HTML
+anchors that our conversion process added.  For example,
+if you want to find `dir-spec.txt` section 2.1.3, look for
+the anchor that says `<a id="dir-spec.txt-2.1.3"></a>`.
+
diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md
index 03ed3f1..7d1d368 100644
--- a/spec/SUMMARY.md
+++ b/spec/SUMMARY.md
@@ -171,3 +171,8 @@
 
 - [`Glossary`](./glossary.md)
 - [`Style guide`](./STYLE.md)
+
+# Maintenance and and editing of the Tor Specifications
+
+- [`About the Tor Specifications documents`](./back-matter.md)
+- [`Permalinks`](./permalinks.md)
diff --git a/spec/back-matter.md b/spec/back-matter.md
new file mode 100644
index 0000000..59463ce
--- /dev/null
+++ b/spec/back-matter.md
@@ -0,0 +1,54 @@
+# About the Tor Specifications documents
+
+The canonical, official, versions of these documents are on the
+[Tor Specifications website](https://spec.torproject.org/)
+maintained by the [Tor Project](https://www.torproject.org/).
+
+Only the Tor Specifications themselves are approved.
+The [Proposals](../proposals/) are, by their nature, drafts.
+
+When linking to the Specifications,
+consider using one of the links advertised in the
+[Table of Permalinks](permalinks.html).
+
+## Source code
+
+The Specifications and Proposals are maintained by the Tor Project
+in a
+[gitlab repository](https://gitlab.torproject.org/tpo/core/torspec/).
+
+Corrections and clarifications are welcome.
+To propose a change to the Tor protocol, use the
+[Proposals process](proposals/001-process.txt)
+
+## Building
+
+The documents are in Markdown and formatted with
+[mdbook](https://rust-lang.github.io/mdBook/).
+To build the formatted HTML:
+
+```text,ignore
+cargo install mdbook
+git clone https://gitlab.torproject.org/tpo/core/torspec/
+cd torspec
+bin/build_html
+```
+
+The output is then in `html/`.
+
+## Source code structure, and output webtree
+
+There are two mdbook books here:
+
+ * **The Tor Specifications**: source code in `specs/`,
+   formatted output in `html/`.
+
+ * **Proposals**: source code in `proposals/`,
+   formatted output in `html/proposals/`.
+
+Each book's source files are listed,
+and the chapter defined,
+in its `SUMMARY.md`.
+The format is pretty restrictive;
+see the
+[mdbook documentation](https://rust-lang.github.io/mdBook/format/summary.html).
diff --git a/spec/permalinks.md b/spec/permalinks.md
new file mode 100644
index 0000000..052d48f
--- /dev/null
+++ b/spec/permalinks.md
@@ -0,0 +1,57 @@
+# Permalinks
+
+These URLs at `spec.toprorject.org` are intended to be
+long-term permalinks.
+
+<!-- BEGIN AUTO-GENERATED REDIRECTS -->
+<dl>
+<dt><code>/address-spec</code></dt>
+<dd><a href="https://spec.torproject.org/address-spec"><code>https://spec.torproject.org/address-spec</code> (Special Hostnames in Tor)</a></dt>
+<dt><code>/bandwidth-file-spec</code></dt>
+<dd><a href="https://spec.torproject.org/bandwidth-file-spec"><code>https://spec.torproject.org/bandwidth-file-spec</code> (Directory Authority Bandwidth File spec)</a></dt>
+<dt><code>/bridgedb-spec</code></dt>
+<dd><a href="https://spec.torproject.org/bridgedb-spec"><code>https://spec.torproject.org/bridgedb-spec</code> (BridgeDB specification)</a></dt>
+<dt><code>/cert-spec</code></dt>
+<dd><a href="https://spec.torproject.org/cert-spec"><code>https://spec.torproject.org/cert-spec</code> (Ed25519 certificates in Tor)</a></dt>
+<dt><code>/collector-protocol</code></dt>
+<dd><a href="https://gitlab.torproject.org/tpo/network-health/metrics/collector/-/blob/master/src/main/resources/docs/PROTOCOL?ref_type=heads"><code>https://gitlab.torproject.org/tpo/network-health/metrics/collector/-/blob/master/src/main/resources/docs/PROTOCOL?ref_type=heads</code> (Protocol of CollecTor's File Structure)</a></dt>
+<dt><code>/control-spec</code></dt>
+<dd><a href="https://spec.torproject.org/control-spec"><code>https://spec.torproject.org/control-spec</code> (Tor control protocol, version 1)</a></dt>
+<dt><code>/dir-spec</code></dt>
+<dd><a href="https://spec.torproject.org/dir-spec"><code>https://spec.torproject.org/dir-spec</code> (Tor directory protocol, version 3)</a></dt>
+<dt><code>/dir-list-spec</code></dt>
+<dd><a href="https://spec.torproject.org/dir-list-spec"><code>https://spec.torproject.org/dir-list-spec</code> (Tor Directory List file format)</a></dt>
+<dt><code>/ext-orport-spec</code></dt>
+<dd><a href="https://spec.torproject.org/ext-orport-spec"><code>https://spec.torproject.org/ext-orport-spec</code> (Extended ORPort for pluggable transports)</a></dt>
+<dt><code>/gettor-spec</code></dt>
+<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/attic/text_formats/gettor-spec.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/raw/main/attic/text_formats/gettor-spec.txt?ref_type=heads</code> (GetTor specification)</a></dt>
+<dt><code>/padding-spec</code></dt>
+<dd><a href="https://spec.torproject.org/padding-spec"><code>https://spec.torproject.org/padding-spec</code> (Tor Padding Specification)</a></dt>
+<dt><code>/path-spec</code></dt>
+<dd><a href="https://spec.torproject.org/path-spec"><code>https://spec.torproject.org/path-spec</code> (Tor Path Specification)</a></dt>
+<dt><code>/pt-spec</code></dt>
+<dd><a href="https://spec.torproject.org/pt-spec"><code>https://spec.torproject.org/pt-spec</code> (Tor Pluggable Transport Specification, version 1)</a></dt>
+<dt><code>/rend-spec</code></dt>
+<dd><a href="https://spec.torproject.org/rend-spec"><code>https://spec.torproject.org/rend-spec</code> (Tor Onion Service Rendezvous Specification, latest version)</a></dt>
+<dt><code>/rend-spec-v2</code></dt>
+<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/rend-spec-v2.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/rend-spec-v2.txt?ref_type=heads</code> (Tor Onion Service Rendezvous Specification, Version 2 (Obsolete))</a></dt>
+<dt><code>/rend-spec-v3</code></dt>
+<dd><a href="https://spec.torproject.org/rend-spec"><code>https://spec.torproject.org/rend-spec</code> (Tor Onion Service Rendezvous Specification, Version 3 (Latest))</a></dt>
+<dt><code>/socks-extensions</code></dt>
+<dd><a href="https://spec.torproject.org/socks-extensions"><code>https://spec.torproject.org/socks-extensions</code> (Tor's extensions to the SOCKS protocol)</a></dt>
+<dt><code>/srv-spec</code></dt>
+<dd><a href="https://spec.torproject.org/srv-spec"><code>https://spec.torproject.org/srv-spec</code> (Tor Shared Random Subsystem Specification)</a></dt>
+<dt><code>/tor-fw-helper-spec</code></dt>
+<dd><a href="https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/tor-fw-helper-spec.txt?ref_type=heads"><code>https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/attic/tor-fw-helper-spec.txt?ref_type=heads</code> (Tor's (little) Firewall Helper specification)</a></dt>
+<dt><code>/tor-spec</code></dt>
+<dd><a href="https://spec.torproject.org/tor-spec"><code>https://spec.torproject.org/tor-spec</code> (Tor Protocol Specification)</a></dt>
+<dt><code>/torbrowser-design</code></dt>
+<dd><a href="https://2019.www.torproject.org/projects/torbrowser/design/"><code>https://2019.www.torproject.org/projects/torbrowser/design/</code> (The Design and Implementation of the Tor Browser)</a></dt>
+<dt><code>/version-spec</code></dt>
+<dd><a href="https://spec.torproject.org/version-spec"><code>https://spec.torproject.org/version-spec</code> (How Tor Version Numbers Work)</a></dt>
+<dt><code>/tor-design</code></dt>
+<dd><a href="https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf"><code>https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf</code> (Tor: The Second-Generation Onion Router)</a></dt>
+<dt><code>/walking-onions</code></dt>
+<dd><a href="https://spec.torproject.org/proposals/323-walking-onions-full.html"><code>https://spec.torproject.org/proposals/323-walking-onions-full.html</code> (Walking Onions specifications)</a></dt>
+</dl>
+<!-- END AUTO-GENERATED REDIRECTS -->