subprotocol-versioning.md: convert code blocks

1 files changed, 128 insertions, 141 deletions

diff --git a/spec/tor-spec/subprotocol-versioning.md b/spec/tor-spec/subprotocol-versioning.md
index ffd17a6..15a0605 100644
--- a/spec/tor-spec/subprotocol-versioning.md
+++ b/spec/tor-spec/subprotocol-versioning.md
@@ -14,28 +14,26 @@ The dir-spec.txt details how those versions are encoded. See the
 Here are the rules a relay and client should follow when encountering a
 protocol list in the consensus:
 
-```text
-      - When a relay lacks a protocol listed in recommended-relay-protocols,
-        it should warn its operator that the relay is obsolete.
-
-      - When a relay lacks a protocol listed in required-relay-protocols, it
-        should warn its operator as above. If the consensus is newer than the
-        date when the software was released or scheduled for release, it must
-        not attempt to join the network.
-
-      - When a client lacks a protocol listed in recommended-client-protocols,
-        it should warn the user that the client is obsolete.
-
-      - When a client lacks a protocol listed in required-client-protocols,
-        it should warn the user as above.  If the consensus is newer than the
-        date when the software was released, it must not connect to the
-        network.  This implements a "safe forward shutdown" mechanism for
-        zombie clients.
-
-      - If a client or relay has a cached consensus telling it that a given
-        protocol is required, and it does not implement that protocol, it
-        SHOULD NOT try to fetch a newer consensus.
-```
+ - When a relay lacks a protocol listed in recommended-relay-protocols,
+   it should warn its operator that the relay is obsolete.
+
+ - When a relay lacks a protocol listed in required-relay-protocols, it
+   should warn its operator as above. If the consensus is newer than the
+   date when the software was released or scheduled for release, it must
+   not attempt to join the network.
+
+ - When a client lacks a protocol listed in recommended-client-protocols,
+   it should warn the user that the client is obsolete.
+
+ - When a client lacks a protocol listed in required-client-protocols,
+   it should warn the user as above.  If the consensus is newer than the
+   date when the software was released, it must not connect to the
+   network.  This implements a "safe forward shutdown" mechanism for
+   zombie clients.
+
+ - If a client or relay has a cached consensus telling it that a given
+   protocol is required, and it does not implement that protocol, it
+   SHOULD NOT try to fetch a newer consensus.
 
 Software release dates SHOULD be automatically updated as part of the
 release process, to prevent forgetting to move them forward.  Software
@@ -45,13 +43,15 @@ Starting in version 0.2.9.4-alpha, the initial required protocols for
 clients that we will Recommend and Require are:
 
 ```text
-      Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 Link=4
-      LinkAuth=1 Microdesc=1-2 Relay=2
+Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 Link=4
+LinkAuth=1 Microdesc=1-2 Relay=2
+```
 
-   For relays we will Require:
+For relays we will Require:
 
-      Cons=1 Desc=1 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 Link=3-4
-      LinkAuth=1 Microdesc=1 Relay=1-2
+```text
+Cons=1 Desc=1 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 Link=3-4
+LinkAuth=1 Microdesc=1 Relay=1-2
 ```
 
 For relays, we will additionally Recommend all protocols which we
@@ -83,11 +83,11 @@ the v3+ link protocols.
 
 Current versions are:
 
