Improve style and formatting

Avoid double plurals and fix a few typos.
Improve ReST formatting

Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>

Author: pombredanne

VERSION-RANGE-SPEC.rst

@@ -2,9 +2,7 @@
 vers: a mostly universal version range specifier
 ======================================================
 
-This specification is an attempt to standardize on a subset of existing
-notations to reliably communicate software package version ranges as used in
-package dependencies and vulnerabilities advisories.
+This specification is a new syntax for dependency and vulnerable version ranges.
 
 
 Context
@@ -27,20 +25,20 @@ interest. But in practice, all the versions may not yet exist when defining an
 open version range such as "v2.0 or later".
 
 Therefore, a version range is a necessary, compact and practical way to
-reference multiple versions rather that listing all the versions.
+reference multiple versions rather than listing all the versions.
 
 
 Problem
 --------
 
-Several version range syntaxes exist and have evolved separately to serve the
+Several version range notations exist and have evolved separately to serve the
 specific needs of each package ecosystem, vulnerability databases and tools.
 
-There is no (mostly) universal syntax for version ranges and there is no
+There is no (mostly) universal notation for version ranges and there is no
 universal way to compare two versions, even though the concepts that exist in
 most version range notations are similar.
 
-Each package type or ecosystem may define their own range syntax and version
+Each package type or ecosystem may define their own ranges notation and version
 comparison semantics for dependencies. And for security advisories, the lack of
 portable notation for vulnerable package version ranges means that these ranges
 may be either ambiguous or hard to compute and are typically replaced by
@@ -49,7 +47,7 @@ complete enumerations of all versions, such as the NVD CPEs.
 Because of this, expressing and resolving a version range is often a complex, or
 error prone task.
 
-In particular the need for common syntax for version has emerged based on the
+In particular the need for common notation for version has emerged based on the
 usage of Package URLs referencing vulnerable package version ranges such as in
 vulnerability databases like VulnerableCode.
 
@@ -66,8 +64,7 @@ in use:
   https://dart.dev/tools/pub/versioning provides a comprehensive coverage of the
   topic of versioning. But version resolution is using its own algorithm.
 
-- Python uses its own syntax and version ranges notation specific to Python
-  https://www.python.org/dev/peps/pep-0440/
+- Python uses its own version ranges notation https://www.python.org/dev/peps/pep-0440/
 
 - Debian and Ubuntu use their own notation
   https://www.debian.org/doc/debian-policy/ch-relationships.html
@@ -90,31 +87,38 @@ in use:
 - Go modules https://golang.org/ref/mod#versions use semver versions with
   specific version resolution algorithms.
 
+- Haskell Package Versioning Policy https://pvp.haskell.org/ provides a notation
+  similar to this specification based on a modified semver with extra notations
+  such as star and caret.
+
+
 Note that there is a closely related problem: the way two versions are compared
 as equal, lesser or greater is complex and package types may have evolved their
 own peculiar version comparison procedure. Semver is a prominent specification
-in this domain but this is just one of the many versioning schemes. Semver, Debian,
-RPM, PyPI,  Rubygems, and Composer all have their own subtly different ways of
-comparing two versions even though they may seem highly similar at first glance.
+in this domain but this is just one of the many versioning schemes. Semver,
+Debian, RPM, PyPI,  Rubygems, and Composer all have their own subtly different
+ways of comparing two versions even though they may seem highly similar at first
+glance.
 
 
 Solution
 ---------
 
-A solution to the many version ranges syntaxes is to design a new syntax to
+A solution to the many version range syntaxes is to design a new notation to
 unify them all with:
 
-- a mostly universal and minimalist syntax to express the version range  notations from many different package types and ecosystems.
+- a mostly universal and minimalist notation to express the version range
+  notations from many different package types and ecosystems.
 
 - the package type-specific definitions to normalize existing range expressions
-  to this common syntax.
+  to this common notation .
 
 - the designation of which algorithm or procedure to use when comparing two
   versions such that it is possible to resolve if a version is within or
   outside of a version range.
 
 We call this solution "version range specifier" or "vers" and it is described
-here.
+in this document.
 
 
 Version range specifier
@@ -139,7 +143,7 @@ constraint such as::
 Or a composite constraint grouping multiple ``<version-constraint>`` joined by
 an ampersand such as:
 
-   <comparator:version>&<comparator:version>...
+    <comparator:version>&<comparator:version>...
 
 The comma is a logical `OR` and the ampersand is a logical `AND`.
 
@@ -148,9 +152,8 @@ A version range specifier is therefore an "OR of ANDs". This is also called a
 See https://en.wikipedia.org/wiki/Disjunctive_normal_form for details.
 
 ``vers`` is the URI-scheme and is an acronym for "VErsion Range Specifier". It
-has been selected because it is short, obviously about version and available in
-the IANA URI-schemes registry for a future formal registration for this URI-
-scheme.
+has been selected because it is short, obviously about version and available
+for a future formal registration for this URI-scheme at the IANA registry.
 
 
 ``<versioning-scheme>``
@@ -159,15 +162,15 @@ scheme.
 The ``<versioning-scheme>`` (such as ``semver``,
 ``debian``, etc.) determines:
 
