Remove more TOCs and merge in introductions.

10 files changed, 219 insertions, 486 deletions

diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md
index 08ae2c3..b0b4a10 100644
--- a/spec/SUMMARY.md
+++ b/spec/SUMMARY.md
@@ -27,7 +27,6 @@
   - [Subprotocol versioning](./tor-spec/subprotocol-versioning.md)
   - [`Ed25519 certificates in Tor`](./cert-spec.md)
 - [`Tor directory protocol, version 3`](./dir-spec-intro.md)
-  - [Scope and preliminaries](./dir-spec/scope-preliminaries.md)
   - [Outline](./dir-spec/outline.md)
   - [Router operation and formats](./dir-spec/router-operation-formats.md)
     - [Uploading server descriptors and extra-info documents](./dir-spec/uploading-relay-documents.md)
@@ -73,7 +72,6 @@
   - [Detecting route manipulation by Guard nodes (Path Bias)](./path-spec/detecting-route-manipulation.md)
   - [Old notes](./path-spec/old-notes.md)
 - [`Tor Guard Specification`](./guard-spec-intro.md)
-  - [Introduction and motivation](./guard-spec/introduction-motivation.md)
   - [State instances](./guard-spec/state-instances.md)
   - [Circuit Creation, Entry Guard Selection (1000 foot view)](./guard-spec/guard-selection-intro.md)
   - [The algorithm.](./guard-spec/algorithm.md)
@@ -139,7 +137,6 @@
 # For C Tor only
 
 - [`The Tor Control Protocol`](./control-spec-intro.md)
-  - [Scope](./control-spec/scope.md)
   - [Protocol outline](./control-spec/protocol-outline.md)
   - [Message format](./control-spec/message-format.md)
   - [Commands](./control-spec/commands.md)
diff --git a/spec/bandwidth-file-spec-intro.md b/spec/bandwidth-file-spec-intro.md
index 93d812e..86563fa 100644
--- a/spec/bandwidth-file-spec-intro.md
+++ b/spec/bandwidth-file-spec-intro.md
@@ -1,32 +1,18 @@
+# Tor Bandwidth File Format
+
 ```text
-                  Tor Bandwidth File Format
                             juga
                             teor
+```
 
-Table of Contents
+This document describes the format of Tor's Bandwidth File, version
+1.0.0 and later.
 
