PEP 691: touch up (#2668)

pep-0691.rst

@@ -144,6 +144,8 @@ return data, whose interpretation is defined by the version of that data, and th
 serialized into the target serialization format.
 
 
+.. _json-serialization:
+
 JSON Serialization
 ------------------
 
@@ -217,13 +219,14 @@ Project Detail
 ~~~~~~~~~~~~~~
 
 The format of this URL is ``/<project>/`` where the ``<project>`` is replaced by the
-:pep:`503` normalized name for that project, so a project named "Holy_Grail" would
+:pep:`503` normalized name for that project, so a project named "Silly_Walk" would
-have a URL like ``/holy-grail/``.
+have a URL like ``/silly-walk/``.
 
-This URL must respond with a JSON encoded dictionary that has three keys, ``name``,
+This URL must respond with a JSON encoded dictionary that has three keys:
-which represents the normalized name of the project, ``files``. The ``files`` key is
+
-a list of dictionaries, each one representing an individual file. Finally the ``meta``
+- ``name``: The normalized name of the project.
-key which is the general response metadata described earlier.
+- ``files``: A list of dictionaries, each one representing an individual file.
+- ``meta``: The general response metadata as `described earlier <json-serialization_>`__.
 
 Each individual file dictionary has the following keys:
 
@@ -236,7 +239,7 @@ Each individual file dictionary has the following keys:
 
   The ``hashes`` dictionary **MUST** be present, even if no hashes are available
   for the file, however it is **HIGHLY** recommended that at least one secure,
-  guaranteed to be available hash is always included.
+  guaranteed-to-be-available hash is always included.
 
   By default, any hash algorithm available via `hashlib
   <https://docs.python.org/3/library/hashlib.html>`_ (specifically any that can
@@ -254,11 +257,12 @@ Each individual file dictionary has the following keys:
 - ``dist-info-metadata``: An **optional** key that indicates
   that metadata for this file is available, via the same location as specified in
   :pep:`658` (``{file_url}.metadata``). Where this is present, it **MUST** be
-  boolean to indicate if the file has an associated metadata file, or a dictionary
+  either a boolean to indicate if the file has an associated metadata file, or a
-  mapping hash names to a hex encoded digest of the metadata's hash.
+  dictionary mapping hash names to a hex encoded digest of the metadata's hash.
 
-  When this is a dictionary of hashes, then all the same requirements and
+  When this is a dictionary of hashes instead of a boolean, then all the same
-  recommendations as the ``hashes`` key hold true for this key as well.
+  requirements and recommendations as the ``hashes`` key hold true for this key as
+  well.
 
   If this key is missing then the metadata file may or may not exist. If the key
   value is truthy, then the metadata file is present, and if it is falsey then it
@@ -267,11 +271,12 @@ Each individual file dictionary has the following keys:
   It is recommended that servers make the hashes of the metadata file available if
   possible.
 - ``gpg-sig``: An **optional** key that acts a boolean to indicate if the file has
-  an associated GPG signature or not. If this key does not exist, then the signature
+  an associated GPG signature or not. The URL for the signature file follows what
-  may or may not exist.
+  is specified in :pep:`503` (``{file_url}.asc``). If this key does not exist, then
-- ``yanked``: An **optional** key which may be a boolean to indicate if the file
+  the signature may or may not exist.
-  has been yanked, or a non empty, but otherwise arbitrary, string to indicate that
+- ``yanked``: An **optional** key which may be either a boolean to indicate if the
-  a file has been yanked with a specific reason. If the ``yanked`` key is present
+  file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
+  that a file has been yanked with a specific reason. If the ``yanked`` key is present
   and is a truthy value, then it **SHOULD** be interpreted as indicating that the
   file pointed to by the ``url`` field has been "Yanked" as per :pep:`592`.
 
@@ -417,7 +422,7 @@ content type over another, they may use the ``Accept`` header's
 syntax.
 
 This allows a client to specify a priority for a specific entry in their
-``Accept`` header, by append a ``;q=`` followed by a value between ``0`` and
+``Accept`` header, by appending a ``;q=`` followed by a value between ``0`` and
 ``1`` inclusive, with up to 3 decimal digits. When interpreting this value,
 an entry with a higher quality has priority over an entry with a lower quality,
 and any entry without a quality present will default to a quality of ``1``.
@@ -607,14 +612,15 @@ It is recommended that servers:
   long as they're receiving non trivial traffic that uses the HTML responses.
 
 - When encountering an ``Accept`` header that does not contain any content types
-  that it knows how to work with, should not ever return a ``300 Multiple Choice``
+  that it knows how to work with, the server should not ever return a
-  response, and it should be preferred to return a ``406 Not Acceptable`` response.
+  ``300 Multiple Choice`` response, and instead return a ``406 Not Acceptable``
+  response.
 
   - However, if choosing to use the endpoint configuration, you should prefer to
     return a ``200 OK`` response in the expected content type for that endpoint.
 
-- When selecting an acceptable version, should choose the highest version that
+- When selecting an acceptable version, the server should choose the highest version
-  the client supports, with the most expressive/featureful serialization format,
+  that the client supports, with the most expressive/featureful serialization format,
   taking into account the specificity of the client requests as well as any
   quality priority values they have expressed, and it should only use the
   ``text/html`` content type as a last resort.
@@ -694,18 +700,6 @@ so if there's some new piece of data that an installer might need, future PEPs c
 easily make that available.
 
 
-Why is the root URL a dictionary instead of a list?
----------------------------------------------------
-
-The most natural direct translation of the root URL being a list of links is to turn
-it into a list of objects. However, stepping back, that's not the most natural way
-to actually represent this data. This was a result of a HTML limitation that we had to
-work around. With a list (either of ``<a>`` tags, or objects) there's nothing stopping
-you from listing the same project twice and other unwanted patterns.
-
-A dictionary also allows for an average of constant-time access given the project name.
-
-
 Why include the filename when the URL has it already?
 -----------------------------------------------------