-- the specific syntax and conventions used for a version string encoded in this
-  scheme. Versioning schemes often specify a version segments separator and
+- the specific notation and conventions used for a version string encoded in
+  this scheme. Versioning schemes often specify a version segments separator and
   the meaning of each version segments, such as [major.minor.patch] in semver.
 
 - how two versions compare as greater or lesser to determine if a version is
   within or outside a range.
 
-- how a versioning scheme-specific range syntax can be transformed in the
-  ``vers`` syntax defined here.
+- how a versioning scheme-specific range notation can be transformed in the
+  ``vers`` notation defined here.
 
 Note: the ``<versioning-scheme>`` does not define which symbols to use to
 compare versions, and how to compose these as this is the substance of this
@@ -204,27 +207,34 @@ The ``<comparator>`` is one of these comparison operators:
   strings and is not versioning scheme-specific.
 
 - "!=": Version exclusion or inequality comparator. This means a version must
-  not be equal to the provided version and is excluded from the range. For
-  example: "!=1.2.3".
+  not be equal to the provided version and this version must be excluded from
+  the range. For example: "!=1.2.3" means that version "1.2.3" is not part of
+  the range.
 
 - "<", "<=": Less than or less-or-equal version comparators points to all
   versions less than or equal to the provided version. For example "<=1.2.3"
-  means less than or equal to "1.2.3". The way two version strings are compared
-  using these comparators is implied by the versioning scheme.
+  means less than or equal to "1.2.3". 
 
-- "<", "<=": Greater than or greater-or-equal version comparators points to
+- ">", ">=": Greater than or greater-or-equal version comparators points to
   all versions greater than or equal to the provided version. For example
   ">=1.2.3" means greater than or equal to "1.2.3".
 
 - The way two version strings are compared using these comparators is defined
   by the ``<versioning-scheme>``.
 
-- The syntax of a version such as "1.2.3" is defined by the
-  ``<versioning-scheme>``.
+- The structure and meaning of a version string such as "1.2.3" is defined by
+  the ``<versioning-scheme>``. For instance, ``semver`` defines three
+  dot-separated segments name major, minor and patch.
 
 - The special star "*" ``<version-constraint>`` matches any version. This star
-  constraint must be used **alone** in a version range specifier.
-  For example "vers:debian/\*" would resolve to any version.
+  constraint must be used **alone** in a version range specifier, exclusive of
+  any other constraint. For example "vers:debian/\*" resolves to any version.
+
+
+Examples
+~~~~~~~~~
+
+TODO.
 
 
 Normalized or canonical representation
@@ -237,10 +247,9 @@ Normalized or canonical representation
   "!=1.2.3" and " ! = 1.2. 3" are equivalent. And so are "1.2.3 & < = 2.0.0" and
   "1.2.3&<=2.0.0"
 
-- Version ranges specifiers are case-insensitive and lowercase in their
-  canonical form.
+- A version range specifier is case-insensitive and lowercase in canonical form.
 
-- The ordering of multiple ``<version-constraint>`` in a specifier is not
+- The ordering of multiple ``<version-constraint>`` in a range specifier is not
   significant. The canonical ordering is by sorting these by lexicographical
   order applied with this approach:
 
@@ -249,8 +258,9 @@ Normalized or canonical representation
 
 - A version in a ``<version-constraint>`` can only contain printable ASCII
   characters excluding the special characters used as separators and comparators
-  ``><=!,&*``. If required (which should be rare in practice) the version
-  in a constraint must be quoted using the URL quoting rules.
+  ``><=!,&*``. If it contains special characters (which should be rare in
+  practice) the version string in a constraint must be quoted using the URL
+  quoting rules.
 
 
 Using version range specifiers
@@ -265,19 +275,21 @@ outside of the range specifier.
 
 Some important usages derived from this primary usage include:
 
-- resolving a version range specifier to a list of concrete versions. In this
-  case, the input is the set of known versions of a package (typically obtained
-  from some package repository or registry). Each version is then tested
-  individually to check if it is within or outside the ranges. For example, this
-  can be used to determine which existing package versions are affected by a
-  known vulnerability version range specifier.
+- **Resolving a version range specifier to a list of concrete versions.**
+  In this case, the input is the set of known versions of a package (typically
+  obtained from some package repository or registry). Each version is then
+  tested individually to check if it is within or outside the ranges. For
+  example, this can be used to determine which existing package versions are
+  affected by a known vulnerability if they match the vulnerability version
+  range specifier.
 
-- selecting one of several versions that are within a range specifier.
+- **Selecting one of several versions that are within a range.**
   For example, package management tools need to determine what are the dependent
-  package versions of a package instance. This usually requires deploying
-  heuristics and algorithms (often complex such as sat solvers) that are
-  versioning-scheme- and tool-specific and outside of the scope for this
-  specification.
+  package versions of a package instance based the acceptable version ranges
+  provided with each dependency. This usually requires deploying heuristics and
+  algorithms (possibly complex such as sat solvers) that are versioning-scheme-
+  and tool-specific and outside of the scope for this specification; ``vers``
+  scope is limited to provide an input to the resolution process.
 
 
 Parsing version range specifiers