-    1. Scope and preliminaries
-        1.2. Acknowledgements
-        1.3. Outline
-        1.4. Format Versions
-    2. Format details
-        2.1. Definitions
-        2.2. Header List format
-        2.3. Relay Line format
-        2.4. Implementation details
-            2.4.1. Writing bandwidth files atomically
-            2.4.2. Additional KeyValue pair definitions
-                2.4.2.1. Simple Bandwidth Scanner
-                2.4.2.2. Torflow
-    A. Sample data
-        A.1. Generated by Torflow
-        A.2. Generated by sbws version 0.1.0
-        A.3. Generated by sbws version 1.0.3
-        A.4. Headers generated by sbws version 1.0.4
-        A.5 Generated by sbws version 1.1.0
-    B. Scaling bandwidths
-        B.1. Scaling requirements
-        B.2. A linear scaling method
-        B.3. Quota changes
-        B.4. Torflow aggregation
-```
+It is a new specification for the existing bandwidth file format,
+which we call version 1.0.0. It also specifies new format versions
+1.1.0 and later, which are backwards compatible with 1.0.0 parsers.
+
+Since Tor version 0.2.4.12-alpha, the directory authorities use
+the Bandwidth File file called "V3BandwidthsFile" generated by
+Torflow \[1\]. The details of this format are described in Torflow's
+README.spec.txt. We also summarise the format in this specification.
diff --git a/spec/bandwidth-file-spec/scope-preliminaries.md b/spec/bandwidth-file-spec/scope-preliminaries.md
index dd17d56..0215514 100644
--- a/spec/bandwidth-file-spec/scope-preliminaries.md
+++ b/spec/bandwidth-file-spec/scope-preliminaries.md
@@ -2,18 +2,6 @@
 
 # Scope and preliminaries
 
-This document describes the format of Tor's Bandwidth File, version
-1.0.0 and later.
-
-It is a new specification for the existing bandwidth file format,
-which we call version 1.0.0. It also specifies new format versions
-1.1.0 and later, which are backwards compatible with 1.0.0 parsers.
-
-Since Tor version 0.2.4.12-alpha, the directory authorities use
-the Bandwidth File file called "V3BandwidthsFile" generated by
-Torflow \[1\]. The details of this format are described in Torflow's
-README.spec.txt. We also summarise the format in this specification.
-
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
diff --git a/spec/control-spec-intro.md b/spec/control-spec-intro.md
index 08ea28e..8ce17b3 100644
--- a/spec/control-spec-intro.md
+++ b/spec/control-spec-intro.md
@@ -1,92 +1,24 @@
-TC: A Tor control protocol (Version 1)
+# TC: A Tor control protocol (Version 1)
 
-Table of Contents
+<a id="control-spec.txt-0"></a>
+
+## Scope
+
+This document describes an implementation-specific protocol that is used
+for other programs (such as frontend user-interfaces) to communicate with a
+locally running Tor process.  It is not part of the Tor onion routing
+protocol.
+
+This protocol replaces version 0 of TC, which is now deprecated.  For
+reference, TC is described in "control-spec-v0.txt".  Implementors are
+recommended to avoid using TC directly, but instead to use a library that
+can easily be updated to use the newer protocol.  (Version 0 is used by Tor
+versions 0.1.0.x; the protocol in this document only works with Tor
+versions in the 0.1.1.x series and later.)
 
 ```text
