take pass at terminology, suggest changes to disambiguate 'address'

1 files changed, 51 insertions, 44 deletions

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index a46db61..1601264 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -194,12 +194,12 @@
         <t>
          is a UTF-8 <xref target="RFC3629"/> URI
          <xref target="RFC3986"/> which can be
-         used to contact a peer.
+         used to contact a <em>Peer</em>.
          An example of an addressing scheme used in
          this document is "r5n+ip+tcp", which refers to a standard TCP/IP socket
          connection. The "hier"-part of the URI must provide a suitable
          address for the given addressing scheme.
-         The following are non-normative examples of address strings:
+         The following are non-normative examples of <em>Address</em> strings:
         </t>
         <figure title="Example Address URIs.">
           <artwork name="" type="" align="left" alt=""><![CDATA[
@@ -211,119 +211,126 @@ gnunet+tcp://12.3.4.5/
       </dd>
       <dt>Applications</dt>
       <dd>
-        Applications are components which directly use the DHT overlay
-        interfaces. Possible applications include the GNU Name System
+        <em>Application</em>s are higher-layer components which directly use the DHT overlay
+        interfaces. Possible <em>Application</em>s include the GNU Name System
         <xref target="I-D.schanzen-gns"/> and the GNUnet
         Confidential Ad-hoc Decentralized End-to-End Transport (CADET)
         <xref target="cadet"/>.
       </dd>
       <dt>Application API</dt>
       <dd>
-        The application API exposes the core operations of the DHT overlay
-        to applications.
-        This includes storing blocks in the DHT and retrieving blocks from the DHT.
+        The <em>Application API</em> exposes the core operations of the DHT overlay
+        to <em>Applications</em>.
+        This includes storing <em>Block</em>s in the DHT and retrieving
+        <em>Block</em>s from the DHT.
       </dd>
       <dt>Block</dt>
       <dd>
         Variable-size unit of payload stored in the DHT
-        under a <tt>Key</tt>.
+        under a <em>Key</em>.
         In the context of &quot;key-value stores&quot; this
-        refers to &quot;value&quot; stored under a key.
+        refers to &quot;value&quot; stored under a <em>Key</em>.
       </dd>
       <dt>Block Storage</dt>
       <dd>
-        The <tt>Block Storage</tt> component is used to persist and manage
-        <tt>Block</tt> data by peers.
+        The <em>Block Storage</em> component is used to persist and manage
+        <em>Block</em>s stored by <em>Peer</em>s.
         It includes logic for enforcing storage quotas, caching strategies and
-        data validation.
+        <em>Block</em> validation.
       </dd>
       <dt>Block-Type</dt>
       <dd>
-        A unique 32-bit value identifying the data format of a <tt>Block</tt>.
-        Block-Types are either private or registered in the GANA block type registry (see
+        A unique 32-bit value identifying the data format of a <em>Block</em>.
+        <em>Block-Types</em> are either private or registered in the GANA block type registry (see
         <xref target="gana_block_type"/>).
       </dd>
       <dt>Bootstrapping</dt>
       <dd>
-        Bootstrapping is the initial process of establishing a connection to the peer-to-peer
+        <em>Bootstrapping</em> is the initial process of establishing a connection
+        to the peer-to-peer
         network.
-        This initially requires an initial, non-empty set of reachable peers and corresponding
-        addresses supported by the implementation to connect to.
+        This initially requires an initial, non-empty set of reachable <em>Peer</em>s and corresponding
+        <em>Address</em>es supported by the implementation to connect to.
       </dd>
       <dt>Initiator</dt>
       <dd>
-        The peer that initially creates and sends a DHT protocol message (<xref target="p2p_hello"/>,
+        The <em>Peer</em> that initially creates and sends a DHT protocol message (<xref target="p2p_hello"/>,
         <xref target="p2p_put"/>, <xref target="p2p_get"/>, <xref target="p2p_result"/>).
       </dd>
       <dt>HELLO block</dt>
       <dd>
-        A <tt>HELLO</tt> block is a block with a dedicated block type and is specified in this document.
-        The <tt>HELLO</tt> block is used to store and retrieve Peer addresses.
+        A <tt>HELLO block</tt> is a <em>Block</em> with a <em>Block-Type</em> <tt>DHT_HELLO</tt> (13).
+        A <tt>HELLO block</tt> is used to store and retrieve <em>Address</em>es of a <em>Peer</em>.
         In this document, <tt>HELLO</tt> blocks are used by the peer discovery mechanism.
       </dd>
       <dt>HELLO URL</dt>
       <dd>
-        <tt>HELLO</tt> URLs are <tt>HELLO</tt> blocks in a URL representation.
-        They can used for out-of-band exchanges of peer information and are used for
-        address update signalling messages to neighbours. Example HELLO URLs and their
+        <tt>HELLO</tt> URLs are <tt>HELLO</tt> blocks represented as URLs.
+        They can used for out-of-band exchanges of <em>Peer</em> <em>Address</em>
+        information and are used for
+        address update signalling messages to <em>Neighbours</em>. Example HELLO URLs and their
         format can be found in <xref target="hello_url"/>.
       </dd>
       <dt>Key</dt>
       <dd>
         512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
-  stored under the same key. <tt>Peer Addresses</tt> are valid keys.
+        stored under the same <em>Key</em>. A <em>Peer Address</em> is also a <tt>Key</tt>.
         In the context of &quot;key-value stores&quot; this
-        refers to &quot;key&quot; under which values (blocks) are stored.
+        refers to &quot;key&quot; under which values (<em>Block</em>s) are stored.
       </dd>
       <dt>Message Processing</dt>
       <dd>
-        The Message Processing component processes requests from and
-  generates responses to applications and the underlay network.
+        The <em>Message Processing</em> component of the DHT implementation processes
+        requests from and generates responses to <em>Application</em>s
+        and the <em>Underlay Interface</em>.
       </dd>
       <dt>Neighbor</dt>
       <dd>
-        A neighbor is a peer which is directly able to communicate
-  with our peer via the <tt>Underlay Interface</tt>.
+        A neighbor is a <em>Peer</em> which is directly able to communicate
+        with our <em>Peer</em> via the <em>Underlay Interface</em>.
       </dd>
       <dt>Peer</dt>
       <dd>
-        A host that is participating in the overlay.  Peers are
+        A host that is participating in the overlay by running an implementation
+        of the DHT protocol.  Each participating host is
         responsible for holding some portion of the data that has been
         stored in the overlay, and they are responsible for routing
-        messages on behalf of other hosts as needed by the Routing
-        Algorithm.
+        messages on behalf of other <em>Peer</em>s as needed by the <em>Routing
+        Algorithm</em>.
       </dd>
+      <!-- FIXME: this overloads the term 'address'. We should use 'Peer Identity'! -->
       <dt>Peer Address</dt>
       <dd>
-        The <tt>Peer Address</tt> is the identifier used on the Overlay
-        to address a peer.
-  It is a SHA-512 hash of the <tt>Peer ID</tt>.
+        The <em>Peer Address</em> is the identifier used on the overlay
+        to identify a <em>Peer</em>.  It is a SHA-512 hash of the <tt>Peer ID</tt>.
       </dd>
+      <!-- FIXME: this obscures the public key nature. We should use "Peer Public Key"! -->
       <dt>Peer ID</dt>
       <dd>
-        The <tt>Peer ID</tt> is the public key which is used to authenticate
-        a peer in the underlay.
-        The Peer ID is the public key of the corresponding
+        The <em>Peer ID</em> is the public key which is used to authenticate
+        a <em>Peer</em> in the underlay.
+        The <em>Peer ID</em> is the public key of the corresponding
         Ed25519<xref target="ed25519" /> peer private key.
       </dd>
       <dt>Routing</dt>
       <dd>
-        The Routing component includes the routing table as well as
-        routing and peer selection logic. It facilitates the R<sup>5</sup>N routing
+        The <em>Routing</em> component includes the routing table as well as
+        routing and <em>Peer</em> selection logic. It facilitates the R<sup>5</sup>N routing
         algorithm with required data structures and algorithms.
       </dd>
       <dt>Responsible Peer</dt>
       <dd>
-        The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as
+        The <em>Peer</em> <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as
         defined by the <tt>SelectClosestPeer(K, P)</tt> algorithm (see
         <xref target="routing"/>.
       </dd>
       <dt>Underlay Interface</dt>
       <dd>
-        The Underlay Interface is an abstraction layer on top of the
-        supported links of a peer. Peers may be linked by a variety of
+        The <em>Underlay Interface</em> is an abstraction layer on top of the
+        supported links of a <em>Peer</em>. Peers may be linked by a variety of
         different transports, including "classical" protocols such as
-        TCP, UDP and TLS or advanced protocols such as GNUnet, I2P or Tor.
+        TCP, UDP and TLS or higher-layer protocols such as GNUnet, I2P or Tor.
+        <!-- FIXME: add references to GNUnet/I2P/Tor here! -->
       </dd>
     </dl>
     </section>