@@ -406,20 +418,33 @@ Implementations
 - Yours!
 
 
-Why not reuse existing version ranges syntaxes?
+Why not reuse existing version range notations?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Most existing version ranges syntaxes are tied to a specific version syntax and
-are therefore not readily applicable to other contexts such as tilde and caret
-ranges as used in Ruby or Dart. The inclusion of additional comparators is a
-result of the history and evolution in a package ecosystem.
+Most existing version range notations are tied to a specific version string
+syntax and are therefore not readily applicable to other contexts. For example,
+the use of elements such as tilde and caret ranges in Ruby or Dart notations
+implies that a certain structure exists in the version string (semver or semver-
+like). The inclusion of these additional comparators is a result of the history
+and evolution in a given package ecosystem to address specific needs.
 
 In practice, the unified and reduced set of comparators and syntax defined for
-``vers`` has been designed such that all these notations can be
-converted to a ``vers`` and back from a ``vers`` to the original notation. There
-are likely to be a few rare cases where round tripping may not be possible, and
-in anycase round tripping to and from ``vers`` may only produce equivalent
-results and not strictly the same original strings.
+``vers`` has been designed such that all these notations can be converted to a
+``vers`` and back from a ``vers`` to the original notation. 
+
+In contrast, this would not be possible with existing notations. For instance,
+the Python notation may not work with npm versions and reciprocally.
+
+There are likely to be a few rare cases where round tripping from and to
+``vers`` may not be possible, and in anycase round tripping to and from ``vers``
+may only produce equivalent results and not strictly the same original strings.
+
+Another issue with existing version range notations is that, they are primarily
+meant to be used for dependency constraints and may not readily be reused for
+vulnerable ranges. In particular, a vulnerability may exist for multiple
+"branches" of a given package (such as Django 2, 3 and 4) which may not be
+possible to express with a notation designed exclusively for dependent versions
+resolution.
 
 
 Why not use the NVD CPE Ranges?
@@ -447,20 +472,21 @@ https://github.com/npm/node-semver#ranges
 The node semver is very similar to this spec (this is also an OR of ANDs) but it
 has a few practical issues:
 
-  - The space means "AND" and significant whitespaces in a single string makes
-    normalization more complicated and may be a source of confusion or errors.
-    The explicit ampersand "AND" operator specified here improves clarity.
+- The space means "AND" and significant whitespace in a single string makes
+  normalization more complicated and may be a source of confusion or errors. The
+  explicit ampersand used an "AND" operator specified here improves clarity.
 
-  - There is no negation "!=" operator meaning that some version constraints
-    are difficult to express and require combining < and > comparators. For
-    instance stating that a vulnerability affects babel 6.2 or later but not
-    babel 7.0 is possible but difficult.
+- There is no negation "!=" operator meaning that some version constraints are
+  difficult to express and require combining < and > comparators. For instance
+  stating that a vulnerability affects babel 6.2 or later but not babel 7.0 is
+  possible but difficult.
+
+- The advanced range syntax has grown to be rather complex using hyphen, stars,
+  carets and tilde constructs are all tied to the JavaScript and npm ways of
+  handling versions in their specific ecosystem and furthermore are bound to the
+  semver semantics. These are not readily reusable elsewhere. And these multiple
+  comparators and modifiers make the grammar and parsing more complex.
 
-  - The advanced range syntax has grown to be rather complex using hyphen,
-    stars, carets and tilde constructs all tied to the JavaScript and npm ways
-    of handling versions in their specific ecosystem and furthermore bound to
-    semver. These are not readily reusable elsewhere. And these multiple
-    comparators and modifiers make the grammar and parsing more complex.
 
 Why not use Python pep-0440 ranges?
 #####################################
@@ -475,16 +501,17 @@ This specification is mostly compatible with and is similar to this ``vers``
 spec, but has a richer notation with some aspects specific to the version used
 only in the Python ecosystem.
 
-  - In particular pep-0440 uses tilde, triple equal and wildcard star operators
-    that are specific to how two Python versions are compared.
+- In particular pep-0440 uses tilde, triple equal and wildcard star operators
+  that are specific to how two Python versions are compared.
+
+- The comma separator between constraints is a logical "AND" rather than an
+  "OR". The "OR" does not exist in the syntax making some version ranges
+  harder to express, in particular for vulnerabilities that may affect several
+  exact versions or version ranges such as when there are multiple release
+  branches that exist in parallel. For instance a statement such as: Django 1.2
+  or later, or Django 2.2 or later or Django 3.2 or later is difficult to
+  express without an "OR" logic.
 
-  - The comma separator between constraints is a logical "AND" rather than an
-    "OR". The "OR" does not exist in the syntax making some version ranges
-    harder to express, in particular for vulnerabilities that may affect
-    several exact versions or version ranges such as when there are multiple
-    release branches that exist in parallel. For instance a statement such as:
-    Django 1.2 or later, or Django 2.2 or later or Django 3.2 or later is
-    difficult to express without an "OR" logic.
 
 Why not use Rubygems requirements notation?
 ##############################################################