-    0. Scope
-    1. Protocol outline
-        1.1. Forward-compatibility
-    2. Message format
-        2.1. Description format
-            2.1.1. Notes on an escaping bug
-        2.2. Commands from controller to Tor
-        2.3. Replies from Tor to the controller
-        2.4. General-use tokens
-    3. Commands
-        3.1. SETCONF
-        3.2. RESETCONF
-        3.3. GETCONF
-        3.4. SETEVENTS
-        3.5. AUTHENTICATE
-        3.6. SAVECONF
-        3.7. SIGNAL
-        3.8. MAPADDRESS
-        3.9. GETINFO
-        3.10. EXTENDCIRCUIT
-        3.11. SETCIRCUITPURPOSE
-        3.12. SETROUTERPURPOSE
-        3.13. ATTACHSTREAM
-        3.14. POSTDESCRIPTOR
-        3.15. REDIRECTSTREAM
-        3.16. CLOSESTREAM
-        3.17. CLOSECIRCUIT
-        3.18. QUIT
-        3.19. USEFEATURE
-        3.20. RESOLVE
-        3.21. PROTOCOLINFO
-        3.22. LOADCONF
-        3.23. TAKEOWNERSHIP
-        3.24. AUTHCHALLENGE
-        3.25. DROPGUARDS
-        3.26. HSFETCH
-        3.27. ADD_ONION
-        3.28. DEL_ONION
-        3.29. HSPOST
-        3.30. ONION_CLIENT_AUTH_ADD
-        3.31. ONION_CLIENT_AUTH_REMOVE
-        3.32. ONION_CLIENT_AUTH_VIEW
-        3.33. DROPOWNERSHIP
-        3.34. DROPTIMEOUTS
-    4. Replies
-        4.1. Asynchronous events
-            4.1.1. Circuit status changed
-            4.1.2. Stream status changed
-            4.1.3. OR Connection status changed
-            4.1.4. Bandwidth used in the last second
-            4.1.5. Log messages
-            4.1.6. New descriptors available
-            4.1.7. New Address mapping
-            4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
-            4.1.9. Our descriptor changed
-            4.1.10. Status events
-            4.1.11. Our set of guard nodes has changed
-            4.1.12. Network status has changed
-            4.1.13. Bandwidth used on an application stream
-            4.1.14. Per-country client stats
-            4.1.15. New consensus networkstatus has arrived
-            4.1.16. New circuit buildtime has been set
-            4.1.17. Signal received
-            4.1.18. Configuration changed
-            4.1.19. Circuit status changed slightly
-            4.1.20. Pluggable transport launched
-            4.1.21. Bandwidth used on an OR or DIR or EXIT connection
-            4.1.22. Bandwidth used by all streams attached to a circuit
-            4.1.23. Per-circuit cell stats
-            4.1.24. Token buckets refilled
-            4.1.25. HiddenService descriptors
-            4.1.26. HiddenService descriptors content
-            4.1.27. Network liveness has changed
-            4.1.28. Pluggable Transport Logs
-            4.1.29. Pluggable Transport Status
-    5. Implementation notes
-        5.1. Authentication
-        5.2. Don't let the buffer get too big
-        5.3. Backward compatibility with v0 control protocol
-        5.4. Tor config options for use by controllers
-        5.5. Phases from the Bootstrap status event
-            5.5.1. Overview of Bootstrap reporting.
-            5.5.2. Phases in Bootstrap Stage 1
-            5.5.3. Phases in Bootstrap Stage 2
-            5.5.4. Phases in Bootstrap Stage 3
-        5.6 Bootstrap phases reported by older versions of Tor
+      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+      "OPTIONAL" in this document are to be interpreted as described in
+      RFC 2119.
 ```
diff --git a/spec/control-spec/scope.md b/spec/control-spec/scope.md
deleted file mode 100644
index 9d5b3d3..0000000
--- a/spec/control-spec/scope.md
+++ /dev/null
@@ -1,22 +0,0 @@
-<a id="control-spec.txt-0"></a>
-
-# Scope
-
-This document describes an implementation-specific protocol that is used
-for other programs (such as frontend user-interfaces) to communicate with a
-locally running Tor process.  It is not part of the Tor onion routing
-protocol.
-
-This protocol replaces version 0 of TC, which is now deprecated.  For
-reference, TC is described in "control-spec-v0.txt".  Implementors are
-recommended to avoid using TC directly, but instead to use a library that
-can easily be updated to use the newer protocol.  (Version 0 is used by Tor
-versions 0.1.0.x; the protocol in this document only works with Tor
-versions in the 0.1.1.x series and later.)
-
-```text
-      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
-      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
-      "OPTIONAL" in this document are to be interpreted as described in
-      RFC 2119.
-```
diff --git a/spec/dir-spec-intro.md b/spec/dir-spec-intro.md
index 71b1090..0f4cafd 100644
--- a/spec/dir-spec-intro.md
+++ b/spec/dir-spec-intro.md
@@ -1,69 +1,140 @@
-Tor directory protocol, version 3
+# Tor directory protocol, version 3
 
-Table of Contents
+<a id="dir-spec.txt-0"></a>
+
+This directory protocol is used by Tor version 0.2.0.x-alpha and later.
+See dir-spec-v1.txt for information on the protocol used up to the
+0.1.0.x series, and dir-spec-v2.txt for information on the protocol
+used by the 0.1.1.x and 0.1.2.x series.
+
+This document merges and supersedes the following proposals:
+
+- 101  Voting on the Tor Directory System
+- 103  Splitting identity key from regularly used signing key
+- 104  Long and Short Router Descriptors
+
+XXX timeline
+XXX fill in XXXXs
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in
+RFC 2119.
+
+<a id="dir-spec.txt-0.1"></a>
+
+## History
+
+The earliest versions of Onion Routing shipped with a list of known
+routers and their keys.  When the set of routers changed, users needed to
+fetch a new list.
+
+### The Version 1 Directory protocol
+
+Early versions of Tor (0.0.2) introduced "Directory authorities": servers
+that served signed "directory" documents containing a list of signed
+"server descriptors", along with short summary of the status of each
+router.  Thus, clients could get up-to-date information on the state of
+the network automatically, and be certain that the list they were getting
+was attested by a trusted directory authority.
+
+Later versions (0.0.8) added directory caches, which download
+directories from the authorities and serve them to clients.  Non-caches
+fetch from the caches in preference to fetching from the authorities, thus
+distributing bandwidth requirements.
+
+Also added during the version 1 directory protocol were "router status"
+documents: short documents that listed only the up/down status of the
+routers on the network, rather than a complete list of all the
+descriptors.  Clients and caches would fetch these documents far more
+frequently than they would fetch full directories.
+
+### The Version 2 Directory Protocol
+
+During the Tor 0.1.1.x series, Tor revised its handling of directory
+documents in order to address two major problems:
 
 ```text
