aboutsummaryrefslogtreecommitdiff
path: root/spec/back-matter.md
diff options
context:
space:
mode:
Diffstat (limited to 'spec/back-matter.md')
-rw-r--r--spec/back-matter.md70
1 files changed, 70 insertions, 0 deletions
diff --git a/spec/back-matter.md b/spec/back-matter.md
new file mode 100644
index 0000000..90ddea2
--- /dev/null
+++ b/spec/back-matter.md
@@ -0,0 +1,70 @@
+# 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).
+
+## Editing advice
+
+To edit these specs, clone the
+[git repository](https://gitlab.torproject.org/tpo/core/torspec/)
+and edit the
+appropriate file in the `spec` directory. These files will match
+the URLs of their corresponding pages, so if you want to edit
+`tor-spec/flow-control.html`,
+you'll be looking for a file
+called `spec/tor-spec/flow-control.md`.
+
+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!
+