bandwidth: rewrite the intro

Part of 27079.

1 files changed, 10 insertions, 8 deletions

diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt
index 7e859b7..05d1f40 100644
--- a/bandwidth-file-spec.txt
+++ b/bandwidth-file-spec.txt
@@ -4,16 +4,17 @@
 
 1. Scope and preliminaries
 
-  This document describes the format of Tor's Bandwidth List,
-  version 1.0.0, 1.1.0 and later.
-  It is new specification for the existing format 1.0.0.
-  Describes a new format 1.1.0, which is backwards compatible with
-  1.0.0 parsers.
+  This document describes the format of Tor's Bandwidth List, version
+  1.0.0 and later.
 
-  Since Tor version 0.2.4.12-alpha the directory authorities use
+  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 List file called "V3BandwidthsFile" generated by
-  Torflow [1]. The format is described in Torflow's README.spec.txt and
-  is considered to be version 1.0.0.
+  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
@@ -36,6 +37,7 @@
   The Tor directory protocol (dir-spec.txt [3]) sections 3.4.1
   and 3.4.2, use the term bandwidth measurements, to refer to what
   here is called Bandwidth List.
+
   A Bandwidth List file contains information on relays' bandwidth
   capacities and is produced by bandwidth generators, previously known
   as bandwidth scanners.