-    0. Scope and preliminaries
-        0.1. History
-        0.2. Goals of the version 3 protoc
-        0.3. Some Remaining questions
-    1. Outline
-        1.1. What's different from version 2?
-        1.2. Document meta-format
-        1.3. Signing documents
-        1.4. Voting timeline
-    2. Router operation and formats
-        2.1. Uploading server descriptors and extra-info documents
-            2.1.1. Server descriptor format
-            2.1.2. Extra-info document format
-            2.1.3. Nonterminals in server descriptors
-    3. Directory authority operation and formats
-        3.1. Creating key certificates
-        3.2. Accepting server descriptor and extra-info document uploads
-        3.3. Computing microdescriptors
-        3.4. Exchanging votes
-            3.4.1. Vote and consensus status document formats
-            3.4.2. Assigning flags in a vote
-            3.4.3. Serving bandwidth list files
-        3.5. Downloading missing certificates from other directory authorities
-        3.6. Downloading server descriptors from other directory authorities
-        3.7. Downloading extra-info documents from other directory authorities
-        3.8. Computing a consensus from a set of votes
-            3.8.0.1. Deciding which Ids to include.
-            3.8.0.2. Deciding which descriptors to include
-            3.8.1. Forward compatibility
-            3.8.2. Encoding port lists
-            3.8.3. Computing Bandwidth Weights
-        3.9. Computing consensus flavors
-            3.9.1. ns consensus
-            3.9.2. Microdescriptor consensus
-        3.10. Exchanging detached signatures
-        3.11. Publishing the signed consensus
-    4. Directory cache operation
-        4.1. Downloading consensus status documents from directory authorities
-        4.2. Downloading server descriptors from directory authorities
-        4.3. Downloading microdescriptors from directory authorities
-        4.4. Downloading extra-info documents from directory authorities
-        4.5. Consensus diffs
-            4.5.1. Consensus diff format
-            4.5.2. Serving and requesting diff
-        4.6 Retrying failed downloads
-    5. Client operation
-        5.1. Downloading network-status documents
-        5.2. Downloading server descriptors or microdescriptors
-        5.3. Downloading extra-info documents
-        5.4. Using directory information
-        5.4.1. Choosing routers for circuits.
-        5.4.2. Managing naming
-        5.4.3. Software versions
-        5.4.4. Warning about a router's status.
-        5.5. Retrying failed downloads
-    6. Standards compliance
-        6.1. HTTP headers
-        6.2. HTTP status codes
-            A. Consensus-negotiation timeline.
-            B. General-use HTTP URLs
-            C. Converting a curve25519 public key to an ed25519 public key
-            D. Inferring missing proto lines.
-            E. Limited ed diff format
+      * Directories had grown quite large (over 1MB), and most directory
+        downloads consisted mainly of server descriptors that clients
+        already had.
+
+      * Every directory authority was a trust bottleneck: if a single
+        directory authority lied, it could make clients believe for a time
+        an arbitrarily distorted view of the Tor network.  (Clients
+        trusted the most recent signed document they downloaded.) Thus,
+        adding more authorities would make the system less secure, not
+        more.
 ```
+
+To address these, we extended the directory protocol so that
+authorities now published signed "network status" documents.  Each
+network status listed, for every router in the network: a hash of its
+identity key, a hash of its most recent descriptor, and a summary of
+what the authority believed about its status.  Clients would download
+the authorities' network status documents in turn, and believe
+statements about routers iff they were attested to by more than half of
+the authorities.
+
+Instead of downloading all server descriptors at once, clients
+downloaded only the descriptors that they did not have.  Descriptors
+were indexed by their digests, in order to prevent malicious caches
+from giving different versions of a server descriptor to different
+clients.
+
+Routers began working harder to upload new descriptors only when their
+contents were substantially changed.
+
+<a id="dir-spec.txt-0.2"></a>
+
+### Goals of the version 3 protocol
+
+Version 3 of the Tor directory protocol tries to solve the following
+issues:
+
+```text
+      * A great deal of bandwidth used to transmit server descriptors was
+        used by two fields that are not actually used by Tor routers
+        (namely read-history and write-history).  We save about 60% by
+        moving them into a separate document that most clients do not
+        fetch or use.
+
+      * It was possible under certain perverse circumstances for clients
+        to download an unusual set of network status documents, thus
+        partitioning themselves from clients who have a more recent and/or
+        typical set of documents.  Even under the best of circumstances,
+        clients were sensitive to the ages of the network status documents
+        they downloaded.  Therefore, instead of having the clients
+        correlate multiple network status documents, we have the
+        authorities collectively vote on a single consensus network status
+        document.
+
+      * The most sensitive data in the entire network (the identity keys
+        of the directory authorities) needed to be stored unencrypted so
+        that the authorities can sign network-status documents on the fly.
+        Now, the authorities' identity keys are stored offline, and used
+        to certify medium-term signing keys that can be rotated.
+```
+
+<a id="dir-spec.txt-0.3"></a>
+
+## Some Remaining questions
+
+Things we could solve on a v3 timeframe:
+
+The SHA-1 hash is showing its age.  We should do something about our
+dependency on it.  We could probably future-proof ourselves here in
+this revision, at least so far as documents from the authorities are
+concerned.
+
+Too many things about the authorities are hardcoded by IP.
+
+Perhaps we should start accepting longer identity keys for routers
+too.
+
+Things to solve eventually:
+
+Requiring every client to know about every router won't scale forever.
+
+Requiring every directory cache to know every router won't scale
+forever.
diff --git a/spec/dir-spec/scope-preliminaries.md b/spec/dir-spec/scope-preliminaries.md
deleted file mode 100644
index 1025c04..0000000
--- a/spec/dir-spec/scope-preliminaries.md
+++ /dev/null
@@ -1,140 +0,0 @@
-<a id="dir-spec.txt-0"></a>
-
-# Scope and preliminaries
-
-This directory protocol is used by Tor version 0.2.0.x-alpha and later.
-See dir-spec-v1.txt for information on the protocol used up to the
-0.1.0.x series, and dir-spec-v2.txt for information on the protocol
-used by the 0.1.1.x and 0.1.2.x series.
-
-This document merges and supersedes the following proposals:
-
-- 101  Voting on the Tor Directory System
-- 103  Splitting identity key from regularly used signing key
-- 104  Long and Short Router Descriptors
-
-XXX timeline
-XXX fill in XXXXs
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
-NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
-"OPTIONAL" in this document are to be interpreted as described in
-RFC 2119.
-
-<a id="dir-spec.txt-0.1"></a>
-
-## History
-
-The earliest versions of Onion Routing shipped with a list of known
-routers and their keys.  When the set of routers changed, users needed to
-fetch a new list.
-
-### The Version 1 Directory protocol
-
-Early versions of Tor (0.0.2) introduced "Directory authorities": servers
-that served signed "directory" documents containing a list of signed
-"server descriptors", along with short summary of the status of each
-router.  Thus, clients could get up-to-date information on the state of
-the network automatically, and be certain that the list they were getting
-was attested by a trusted directory authority.
-
-Later versions (0.0.8) added directory caches, which download
-directories from the authorities and serve them to clients.  Non-caches
-fetch from the caches in preference to fetching from the authorities, thus
-distributing bandwidth requirements.
-
-Also added during the version 1 directory protocol were "router status"
-documents: short documents that listed only the up/down status of the
-routers on the network, rather than a complete list of all the
-descriptors.  Clients and caches would fetch these documents far more
-frequently than they would fetch full directories.
-
-### The Version 2 Directory Protocol
-
-During the Tor 0.1.1.x series, Tor revised its handling of directory
-documents in order to address two major problems:
-
-```text
-      * Directories had grown quite large (over 1MB), and most directory
-        downloads consisted mainly of server descriptors that clients
-        already had.
-
-      * Every directory authority was a trust bottleneck: if a single
-        directory authority lied, it could make clients believe for a time
-        an arbitrarily distorted view of the Tor network.  (Clients
-        trusted the most recent signed document they downloaded.) Thus,
-        adding more authorities would make the system less secure, not
-        more.
-```
-
-To address these, we extended the directory protocol so that
-authorities now published signed "network status" documents.  Each
-network status listed, for every router in the network: a hash of its
-identity key, a hash of its most recent descriptor, and a summary of
-what the authority believed about its status.  Clients would download
-the authorities' network status documents in turn, and believe
-statements about routers iff they were attested to by more than half of
-the authorities.
-
-Instead of downloading all server descriptors at once, clients
-downloaded only the descriptors that they did not have.  Descriptors
-were indexed by their digests, in order to prevent malicious caches
-from giving different versions of a server descriptor to different
-clients.
-
-Routers began working harder to upload new descriptors only when their
-contents were substantially changed.
-
-<a id="dir-spec.txt-0.2"></a>
-
-### Goals of the version 3 protocol
-
-Version 3 of the Tor directory protocol tries to solve the following
-issues:
-
-```text
-      * A great deal of bandwidth used to transmit server descriptors was
-        used by two fields that are not actually used by Tor routers
-        (namely read-history and write-history).  We save about 60% by
-        moving them into a separate document that most clients do not
-        fetch or use.
-
-      * It was possible under certain perverse circumstances for clients
-        to download an unusual set of network status documents, thus
-        partitioning themselves from clients who have a more recent and/or
-        typical set of documents.  Even under the best of circumstances,
-        clients were sensitive to the ages of the network status documents
-        they downloaded.  Therefore, instead of having the clients
-        correlate multiple network status documents, we have the
-        authorities collectively vote on a single consensus network status
-        document.
-
-      * The most sensitive data in the entire network (the identity keys
-        of the directory authorities) needed to be stored unencrypted so
-        that the authorities can sign network-status documents on the fly.
-        Now, the authorities' identity keys are stored offline, and used
-        to certify medium-term signing keys that can be rotated.
-```
-
-<a id="dir-spec.txt-0.3"></a>
-
-## Some Remaining questions
-
-Things we could solve on a v3 timeframe:
-
-The SHA-1 hash is showing its age.  We should do something about our
-dependency on it.  We could probably future-proof ourselves here in
-this revision, at least so far as documents from the authorities are
-concerned.
-
-Too many things about the authorities are hardcoded by IP.
-
-Perhaps we should start accepting longer identity keys for routers
-too.
-
-Things to solve eventually:
-
-Requiring every client to know about every router won't scale forever.
-
-Requiring every directory cache to know every router won't scale
-forever.
diff --git a/spec/guard-spec-intro.md b/spec/guard-spec-intro.md
index e94a4f2..b7d1836 100644
--- a/spec/guard-spec-intro.md
+++ b/spec/guard-spec-intro.md
@@ -1,39 +1,48 @@
-Tor Guard Specification
+# Tor Guard Specification
+
+<a id="guard-spec.txt-1"></a>
+
+## Introduction and motivation
+
+Tor uses entry guards to prevent an attacker who controls some
+fraction of the network from observing a fraction of every user's
+traffic. If users chose their entries and exits uniformly at
+random from the list of servers every time they build a circuit,
+then an adversary who had (k/N) of the network would deanonymize
+F=(k/N)^2 of all circuits... and after a given user had built C
+circuits, the attacker would see them at least once with
+probability 1-(1-F)^C.  With large C, the attacker would get a
+sample of every user's traffic with probability 1.
+
+To prevent this from happening, Tor clients choose a small number
+of guard nodes (e.g. 3).  These guard nodes are the only
+nodes that the client will connect to directly.  If they are not
+compromised, the user's paths are not compromised.
+
+This specification outlines Tor's guard housekeeping algorithm,
+which tries to meet the following goals:
 
 ```text
