Revise the description of the DOS_PARAMS extension

The changes:
 - The extension's name is now as given in C Tor and Arti.
   Previously it had no short name.
 - We use tables to describe the parameter's format.
 - We forward-reference the extension from a list of extensions.
 - We note that a burst is not "per second" but do not rename anything.
 - We include anchors for linking to the parameters.
 - We generally make the description more terse.
 - We repair a run-on section.

1 files changed, 57 insertions, 47 deletions

diff --git a/spec/rend-spec/introduction-protocol.md b/spec/rend-spec/introduction-protocol.md
index bdedef7..75e9a0d 100644
--- a/spec/rend-spec/introduction-protocol.md
+++ b/spec/rend-spec/introduction-protocol.md
@@ -82,6 +82,14 @@ unrecognized EXT_FIELD_TYPE values must be ignored.
    they may be overridden in the descriptions of individual extensions.)
 ```
 
+The following extensions are currently defined:
+
+| `EXT_FIELD_TYPE` | Name           |
+| ---------------- | -------------- |
+| `[01]`           | [`DOS_PARAMS`] |
+
+[`DOS_PARAMS`]: #DOS_PARAMS
+
 The HANDSHAKE_AUTH field contains the MAC of all earlier fields in
 the cell using as its key the shared per-circuit material ("KH")
 generated during the circuit extension protocol; see tor-spec.txt
@@ -113,67 +121,70 @@ the ESTABLISH_INTRO cell and destroy the circuit in these cases:
 Otherwise, the node must associate the key with the circuit, for use
 later in INTRODUCE1 cells.
 
+
+
 <a id="rend-spec-v3.txt-3.1.1.1"></a>
 
-#### Denial-of-Service defense extension {#EST_INTRO_DOS_EXT}
+#### Denial-of-Service defense extension (DOS\_PARAMS) {#EST_INTRO_DOS_EXT}
 
-This extension can be used to send Denial-of-Service (DoS) parameters to
+<a id="DOS_PARAMS"></a>
+The `DOS_PARAMS` extension is used to send Denial-of-Service (DoS) parameters to
 the introduction point in order for it to apply them for the introduction
 circuit.
 
 This is for the [rate limiting DoS mitigation](../dos-spec/overview.md#hs-intro-rate) specifically.
 
-If used, it needs to be encoded within the N_EXTENSIONS field of the
-ESTABLISH_INTRO cell defined in the previous section. The content is
-defined as follows:
-
-EXT_FIELD_TYPE:
-
-\[01\] -- Denial-of-Service Parameters.
+If used, it needs to be encoded within the `EXT_*` extension fields
+of the
+`ESTABLISH_INTRO` message defined in the previous section.
 
-```text
-         If this flag is set, the extension should be used by the introduction
-         point to learn what values the denial of service subsystem should be
-         using.
+The `EXT_FIELD_TYPE` value for the `DOS_PARAMS` extension is `[01]`.
 
-      EXT_FIELD content format is:
+The content is defined as follows:
 
-        N_PARAMS       [1 byte]
-        N_PARAMS times:
-           PARAM_TYPE  [1 byte]
-           PARAM_VALUE [8 byte]
+| Field             | Size | Description          |
+| ----------------- | ---- | -------------------- |
+| `N_PARAMS`        | 1    | Number of parameters |
+| `N_PARAMS` times: |      |                      |
+| - PARAM_TYPE      | 1    | Identifier for a parameter |
+| - PARAM_VALUE     | 8    | Integer value        |
 
-        The PARAM_TYPE possible values are:
+Recognized values for `PARAM_TYPE` in this extension are:
 
-         [01] -- DOS_INTRODUCE2_RATE_PER_SEC
-                 The rate per second of INTRODUCE2 cell relayed to the
-                 service.
+| `PARAM_TYPE` | Name                             | Min | Max        |
+| -----------  | -------------------------------- | --- | ---------- |
+| `[01]`       | [`DOS_INTRODUCE2_RATE_PER_SEC`]  | 0   | 0x7fffffff |
+| `[02]`       | [`DOS_INTRODUCE2_BURST_PER_SEC`] | 0   | 0x7fffffff |
 
-         [02] -- DOS_INTRODUCE2_BURST_PER_SEC
-                 The burst per second of INTRODUCE2 cell relayed to the
-                 service.
+[`DOS_INTRODUCE2_RATE_PER_SEC`]: #DOS_INTRODUCE2_RATE_PER_SEC
+[`DOS_INTRODUCE2_BURST_PER_SEC`]: #DOS_INTRODUCE2_BURST_PER_SEC
 
-        The PARAM_VALUE size is 8 bytes in order to accommodate 64bit values.
-        It MUST match the specified limit for the following PARAM_TYPE:
+Together, these parameters configure a token bucket
+that determines how many INTRODUCE2 messages
+the introduction point may send to the service.
 
-         [01] -- Min: 0, Max: 2147483647
-         [02] -- Min: 0, Max: 2147483647
+<span id="DOS_INTRODUCE2_RATE_PER_SEC">
+The `DOS_INTRODUCE2_RATE_PER_SEC` parameter defines the maximum
+average rate of messages;
+</span>
+<span id="DOS_INTRODUCE2_BURST_PER_SEC">
+The `DOS_INTRODUCE2_BURST_PER_SEC` parameter defines the largest
+allowable burst of messages
+(that is, the size of the token bucket).
+</span>
 
-        A value of 0 means the defense is disabled. If the rate per second is
-        set to 0 (param 0x01) then the burst value should be ignored. And
-        vice-versa, if the burst value is 0 (param 0x02), then the rate value
-        should be ignored. In other words, setting one single parameter to 0
-        disables the defense.
+> Technically speaking, the `BURST` is not actually "per second":
+> only a _rate_ has an associated time.
 
-        The burst can NOT be smaller than the rate. If so, the parameters
-        should be ignored by the introduction point.
+If either of these parameters is set to 0,
+the defense is disabled,
+and the introduction point should ignore the other parameter.
 
-        Any valid value does have precedence over the network wide consensus
-        parameter.
-```
+If the burst is lower than the rate,
+the introduction point SHOULD ignore the extension.
 
-Using this extension extends the payload of the ESTABLISH_INTRO cell by 19
-bytes bringing it from 134 bytes to 155 bytes.
+> Using this extension extends the payload of the ESTABLISH_INTRO cell by 19
+> bytes bringing it from 134 bytes to 155 bytes.
 
 When this extension is not _sent_,
 introduction points use default settings
@@ -188,13 +199,12 @@ This extension can only be used with relays supporting the protocol version
 
 Introduced in tor-0.4.2.1-alpha.
 
-```text
-3.1.2. Registering an introduction point on a legacy Tor node
-       [LEGACY_EST_INTRO]
+<a id="rend-spec-v3.txt-3.1.2"></a>
 
-   [This section is obsolete and refers to a workaround for now-obsolete Tor
-    relay versions. It is included for historical reasons.]
-```
+## Registering an introduction point on a legacy Tor node {#LEGACY_EST_INTRO}
+
+> This section is obsolete and refers to a workaround for now-obsolete Tor
+> relay versions. It is included for historical reasons.
 
 Tor nodes should also support an older version of the ESTABLISH_INTRO
 cell, first documented in rend-spec.txt. New hidden service hosts