From 3a57e9b614487f064ffefab970c8fe6d599155e9 Mon Sep 17 00:00:00 2001
From: Heiko Schaefer <heiko@schaefer.name>
Date: Thu, 21 Sep 2023 11:36:05 +0200
Subject: [PATCH] Glossary: adjust to appropriate syntax

As outlined in #15
---
 book/source/15-glossary.md  | 19 -------------------
 book/source/15-glossary.rst | 38 +++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 19 deletions(-)
 delete mode 100644 book/source/15-glossary.md
 create mode 100644 book/source/15-glossary.rst

diff --git a/book/source/15-glossary.md b/book/source/15-glossary.md
deleted file mode 100644
index 5e48a32..0000000
--- a/book/source/15-glossary.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Glossary
-
-This document aims to enumerate and clarify alternative terms that have been
-used for the same concept in the OpenPGP space, as well as to document
-terminology specific to OpenPGP CA.
-
-- Authentication
-- Bridge: Two instances of OpenPGP CA mark each other as (scoped) trusted
-  introducers, which means that users in both organizations see each other
-  as authenticated
-- Certification ("Signature" on a certificate)
-- Key / OpenPGP Key (Certificate)
-- Key creation workflow: centralized/decentralized
-- OpenPGP
-- Revocation certificate
-- Trust signature ("tsig"), a speficic type of certification for a
- certificate, which marks that key as a "trusted introducer" (i.e. the
-  party that creates the trust signature signals that they will trust
-  certifications that the "trusted introducer" makes on certificates)
diff --git a/book/source/15-glossary.rst b/book/source/15-glossary.rst
new file mode 100644
index 0000000..7dca174
--- /dev/null
+++ b/book/source/15-glossary.rst
@@ -0,0 +1,38 @@
+Glossary
+========
+
+.. glossary::
+    :sorted:
+
+    Authentication
+      Checking the validity of a claim (e.g. an identity claim). Making sure that a claim is "authentic".
+
+    Certification
+      "Third party Signature" on a certificate, making a statement about that certificate, or an identity in the certificate
+
+    Delegation
+      See :term:`Trust signature`
+
+    Revocation certificate
+      A type of signature that invalidates a previous statement made via a signature
+
+    Certificate
+      See :term:`OpenPGP Certificate`
+
+    Key
+      See :term:`OpenPGP Key`
+
+    OpenPGP Key
+      Used either for an OpenPGP Certificate (containing public key material and metadata), or for an See :term:`OpenPGP Private Key`
+
+    OpenPGP Private Key
+      The combination of an :term:`OpenPGP Certificate` and the associated private key material
+
+    OpenPGP Certificate
+      An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material)
+
+    Trust signature
+      a specific type of certification for a certificate, which marks that key as a "trusted introducer" (i.e. the party that creates the trust signature signals that they will trust certifications that the "trusted introducer" makes on certificates)
+
+    tsig
+      See :term:`Trust signature`