spec/back-matter.md

   1 # About the Tor Specifications documents
   2
   3 The canonical, official, versions of these documents are on the
   4 [Tor Specifications website](https://spec.torproject.org/)
   5 maintained by the [Tor Project](https://www.torproject.org/).
   6
   7 Only the Tor Specifications themselves are approved.
   8 The [Proposals](../proposals/) are, by their nature, drafts.
   9
  10 When linking to the Specifications,
  11 consider using one of the links advertised in the
  12 [Table of Permalinks](permalinks.html).
  13
  14 ## Source code
  15
  16 The Specifications and Proposals are maintained by the Tor Project
  17 in a
  18 [gitlab repository](https://gitlab.torproject.org/tpo/core/torspec/).
  19
  20 Corrections and clarifications are welcome.
  21 To propose a change to the Tor protocol, use the
  22 [Proposals process](proposals/001-process.txt)
  23
  24 ## Building
  25
  26 The documents are in Markdown and formatted with
  27 [mdbook](https://rust-lang.github.io/mdBook/).
  28 To build the formatted HTML:
  29
  30 ```text,ignore
  31 cargo install mdbook
  32 git clone https://gitlab.torproject.org/tpo/core/torspec/
  33 cd torspec
  34 bin/build_html
  35 ```
  36
  37 The output is then in `html/`.
  38
  39 ## Source code structure, and output webtree
  40
  41 There are two mdbook books here:
  42
  43  * **The Tor Specifications**: source code in `specs/`,
  44    formatted output in `html/`.
  45
  46  * **Proposals**: source code in `proposals/`,
  47    formatted output in `html/proposals/`.
  48
  49 Each book's source files are listed,
  50 and the chapter defined,
  51 in its `SUMMARY.md`.
  52 The format is pretty restrictive;
  53 see the
  54 [mdbook documentation](https://rust-lang.github.io/mdBook/format/summary.html).
  55
  56 ## Editing advice
  57
  58 To edit these specs, clone the
  59 [git repository](https://gitlab.torproject.org/tpo/core/torspec/)
  60 and edit the
  61 appropriate file in the `spec` directory.  These files will match
  62 the URLs of their corresponding pages, so if you want to edit
  63 `tor-spec/flow-control.html`,
  64 you'll be looking for a file
  65 called `spec/tor-spec/flow-control.md`.
  66
  67 We have started a [style guide](./STYLE.md) for writing new parts of
  68 this spec; as of 2023 it is quite preliminary. You should feel free to
  69 edit it!
  70