From 7589a207493f5a3200823bc340bccb24987b8164 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 12 Oct 2023 12:27:58 -0400 Subject: Copy all verbatim items into spec directory. --- README.md | 56 +++++++++++++++++++++++++++++++++ build_html.sh | 15 +++++++++ mdbook/proposals/book.toml | 22 +++++++++++++ mdbook/spec/book.toml | 41 ++++++++++++++++++++++++ spec/INTRO.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 211 insertions(+) create mode 100644 README.md create mode 100755 build_html.sh create mode 100644 mdbook/proposals/book.toml create mode 100644 mdbook/spec/book.toml create mode 100644 spec/INTRO.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b7ba56a --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# DRAFT DRAFT DRAFT + +This is a demonstration, showing what the torspec.git repository +might look like after a conversion to use +[mdBook](https://rust-lang.github.io/mdBook/). + +For an example of what people will see when they look at the +_rendered_ version of this repository, see +[this temporary URL](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html). + +If and when we deploy this conversion, we should delete this section, +and have the rest of this document become the new `README.md`. + +—nickm + + + + +------------------------------ + +# Tor specification repository + +**IF YOU WANT TO READ THESE SPECS, +[GO HERE](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html).** + +This is the central location for editing and maintaining the Tor +specifications and proposals for feature changes. + +The specification is rendered at +[better-url-here](https://people.torproject.org/~nickm/volatile/mdbook-specs/index.html); +if you want to _read_ the specifications, that is the place to start. + +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. + + + + + diff --git a/build_html.sh b/build_html.sh new file mode 100755 index 0000000..ae78080 --- /dev/null +++ b/build_html.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +set -e -u -o pipefail + +TOPLEVEL=$(realpath $(dirname "$0")) +cd "${TOPLEVEL}/proposals" +./reindex.py + +cd "${TOPLEVEL}/mdbook/spec" +mdbook build + +cd "${TOPLEVEL}/mdbook/proposals" +mdbook build + + diff --git a/mdbook/proposals/book.toml b/mdbook/proposals/book.toml new file mode 100644 index 0000000..d7b5981 --- /dev/null +++ b/mdbook/proposals/book.toml @@ -0,0 +1,22 @@ +[book] +authors = ["The Tor Project"] +language = "en" +multilingual = false +src = "../../proposals" +title = "Tor proposals (draft mdbook port)" +use-default-preprocessors = false + +[build] +build-dir = "../../html/proposals" + +[preprocessor.links] + +# [preprocessor.pagetoc] + +[output.html] +# additional-css = ["theme/pagetoc.css"] +# additional-js = ["theme/pagetoc.js"] +no-section-label = true + +[output.html.search] +enable = false \ No newline at end of file diff --git a/mdbook/spec/book.toml b/mdbook/spec/book.toml new file mode 100644 index 0000000..de2ad99 --- /dev/null +++ b/mdbook/spec/book.toml @@ -0,0 +1,41 @@ +[book] +authors = ["The Tor Project"] +language = "en" +multilingual = false +src = "../../spec" +title = "Tor specifications (draft mdbook port)" + +[build] +build-dir = "../../html" + +# [preprocessor.pagetoc] + +[output.html] +# additional-css = ["theme/pagetoc.css"] +# additional-js = ["theme/pagetoc.js"] + +[output.html.redirect] +"/address-spec" = "https://gitweb.torproject.org/torspec.git/tree/address-spec.txt" +# "/bandwidth-file-spec" = "https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt" +"/bridgedb-spec" = "https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt" +"/cert-spec" = "https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt" +"/collector-protocol" = "https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL" +# "/control-spec" = "https://gitweb.torproject.org/torspec.git/tree/control-spec.txt" +# "/dir-spec" = "https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt" +"/dir-list-spec" = "https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt" +"/ext-orport-spec" = "https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt" +"/gettor-spec" = "https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt" +# "/padding-spec" = "https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt" +# "/path-spec" = "https://gitweb.torproject.org/torspec.git/tree/path-spec.txt" +# "/pt-spec" = "https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt" +"/rend-spec" = "https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt" +"/rend-spec-v2" = "https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt" +# "/rend-spec-v3" = "https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt" +"/socks-extensions" = "https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt" +# "/srv-spec" = "https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt" +"/tor-fw-helper-spec" = "https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt" +# "/tor-spec" = "https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt" +"/torbrowser-design" = "https://2019.www.torproject.org/projects/torbrowser/design/" +"/version-spec" = "https://gitweb.torproject.org/torspec.git/tree/version-spec.txt" +"/tor-design" = "https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf" +"/walking-onions" = "https://github.com/nmathewson/walking-onions-wip/tree/master/specs" diff --git a/spec/INTRO.md b/spec/INTRO.md new file mode 100644 index 0000000..ddfe886 --- /dev/null +++ b/spec/INTRO.md @@ -0,0 +1,77 @@ +# Tor specifications + +These documents describe how Tor works, and try to do so in enough +detail to allow other compatible implementations of the Tor protocols. + +They were once a separate set of text files, but in late 2023 we +migrated to use [`mdbook`](https://rust-lang.github.io/mdBook/). +We're in the process of updating these documents to improve their quality. + +In addition to these specifications, you should look at the set of `FINISHED` +Tor proposals: They are the ones that have been implemented, but +not yet merged into these documents. + +You can also see all the Tor +proposals here. + +---- + +# Permalinks + +Additionally, these URLs at `spec.toprorject.org` are intended to be +long-term permalinks. + +TODO: Revise them to point somewhere sensible again. + +
+
/address-spec
+
https://gitweb.torproject.org/torspec.git/tree/address-spec.txt (Special Hostnames in Tor) +
/bandwidth-file-spec
+
https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt (Directory Authority Bandwidth File spec) +
/bridgedb-spec
+
https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt (BridgeDB specification) +
/cert-spec
+
https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt (Ed25519 certificates in Tor) +
/collector-protocol
+
https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL (Protocol of CollecTor's File Structure) +
/control-spec
+
https://gitweb.torproject.org/torspec.git/tree/control-spec.txt (Tor control protocol, version 1) +
/dir-spec
+
https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt (Tor directory protocol, version 3) +
/dir-list-spec
+
https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt (Tor Directory List file format) +
/ext-orport-spec
+
https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt (Extended ORPort for pluggable transports) +
/gettor-spec
+
https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt (GetTor specification) +
/padding-spec
+
https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt (Tor Padding Specification) +
/path-spec
+
https://gitweb.torproject.org/torspec.git/tree/path-spec.txt (Tor Path Specification) +
/pt-spec
+
https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt (Tor Pluggable Transport Specification, version 1) +
/rend-spec
+
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 2) +
/rend-spec-v2
+
https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt (Tor Onion Service Rendezvous Specification, Version 2) +
/rend-spec-v3
+
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt (Tor Onion Service Rendezvous Specification, Version 3) +
/socks-extensions
+
https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt (Tor's extensions to the SOCKS protocol) +
/srv-spec
+
https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt (Tor Shared Random Subsystem Specification) +
/tor-fw-helper-spec
+
https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt (Tor's (little) Firewall Helper specification) +
/tor-spec
+
https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt (Tor Protocol Specification) +
/torbrowser-design
+
https://2019.www.torproject.org/projects/torbrowser/design/ (The Design and Implementation of the Tor Browser) +
/version-spec
+
https://gitweb.torproject.org/torspec.git/tree/version-spec.txt (How Tor Version Numbers Work) +
/tor-design
+
https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf (Tor: The Second-Generation Onion Router) +
/walking-onions
+
https://github.com/nmathewson/walking-onions-wip/tree/master/specs (Walking Onions specifications (work in progress)) + +
-- cgit v1.2.3-54-g00ecf