-"1" is the RSA link authentication described in [Link authentication type 1: RSA-SHA256-TLSSecret](./negotiating-channels.md#RSA-SHA256-TLSSecret).
+ * "1" is the RSA link authentication described in [Link authentication type 1: RSA-SHA256-TLSSecret](./negotiating-channels.md#RSA-SHA256-TLSSecret).
 
-"2" is unused, and reserved by proposal 244.
+ * "2" is unused, and reserved by proposal 244.
 
-"3" is the ed25519 link authentication described in [Link authentication type 3: Ed25519-SHA256-RFC5705](./negotiating-channels.md#Ed25519-SHA256-RFC5705).
+ * "3" is the ed25519 link authentication described in [Link authentication type 3: Ed25519-SHA256-RFC5705](./negotiating-channels.md#Ed25519-SHA256-RFC5705).
 
 <a id="tor-spec.txt-9.3"></a>
 
@@ -99,72 +99,71 @@ after a CREATE/CREATE2 cell.  (Except, relay cells used to manage
 introduction and rendezvous points are managed with the "HSIntro"
 and "HSRend" protocols respectively.)
 
-Current versions are:
+Current versions are as follows.
 
-```text
-   "1" -- supports the TAP key exchange, with all features in Tor 0.2.3.
-          Support for CREATE and CREATED and CREATE_FAST and CREATED_FAST
-          and EXTEND and EXTENDED.
-
-   "2" -- supports the ntor key exchange, and all features in Tor
-          0.2.4.19.  Includes support for CREATE2 and CREATED2 and
-          EXTEND2 and EXTENDED2.
-
-          Relay=2 has limited IPv6 support:
-            * Clients might not include IPv6 ORPorts in EXTEND2 cells.
-            * Relays (and bridges) might not initiate IPv6 connections in
-              response to EXTEND2 cells containing IPv6 ORPorts, even if they
-              are configured with an IPv6 ORPort.
-
-          However, relays support accepting inbound connections to their IPv6
-          ORPorts. And they might extend circuits via authenticated IPv6
-          connections to other relays.
-
-   "3" -- relays support extending over IPv6 connections in response to an
-          EXTEND2 cell containing an IPv6 ORPort.
-
-          Bridges might not extend over IPv6, because they try to imitate
-          client behaviour.
-
-          A successful IPv6 extend requires:
-            * Relay subprotocol version 3 (or later) on the extending relay,
-            * an IPv6 ORPort on the extending relay,
-            * an IPv6 ORPort for the accepting relay in the EXTEND2 cell, and
-            * an IPv6 ORPort on the accepting relay.
-          (Because different tor instances can have different views of the
-          network, these checks should be done when the path is selected.
-          Extending relays should only check local IPv6 information, before
-          attempting the extend.)
-
-          When relays receive an EXTEND2 cell containing both an IPv4 and an
-          IPv6 ORPort, and there is no existing authenticated connection with
-          the target relay, the extending relay may choose between IPv4 and
-          IPv6 at random. The extending relay might not try the other address,
-          if the first connection fails.
-
-          As is the case with other subprotocol versions, tor advertises,
-          recommends, or requires support for this protocol version, regardless
-          of its current configuration.
-
-          In particular:
-            * relays without an IPv6 ORPort, and
-            * tor instances that are not relays,
-          have the following behaviour, regardless of their configuration:
-            * advertise support for "Relay=3" in their descriptor
-              (if they are a relay, bridge, or directory authority), and
-            * react to consensuses recommending or requiring support for
-              "Relay=3".
-
-          This subprotocol version is described in proposal 311, and
-          implemented in Tor 0.4.5.1-alpha.
-
-   "4" -- support the ntorv3 (version 3) key exchange and all features in
-          0.4.7.3-alpha. This adds a new CREATE2 cell type. See proposal 332
-          and section 5.1.4.1 above for more details.
-
-   "5" -- [RESERVED] support the ntorv3 subprotocol request extension (prop346)
-          allowing a client to request what features to be used on a circuit.
-```
+ * "1" -- supports the TAP key exchange, with all features in Tor 0.2.3.
+   Support for CREATE and CREATED and CREATE_FAST and CREATED_FAST
+   and EXTEND and EXTENDED.
+
+ * "2" -- supports the ntor key exchange, and all features in Tor
+   0.2.4.19.  Includes support for CREATE2 and CREATED2 and
+   EXTEND2 and EXTENDED2.
+
+   Relay=2 has limited IPv6 support:
+
+    * Clients might not include IPv6 ORPorts in EXTEND2 cells.
+    * Relays (and bridges) might not initiate IPv6 connections in
+      response to EXTEND2 cells containing IPv6 ORPorts, even if they
+      are configured with an IPv6 ORPort.
+
+   However, relays support accepting inbound connections to their IPv6
+   ORPorts. And they might extend circuits via authenticated IPv6
+   connections to other relays.
+
+ * "3" -- relays support extending over IPv6 connections in response to an
+   EXTEND2 cell containing an IPv6 ORPort.
+
+   Bridges might not extend over IPv6, because they try to imitate
+   client behaviour.
+
+   A successful IPv6 extend requires:
+     * Relay subprotocol version 3 (or later) on the extending relay,
+     * an IPv6 ORPort on the extending relay,
+     * an IPv6 ORPort for the accepting relay in the EXTEND2 cell, and
+     * an IPv6 ORPort on the accepting relay.
+   (Because different tor instances can have different views of the
+   network, these checks should be done when the path is selected.
+   Extending relays should only check local IPv6 information, before
+   attempting the extend.)
+
+   When relays receive an EXTEND2 cell containing both an IPv4 and an
+   IPv6 ORPort, and there is no existing authenticated connection with
+   the target relay, the extending relay may choose between IPv4 and
+   IPv6 at random. The extending relay might not try the other address,
+   if the first connection fails.
+
+   As is the case with other subprotocol versions, tor advertises,
+   recommends, or requires support for this protocol version, regardless
+   of its current configuration.
+
+   In particular:
+     * relays without an IPv6 ORPort, and
+     * tor instances that are not relays,
+   have the following behaviour, regardless of their configuration:
+     * advertise support for "Relay=3" in their descriptor
+       (if they are a relay, bridge, or directory authority), and
+     * react to consensuses recommending or requiring support for
+       "Relay=3".
+
+   This subprotocol version is described in proposal 311, and
+   implemented in Tor 0.4.5.1-alpha.
+
+ * "4" -- support the ntorv3 (version 3) key exchange and all features in
+   0.4.7.3-alpha. This adds a new CREATE2 cell type. See proposal 332
+   and section 5.1.4.1 above for more details.
+
+ * "5" -- [RESERVED] support the ntorv3 subprotocol request extension (prop346)
+   allowing a client to request what features to be used on a circuit.
 
 <a id="tor-spec.txt-9.4"></a>
 
@@ -172,16 +171,14 @@ Current versions are:
 
 The "HSIntro" protocol handles introduction points.
 
-```text
-   "3" -- supports authentication as of proposal 121 in Tor
-          0.2.1.6-alpha.
+ * "3" -- supports authentication as of proposal 121 in Tor
+   0.2.1.6-alpha.
 
-   "4" -- support ed25519 authentication keys which is defined by the HS v3
-          protocol as part of proposal 224 in Tor 0.3.0.4-alpha.
+ * "4" -- support ed25519 authentication keys which is defined by the HS v3
+   protocol as part of proposal 224 in Tor 0.3.0.4-alpha.
 
-   "5" -- support ESTABLISH_INTRO cell DoS parameters extension for onion
-          service version 3 only in Tor 0.4.2.1-alpha.
-```
+ * "5" -- support ESTABLISH_INTRO cell DoS parameters extension for onion
+   service version 3 only in Tor 0.4.2.1-alpha.
 
 <a id="tor-spec.txt-9.5"></a>
 
@@ -189,12 +186,10 @@ The "HSIntro" protocol handles introduction points.
 
 The "HSRend" protocol handles rendezvous points.
 
-"1" -- supports all features in Tor 0.0.6.
+ * "1" -- supports all features in Tor 0.0.6.
 
-```text
-   "2" -- supports RENDEZVOUS2 cells of arbitrary length as long as they
-          have 20 bytes of cookie in Tor 0.2.9.1-alpha.
-```
+ * "2" -- supports RENDEZVOUS2 cells of arbitrary length as long as they
+   have 20 bytes of cookie in Tor 0.2.9.1-alpha.
 
 <a id="tor-spec.txt-9.6"></a>
 
@@ -204,12 +199,10 @@ The "HSDir" protocols are the set of hidden service document types that can
 be uploaded to, understood by, and downloaded from a tor relay, and the set
 of URLs available to fetch them.
 
-"1" -- supports all features in Tor 0.2.0.10-alpha.
+ * "1" -- supports all features in Tor 0.2.0.10-alpha.
 
-```text
-   "2" -- support ed25519 blinded keys request which is defined by the HS v3
-          protocol as part of proposal 224 in Tor 0.3.0.4-alpha.
-```
+ * "2" -- support ed25519 blinded keys request which is defined by the HS v3
+   protocol as part of proposal 224 in Tor 0.3.0.4-alpha.
 
 <a id="tor-spec.txt-9.7"></a>
 
@@ -219,9 +212,9 @@ The "DirCache" protocols are the set of documents available for download
 from a directory cache via BEGIN_DIR, and the set of URLs available to
 fetch them.  (This excludes URLs for hidden service objects.)
 
-"1" -- supports all features in Tor 0.2.4.19.
+ * "1" -- supports all features in Tor 0.2.4.19.
 
-"2" -- adds support for consensus diffs in Tor 0.3.1.1-alpha.
+ * "2" -- adds support for consensus diffs in Tor 0.3.1.1-alpha.
 
 <a id="tor-spec.txt-9.8"></a>
 
@@ -233,9 +226,9 @@ Most features in descriptors don't require a "Desc" update -- only those
 that need to someday be required.  For example, someday clients will need
 to understand ed25519 identities.
 
-"1" -- supports all features in Tor 0.2.4.19.
+ * "1" -- supports all features in Tor 0.2.4.19.
 
-"2" -- cross-signing with onion-keys, signing with ed25519
+ * "2" -- cross-signing with onion-keys, signing with ed25519
 identities.
 
 <a id="tor-spec.txt-9.9"></a>
@@ -248,9 +241,9 @@ Most features in descriptors don't require a "MicroDesc" update -- only
 those that need to someday be required.  These correspond more or less with
 consensus methods.
 
-"1" -- consensus methods 9 through 20.
+ * "1" -- consensus methods 9 through 20.
 
-"2" -- consensus method 21 (adds ed25519 keys to microdescs).
+ * "2" -- consensus method 21 (adds ed25519 keys to microdescs).
 
 <a id="tor-spec.txt-9.10"></a>
 
@@ -263,9 +256,9 @@ those that need to someday be required.
 
 These correspond more or less with consensus methods.
 
-"1" -- consensus methods 9 through 20.
+ * "1" -- consensus methods 9 through 20.
 
-"2" -- consensus method 21 (adds ed25519 keys to microdescs).
+ * "2" -- consensus method 21 (adds ed25519 keys to microdescs).
 
 <a id="tor-spec.txt-9.11"></a>
 
@@ -273,15 +266,13 @@ These correspond more or less with consensus methods.
 
 Describes the padding capabilities of the relay.
 
-```text
-   "1" -- [DEFUNCT] Relay supports circuit-level padding. This version MUST NOT
-          be used as it was also enabled in relays that don't actually support
-          circuit-level padding. Advertised by Tor versions from
-          tor-0.4.0.1-alpha and only up to and including tor-0.4.1.4-rc.
+ * "1" -- [DEFUNCT] Relay supports circuit-level padding. This version MUST NOT
+   be used as it was also enabled in relays that don't actually support
+   circuit-level padding. Advertised by Tor versions from
+   tor-0.4.0.1-alpha and only up to and including tor-0.4.1.4-rc.
 
-   "2" -- Relay supports the HS circuit setup padding machines (proposal 302).
-          Advertised by Tor versions from tor-0.4.1.5 and onwards.
-```
+ * "2" -- Relay supports the HS circuit setup padding machines (proposal 302).
+   Advertised by Tor versions from tor-0.4.1.5 and onwards.
 
 <a id="tor-spec.txt-9.12"></a>
 
@@ -291,14 +282,12 @@ Describes the flow control protocol at the circuit and stream level. If
 there is no FlowCtrl advertised, tor supports the unauthenticated flow
 control features (version 0).
 
-```text
-   "1" -- supports authenticated circuit level SENDMEs as of proposal 289 in
-          Tor 0.4.1.1-alpha.
+ * "1" -- supports authenticated circuit level SENDMEs as of proposal 289 in
+   Tor 0.4.1.1-alpha.
 
-   "2" -- supports congestion control by the Exits which implies a new SENDME
-          format and algorithm. See proposal 324 for more details. Advertised
-          in tor 0.4.7.3-alpha.
-```
+ * "2" -- supports congestion control by the Exits which implies a new SENDME
+   format and algorithm. See proposal 324 for more details. Advertised
+   in tor 0.4.7.3-alpha.
 
 ## "Conflux"
 
@@ -314,8 +303,6 @@ in order to split traffic across multiple paths.
 
 Describes the UDP protocol capabilities of a relay.
 
-```text
-   "1" -- [RESERVED] supports UDP by an Exit as in the relay command
-          CONNECT_UDP, CONNECTED_UDP and DATAGRAM. See proposal
-          339 for more details. (Not yet advertised, reserved)
-```
+ * "1" -- [RESERVED] supports UDP by an Exit as in the relay command
+   CONNECT_UDP, CONNECTED_UDP and DATAGRAM. See proposal
+   339 for more details. (Not yet advertised, reserved)