diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-11-07 18:50:54 +0000 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-11-07 18:50:54 +0000 |
commit | af7d5d18a79847996ddb23bc7a3cb18cd6183eff (patch) | |
tree | 7d32fac333a80f83961023c6ba6015c64d49bf1d | |
parent | 63a2bcf36c68da56501afe11c6b83b2a12782b40 (diff) | |
parent | db3fc1550fb8b79152ca4adaa68e0e86d8eedf4c (diff) | |
download | torspec-af7d5d18a79847996ddb23bc7a3cb18cd6183eff.tar.gz torspec-af7d5d18a79847996ddb23bc7a3cb18cd6183eff.zip |
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
-rw-r--r-- | README.md | 33 | ||||
-rwxr-xr-x | bin/make_redirects | 10 | ||||
-rw-r--r-- | spec/README.md | 85 | ||||
-rw-r--r-- | spec/STYLE.md | 27 | ||||
-rw-r--r-- | spec/SUMMARY.md | 5 | ||||
-rw-r--r-- | spec/back-matter.md | 54 | ||||
-rw-r--r-- | spec/permalinks.md | 57 |
7 files changed, 155 insertions, 116 deletions
@@ -1,31 +1,12 @@ # Tor specification repository -**IF YOU WANT TO READ THESE SPECS, -[GO HERE](https://tpo.pages.torproject.net/core/torspec/).** (It is a temporoary location; we intend to move it to `spec.torproject.org`. +This is the source code of the Tor specification documents. -This is the central location for editing and maintaining the Tor -specifications and proposals for feature changes. +**To read the Tor Specifications online**, +please go to the canonical site <https://spec.torproject.org/>. -The specification is rendered at -[better-url-here](https://tpo.pages.torproject.net/core/torspec/); -if you want to _read_ the specifications, that is the place to start. +Overview of the source code layout, and build instructions, +are in `spec/back-matter.md`. -The official site for this repository is on -[gitlab.torproject.org](https://gitlab.torproject.org/tpo/core/torspec/) - -We use mdBook to convert these specifications into the webpages you see above. -For more information about editing them, start with the -[mdBook manual]([mdBook]((https://rust-lang.github.io/mdBook/)). - -The core of this repository is: - * `spec` — A set of markdown files which contain the specifications. - The file `src/SUMAMRY.md` controls their ordering within the - rendered specification. - * `proposals` — A directory of change proposals for the Tor protocols. - -Additionally, this repository contains: - * `mdbook` — A configuration file controlling how the specifications - are rendered. - * `attic` — Obsolete specifications describing no-longer-in-use - pieces of the Tor specification, and obsolete formats of the - existing specifications. +The canonical source repository is on the Tor Project's gitab, at +<https://gitlab.torproject.org/tpo/core/torspec/> diff --git a/bin/make_redirects b/bin/make_redirects index 4cd4e05..a26b871 100755 --- a/bin/make_redirects +++ b/bin/make_redirects @@ -16,8 +16,8 @@ def update_file(fname, start_marker, end_marker, replacement): BOOK_START = "# BEGIN AUTO-GENERATED REDIRECTS\n" BOOK_END = "# END AUTO-GENERATED REDIRECTS\n" -README_START = "<!-- BEGIN AUTO-GENERATED REDIRECTS -->\n" -README_END = "<!-- END AUTO-GENERATED REDIRECTS -->\n" +HTML_MARKER_START = "<!-- BEGIN AUTO-GENERATED REDIRECTS -->\n" +HTML_MARKER_END = "<!-- END AUTO-GENERATED REDIRECTS -->\n" def book_redirects(rs, spec_dir): lines = [] @@ -38,7 +38,7 @@ def book_redirects(rs, spec_dir): ) return "".join(lines) -def readme_redirects(rs): +def permalinks_redirects(rs): lines = [ "<dl>\n" ] for kwd, info in rs.items(): target = info['target'] @@ -66,7 +66,7 @@ if __name__ == '__main__': toplevel = os.path.join(os.path.dirname(sys.argv[0]), "..") spec_book_fname = os.path.join(toplevel, "mdbook", "spec", "book.toml") spec_dir = os.path.join(toplevel, "spec") - readme_fname = os.path.join(toplevel, "spec", "README.md") + permalinks_fname = os.path.join(toplevel, "spec", "permalinks.md") prop_dir = os.path.join(toplevel, "proposals") prop_book_fname = os.path.join(toplevel, "mdbook", "proposals", "book.toml") yaml_fname = os.path.join(toplevel, "mdbook", "spec", "spec-redirects.yaml") @@ -74,5 +74,5 @@ if __name__ == '__main__': rs = yaml.load(open(yaml_fname), yaml.Loader)['redirects'] update_file(spec_book_fname, BOOK_START, BOOK_END, book_redirects(rs, spec_dir)) - update_file(readme_fname, README_START, README_END, readme_redirects(rs)) + update_file(permalinks_fname, HTML_MARKER_START, HTML_MARKER_END, permalinks_redirects(rs)) update_file(prop_book_fname, BOOK_START, BOOK_END, proposal_redirects(prop_dir)) 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 --> |