Copy all verbatim items into spec directory.

5 files changed, 211 insertions, 0 deletions

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 <a
+href="./proposals/BY_STATUS.html#finished-proposals-implemented-specs-not-merged">`FINISHED`
+Tor proposals</a>: They are the ones that have been implemented, but
+not yet merged into these documents.
+
+<a href="./proposals/index.html">You can also see all the Tor
+proposals here.</a>
+
+----
+
+# Permalinks
+
+Additionally, these URLs at `spec.toprorject.org` are intended to be
+long-term permalinks.
+
+TODO: Revise them to point somewhere sensible again.
+
+<dl>
+<dt><a href="/address-spec"><code>/address-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/address-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/address-spec.txt</code> (Special Hostnames in Tor)</a></dt>
+<dt><a href="/bandwidth-file-spec"><code>/bandwidth-file-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/bandwidth-file-spec.txt</code> (Directory Authority Bandwidth File spec)</a></dt>
+<dt><a href="/bridgedb-spec"><code>/bridgedb-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/bridgedb-spec.txt</code> (BridgeDB specification)</a></dt>
+<dt><a href="/cert-spec"><code>/cert-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt</code> (Ed25519 certificates in Tor)</a></dt>
+<dt><a href="/collector-protocol"><code>/collector-protocol</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL"><code>https://gitweb.torproject.org/collector.git/tree/src/main/resources/docs/PROTOCOL</code> (Protocol of CollecTor's File Structure)</a></dt>
+<dt><a href="/control-spec"><code>/control-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/control-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/control-spec.txt</code> (Tor control protocol, version 1)</a></dt>
+<dt><a href="/dir-spec"><code>/dir-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt</code> (Tor directory protocol, version 3)</a></dt>
+<dt><a href="/dir-list-spec"><code>/dir-list-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/dir-list-spec.txt</code> (Tor Directory List file format)</a></dt>
+<dt><a href="/ext-orport-spec"><code>/ext-orport-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/ext-orport-spec.txt</code> (Extended ORPort for pluggable transports)</a></dt>
+<dt><a href="/gettor-spec"><code>/gettor-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/gettor-spec.txt</code> (GetTor specification)</a></dt>
+<dt><a href="/padding-spec"><code>/padding-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/padding-spec.txt</code> (Tor Padding Specification)</a></dt>
+<dt><a href="/path-spec"><code>/path-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/path-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/path-spec.txt</code> (Tor Path Specification)</a></dt>
+<dt><a href="/pt-spec"><code>/pt-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/pt-spec.txt</code> (Tor Pluggable Transport Specification, version 1)</a></dt>
+<dt><a href="/rend-spec"><code>/rend-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt"><code>https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt</code> (Tor Onion Service Rendezvous Specification, Version 2)</a></dt>
+<dt><a href="/rend-spec-v2"><code>/rend-spec-v2</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt"><code>https://gitweb.torproject.org/torspec.git/tree/attic/rend-spec-v2.txt</code> (Tor Onion Service Rendezvous Specification, Version 2)</a></dt>
+<dt><a href="/rend-spec-v3"><code>/rend-spec-v3</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt"><code>https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt</code> (Tor Onion Service Rendezvous Specification, Version 3)</a></dt>
+<dt><a href="/socks-extensions"><code>/socks-extensions</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt"><code>https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt</code> (Tor's extensions to the SOCKS protocol)</a></dt>
+<dt><a href="/srv-spec"><code>/srv-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/srv-spec.txt</code> (Tor Shared Random Subsystem Specification)</a></dt>
+<dt><a href="/tor-fw-helper-spec"><code>/tor-fw-helper-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/attic/tor-fw-helper-spec.txt</code> (Tor's (little) Firewall Helper specification)</a></dt>
+<dt><a href="/tor-spec"><code>/tor-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt</code> (Tor Protocol Specification)</a></dt>
+<dt><a href="/torbrowser-design"><code>/torbrowser-design</code></a></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><a href="/version-spec"><code>/version-spec</code></a></dt>
+<dd><a href="https://gitweb.torproject.org/torspec.git/tree/version-spec.txt"><code>https://gitweb.torproject.org/torspec.git/tree/version-spec.txt</code> (How Tor Version Numbers Work)</a></dt>
+<dt><a href="/tor-design"><code>/tor-design</code></a></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><a href="/walking-onions"><code>/walking-onions</code></a></dt>
+<dd><a href="https://github.com/nmathewson/walking-onions-wip/tree/master/specs"><code>https://github.com/nmathewson/walking-onions-wip/tree/master/specs</code> (Walking Onions specifications (work in progress))</a></dt>
+
+</dl>