path-spec: replace most section-number-based links.

6 files changed, 51 insertions, 27 deletions

diff --git a/spec/path-spec/detecting-route-manipulation.md b/spec/path-spec/detecting-route-manipulation.md
index 48cf4f7..76be4d1 100644
--- a/spec/path-spec/detecting-route-manipulation.md
+++ b/spec/path-spec/detecting-route-manipulation.md
@@ -29,9 +29,10 @@ and one during circuit usage.
 
 The intended behavior is for clients to ultimately disable the use
 of Guards responsible for excessive circuit failure of either type
-(see section 7.4); however known issues with the Tor network currently
-restrict the defense to being informational only at this stage (see
-section 7.5).
+(for the parameters to do this, see ["Parameterization"](#parameters) below);
+however known issues with the Tor network currently
+restrict the defense to being informational only at this stage
+(see ["Known barriers to enforcement"](#barriers)).
 
 <a id="path-spec.txt-7.1"></a>
 
@@ -43,9 +44,10 @@ guard, and a count of the number of circuits that successfully complete
 through that guard. The ratio of these two numbers is used to determine
 a circuit success rate for that Guard.
 
-Circuit build timeouts are counted as construction failures if the
+[Circuit build timeouts](./learning-timeouts.md)
+are counted as construction failures if the
 circuit fails to complete before the 95% "right-censored" timeout
-interval, not the 80% timeout condition (see section 2.4).
+interval, not the 80% timeout condition.
 
 If a circuit closes prematurely after construction but before being
 requested to close by the client, this is counted as a failure.
@@ -151,7 +153,8 @@ defense.
        Default: 300
        Min: 10
        Effect: After this many circuits have completed at least two hops,
-               Tor performs the scaling described in Section 7.3.
+               Tor performs the scaling described in
+	       ["Scaling success counts"](#scaling).
 
      pb_multfactor and pb_scalefactor
        Default: 1/2
@@ -184,7 +187,8 @@ defense.
        Default: 100
        Min: 10
        Effect: After we have attempted to use this many circuits,
-               Tor performs the scaling described in Section 7.3.
+               Tor performs the scaling described in
+      	       ["Scaling success counts"](#scaling).
 ```
 
 <a id="path-spec.txt-7.5"></a>
diff --git a/spec/path-spec/general-operation.md b/spec/path-spec/general-operation.md
index c491f98..721ab3d 100644
--- a/spec/path-spec/general-operation.md
+++ b/spec/path-spec/general-operation.md
@@ -2,8 +2,9 @@
 
 # General operation
 
-Tor begins building circuits as soon as it has enough directory
-information to do so (see section 5 of dir-spec.txt).  Some circuits are
+Tor begins building circuits as soon as it has
+[enough directory information](./when-we-build.md) to do so.
+Some circuits are
 built preemptively because we expect to need them later (for user
 traffic), and some are built because of immediate need (for user traffic
 that no current circuit can handle, for testing the network or our
diff --git a/spec/path-spec/handling-failure.md b/spec/path-spec/handling-failure.md
index 27bad6a..8db9245 100644
--- a/spec/path-spec/handling-failure.md
+++ b/spec/path-spec/handling-failure.md
@@ -14,4 +14,6 @@ so we treat the exit node as if it were a non-exit until we retrieve
 a fresh descriptor for it.
 
 Excessive amounts of either type of failure can indicate an
-attack on anonymity. See section 7 for how excessive failure is handled.
+attack on anonymity.
+See [discussion of path bias detection](./detecting-route-manipulation.md)
+for how excessive failure is handled.
diff --git a/spec/path-spec/learning-timeouts.md b/spec/path-spec/learning-timeouts.md
index 3685274..89b09a4 100644
--- a/spec/path-spec/learning-timeouts.md
+++ b/spec/path-spec/learning-timeouts.md
@@ -35,7 +35,8 @@ The Tor client should build test circuits at a rate of one every 'cbttestfreq'
 (10 seconds) until 'cbtmincircs' (100 circuits) are built, with a maximum of
 'cbtmaxopencircs' (default: 10) circuits open at once. This allows a fresh
 Tor to have a CircuitBuildTimeout estimated within 30 minutes after install
-or network change (see section 2.4.5 below).
+or network change
+(see [Detecting Changing Network Conditions](#changes-in-network) below.)
 
 Timeouts are stored on disk in a histogram of 10ms bin width, the same
 width used to calculate the Xm value above. The timeouts recorded in the
@@ -52,7 +53,9 @@ that build time binning is still needed for parameter estimation.
 
 Once 'cbtmincircs' build times are recorded, Tor clients update the
 distribution parameters and recompute the timeout every circuit completion
-(though see section 2.4.5 for when to pause and reset timeout due to
+(though
+[see below](#change-in-network)
+for when to pause and reset timeout due to
 too many circuits timing out).
 
 Tor clients calculate the parameters for a Pareto distribution fitting the
@@ -77,7 +80,7 @@ To avoid ln(1.0+epsilon) precision issues, use log laws to rewrite the
 estimator for 'alpha' as the sum of logs followed by subtraction, rather
 than multiplication and division:
 
-alpha = n/(Sum_n{ln(MAX(Xm, x_i))} - n\*ln(Xm))
+`alpha = n/(Sum_n{ln(MAX(Xm, x_i))} - n\*ln(Xm))`
 
 In this, n is the total number of build times that have completed, x_i is
 the ith recorded build time, and Xm is the modes of x_i as above.
@@ -96,19 +99,19 @@ of the distribution is below the timeout value (parameter 'cbtquantile').
 
 The Pareto Quantile Function (inverse CDF) is:
 
-F(q) = Xm/((1.0-q)^(1.0/alpha))
+`F(q) = Xm/((1.0-q)^(1.0/alpha))`
 
 Thus, clients obtain the circuit build timeout for 3-hop circuits by
 computing:
 
-timeout_ms = F(0.8)    # 'cbtquantile' == 0.8
+`timeout_ms = F(0.8)    # 'cbtquantile' == 0.8`
 
 With this, we expect that the Tor client will accept the fastest 80% of the
 total number of paths on the network.
 
 Clients obtain the circuit close time to completely abandon circuits as:
 
-close_ms = F(0.99)     # 'cbtclosequantile' == 0.99
+`close_ms = F(0.99)     # 'cbtclosequantile' == 0.99`
 
 To avoid waiting an unreasonably long period of time for circuits that
 simply have relays that are down, Tor clients cap timeout_ms at the max
@@ -133,11 +136,13 @@ other lengths, the client multiples the timeout_ms and close_ms values
 by a scaling factor determined by the number of communication hops
 needed to build their circuits:
 
+```text
 timeout_ms\[hops=n\] = timeout_ms * Actions(N) / Actions(3)
 
 close_ms\[hops=n\] = close_ms * Actions(N) / Actions(3)
+```
 
-where Actions(N) = N * (N + 1) / 2.
+where `Actions(N) = N * (N + 1) / 2.`
 
 To calculate timeouts for operations other than circuit building,
 the client should add X to Actions(N) for every round-trip communication
diff --git a/spec/path-spec/path-selection-constraints.md b/spec/path-spec/path-selection-constraints.md
index d31e45f..89a970a 100644
--- a/spec/path-spec/path-selection-constraints.md
+++ b/spec/path-spec/path-selection-constraints.md
@@ -33,7 +33,10 @@ the fraction of total bandwidth that they make up and depending upon the
 position they are being selected for.
 
 These weights are published in the consensus, and are computed as described
-in Section "Computing Bandwidth Weights" of dir-spec.txt. They are:
+in
+["Computing Bandwidth Weights"](../dir-spec/computing-consensus#computing-bandwidth-weights)
+in the directory specification.
+They are:
 
 ```text
       Wgg - Weight for Guard-flagged nodes in the guard position
diff --git a/spec/path-spec/when-we-build.md b/spec/path-spec/when-we-build.md
index cbcf7da..7130978 100644
--- a/spec/path-spec/when-we-build.md
+++ b/spec/path-spec/when-we-build.md
@@ -9,8 +9,14 @@
 There's a class of possible attacks where our directory servers
 only give us information about the relays that they would like us
 to use.  To prevent this attack, we don't build multi-hop
-circuits for real traffic (like those in 2.1.1, 2.1.2, 2.1.4
-below) until we have enough directory information to be
+circuits
+(including
+[preemptive circuits](#preemptive),
+[on-demand circuits(#on-demand),
+[onion-service circuits](#onion-service)]
+or [self-testing testing circuits](#self-test))
+for real traffic
+until we have enough directory information to be
 reasonably confident this attack isn't being done to us.
 
 Here, "enough" directory information is defined as:
@@ -59,7 +65,7 @@ fraction of middle relays.
 
 <a id="path-spec.txt-2.1.1"></a>
 
-## Clients build circuits preemptively
+## Clients build circuits preemptively {#preemptive}
 
 When running as a client, Tor tries to maintain at least a certain
 number of clean circuits, so that new streams can be handled
@@ -94,7 +100,7 @@ persistent medium.
 
 <a id="path-spec.txt-2.1.2"></a>
 
-## Clients build circuits on demand
+## Clients build circuits on demand {#on-demand}
 
 Additionally, when a client request exists that no circuit (built or
 pending) might support, we create a new circuit to support the request.
@@ -110,11 +116,13 @@ If a circuit has been "dirty" for at least MaxCircuitDirtiness seconds,
 new circuits may not be attached to it.
 
 In some cases we can reuse an already established circuit if it's
-clean; see Section 2.3 (cannibalizing circuits) for details.
+clean; see ["cannibalizing circuits"](./cannibalizing-circuits.md)
+
+for details.
 
 <a id="path-spec.txt-2.1.3"></a>
 
-## Relays build circuits for testing reachability and bandwidth
+## Relays build circuits for testing reachability and bandwidth {#self-test}
 
 Tor relays test reachability of their ORPort once they have
 successfully built a circuit (on startup and whenever their IP address
@@ -137,7 +145,7 @@ this purpose.
 
 <a id="path-spec.txt-2.1.4"></a>
 
-## Hidden-service circuits
+## Hidden-service circuits {#onion-service}
 
 See section 4 below.
 
@@ -145,8 +153,9 @@ See section 4 below.
 
 ## Rate limiting of failed circuits
 
-If we fail to build a circuit N times in a X second period (see Section
-2.3 for how this works), we stop building circuits until the X seconds
+If we fail to build a circuit N times in a X second period
+(see ["Handling failure"](./handling-failure.md)
+for how this works), we stop building circuits until the X seconds
 have elapsed.
 XXXX