-                           Isis Lovecruft
-                         George Kadianakis
-                              Ola Bini
-                           Nick Mathewson
-
-Table of Contents
-
-    1. Introduction and motivation
-    2. State instances
-    3. Circuit Creation, Entry Guard Selection (1000 foot view)
-        3.1 Path selection
-            3.1.1 Managing entry guards
-            3.1.2 Middle and exit node selection
-        3.2 Circuit Building
-    4. The algorithm.
-        4.0. The guards listed in the current consensus. [Section:GUARDS]
-        4.1. The Sampled Guard Set. [Section:SAMPLED]
-        4.2. The Usable Sample [Section:FILTERED]
-        4.3. The confirmed-guard list. [Section:CONFIRMED]
-        4.4. The Primary guards [Section:PRIMARY]
-        4.5. Retrying guards. [Section:RETRYING]
-        4.6. Selecting guards for circuits. [Section:SELECTING]
-        4.7. When a circuit fails. [Section:ON_FAIL]
-        4.8. When a circuit succeeds [Section:ON_SUCCESS]
-        4.9. Updating the list of waiting circuits [Section:UPDATE_WAITING]
-        4.10. Whenever we get a new consensus. [Section:ON_CONSENSUS]
-        4.11. Deciding whether to generate a new circuit.
-        4.12. When we are missing descriptors.
-    A. Appendices
-        A.0. Acknowledgements
-        A.1. Parameters with suggested values. [Section:PARAM_VALS]
-        A.2. Random values [Section:RANDOM]
-        A.3. Why not a sliding scale of primaryness? [Section:CVP]
-        A.4. Controller changes
-        A.5. Persistent state format
+    - Heuristics and algorithms for determining how and which guards
+      are chosen should be kept as simple and easy to understand as
+      possible.
+
+    - Clients in censored regions or who are behind a fascist
+      firewall who connect to the Tor network should not experience
+      any significant disadvantage in terms of reachability or
+      usability.
+
+    - Tor should make a best attempt at discovering the most
+      appropriate behavior, with as little user input and
+      configuration as possible.
+
+    - Tor clients should discover usable guards without too much
+      delay.
+
+    - Tor clients should resist (to the extent possible) attacks
+      that try to force them onto compromised guards.
+
+    - Should maintain the load-balancing offered by the path selection
+      algorithm
 ```
+
diff --git a/spec/guard-spec/introduction-motivation.md b/spec/guard-spec/introduction-motivation.md
deleted file mode 100644
index 628cf1a..0000000
--- a/spec/guard-spec/introduction-motivation.md
+++ /dev/null
@@ -1,45 +0,0 @@
-<a id="guard-spec.txt-1"></a>
-
-# Introduction and motivation
-
-Tor uses entry guards to prevent an attacker who controls some
-fraction of the network from observing a fraction of every user's
-traffic. If users chose their entries and exits uniformly at
-random from the list of servers every time they build a circuit,
-then an adversary who had (k/N) of the network would deanonymize
-F=(k/N)^2 of all circuits... and after a given user had built C
-circuits, the attacker would see them at least once with
-probability 1-(1-F)^C.  With large C, the attacker would get a
-sample of every user's traffic with probability 1.
-
-To prevent this from happening, Tor clients choose a small number
-of guard nodes (e.g. 3).  These guard nodes are the only
-nodes that the client will connect to directly.  If they are not
-compromised, the user's paths are not compromised.
-
-This specification outlines Tor's guard housekeeping algorithm,
-which tries to meet the following goals:
-
-```text
-    - Heuristics and algorithms for determining how and which guards
-      are chosen should be kept as simple and easy to understand as
-      possible.
-
-    - Clients in censored regions or who are behind a fascist
-      firewall who connect to the Tor network should not experience
-      any significant disadvantage in terms of reachability or
-      usability.
-
-    - Tor should make a best attempt at discovering the most
-      appropriate behavior, with as little user input and
-      configuration as possible.
-
-    - Tor clients should discover usable guards without too much
-      delay.
-
-    - Tor clients should resist (to the extent possible) attacks
-      that try to force them onto compromised guards.
-
-    - Should maintain the load-balancing offered by the path selection
-      algorithm
-```
diff --git a/spec/path-spec-intro.md b/spec/path-spec-intro.md
index db16f60..107d640 100644
--- a/spec/path-spec-intro.md
+++ b/spec/path-spec-intro.md
@@ -1,4 +1,4 @@
-Tor Path Specification
+# Tor Path Specification
 
 ```text
                               Roger Dingledine
