diff options
Diffstat (limited to 'spec/back-matter.md')
-rw-r--r-- | spec/back-matter.md | 70 |
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! + |