From 3f388086cb7b9bb2fec54da6c4d02794c17b1b36 Mon Sep 17 00:00:00 2001
From: Stefano Zacchiroli <zack@upsilon.cc>
Date: Fri, 24 Apr 2020 10:11:41 +0200
Subject: [PATCH] SWHID doc: improve wording of intrinsic parts v. the rest

---
 docs/persistent-identifiers.rst | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/persistent-identifiers.rst b/docs/persistent-identifiers.rst
index 301ce1fc..6f1fa590 100644
--- a/docs/persistent-identifiers.rst
+++ b/docs/persistent-identifiers.rst
@@ -7,18 +7,17 @@ SoftWare Heritage persistent IDentifiers (SWHID)
 **version 1.2**
 
 
-Description
-===========
+Overview
+========
 
 You can point to objects present in the Software Heritage archive by the means
 of **SoftWare Heritage persistent IDentifiers**, or **SWHID** for short, that
 are guaranteed to remain stable (persistent) over time. Their syntax, meaning,
 and usage is described below. Note that they are identifiers and not URLs, even
-though an URL-based resolver for Software Heritage persistent identifiers is
-also provided.
+though URL-based resolvers for SWHIDs are also available.
 
 A SWHID can point to any software artifact (or "object") available in the
-Software Heritage archive. Objects come in different types, and most notably:
+Software Heritage archive. Objects come in different types:
 
 * contents
 * directories
@@ -27,13 +26,15 @@ Software Heritage archive. Objects come in different types, and most notably:
 * snapshots
 
 Each object is identified by an intrinsic, type-specific object identifier that
-is embedded in its SWHID as described below. SWHIDs are strong cryptographic
-hashes computed on the entire set of object properties to form a `Merkle
-structure <https://en.wikipedia.org/wiki/Merkle_tree>`_.
+is embedded in its SWHID as described below. The intrinsic identifiers embedded
+in SWHIDs are strong cryptographic hashes computed on the entire set of object
+properties. Together, these identifiers form a `Merkle structure
+<https://en.wikipedia.org/wiki/Merkle_tree>`_, specifically a Merkle DAG.
 
 See the :ref:`Software Heritage data model <data-model>` for an overview of
 object types and how they are linked together. See
-:py:mod:`swh.model.identifiers` for details on how SWHIDs are computed.
+:py:mod:`swh.model.identifiers` for details on how the intrinsic identifiers
+embedded in SWHIDs are computed.
 
 
 Syntax
-- 
GitLab