@@ -15,51 +15,8 @@ of their choices.
 
 THIS SPEC ISN'T DONE YET.
 
-```text
-      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
-      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
-      "OPTIONAL" in this document are to be interpreted as described in
-      RFC 2119.
-
-Tables of Contents
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in
+RFC 2119.
 
-    1. General operation
-        1.1. Terminology
-        1.2. A relay's bandwidth
-    2. Building circuits
-        2.1. When we build
-            2.1.0. We don't build circuits until we have enough directory info
-            2.1.1. Clients build circuits preemptively
-            2.1.2. Clients build circuits on demand
-            2.1.3. Relays build circuits for testing reachability and bandwidth
-            2.1.4. Hidden-service circuits
-            2.1.5. Rate limiting of failed circuits
-            2.1.6. When to tear down circuits
-        2.2. Path selection and constraints
-            2.2.1. Choosing an exit
-            2.2.2. User configuration
-        2.3. Cannibalizing circuits
-        2.4. Learning when to give up ("timeout") on circuit construction
-            2.4.1 Distribution choice and parameter estimation
-            2.4.2. How much data to record
-            2.4.3. How to record timeouts
-            2.4.4. Detecting Changing Network Conditions
-            2.4.5. Consensus parameters governing behavior
-            2.4.6. Consensus parameters governing behavior
-        2.5. Handling failure
-    3. Attaching streams to circuits
-    4. Hidden-service related circuits
-    5. Guard nodes
-        5.1. How consensus bandwidth weights factor into entry guard selection
-    6. Server descriptor purposes
-    7. Detecting route manipulation by Guard nodes (Path Bias)
-        7.1. Measuring path construction success rates
-        7.2. Measuring path usage success rates
-        7.3. Scaling success counts
-        7.4. Parametrization
-        7.5. Known barriers to enforcement
-    X. Old notes
-    X.1. Do we actually do this?
-    X.2. A thing we could do to deal with reachability.
-    X.3. Some stuff that worries me about entry guards. 2006 Jun, Nickm.
-```