Fix trac 4116 and create a global dynamic glossary

Add a global Sphinx generated glossary.
Link the static GBS glossary to the global glossary.

docs/glossary.rst

@@ -0,0 +1,54 @@
+.. -*- coding: utf-8 -*-
+
+============================
+Glossary of Tahoe-LAFS Terms
+============================
+
+
+.. glossary::
+
+   `Foolscap <https://github.com/warner/foolscap/>`_
+     an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted
+
+   storage server
+     a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations
+
+   storage service
+     a Python object held in memory in the storage server which provides the implementation of the storage protocol
+
+   introducer
+     a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers
+
+   :ref:`fURLs <fURLs>`
+     a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol
+     (the storage service is an example of such an object)
+
+   :ref:`NURLs <NURLs>`
+     a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap
+
+   swissnum
+     a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service
+
+   lease
+     state associated with a share informing a storage server of the duration of storage desired by a client
+
+   share
+     a single unit of client-provided arbitrary data to be stored by a storage server
+     (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached)
+
+   bucket
+     a group of one or more immutable shares held by a storage server and having a common storage index
+
+   slot
+     a group of one or more mutable shares held by a storage server and having a common storage index
+     (sometimes "slot" is considered a synonym for "storage index of a slot")
+
+   storage index
+     a 16 byte string which can address a slot or a bucket
+     (in practice, derived by hashing the encryption key associated with contents of that slot or bucket)
+
+   write enabler
+     a short secret string which storage servers require to be presented before allowing mutation of any mutable share
+
+   lease renew secret
+     a short secret string which storage servers required to be presented before allowing a particular lease to be renewed

docs/index.rst

@@ -32,6 +32,8 @@ preserving your privacy and security.
    anonymity-configuration
    known_issues
 
+   glossary
+
 .. toctree::
    :maxdepth: 1
    :caption: Tahoe-LAFS in Depth

docs/specifications/http-storage-node-protocol.rst

@@ -16,53 +16,53 @@ The Tahoe-LAFS client will also need to change but it is not expected that it wi
 Glossary
 --------
 
-.. glossary::
+Foolscap
+ an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted
 
-   `Foolscap <https://github.com/warner/foolscap/>`_
+storage server
-     an RPC/RMI (Remote Procedure Call / Remote Method Invocation) protocol for use with Twisted
+ a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations
 
-   storage server
+storage service
-     a Tahoe-LAFS process configured to offer storage and reachable over the network for store and retrieve operations
+ a Python object held in memory in the storage server which provides the implementation of the storage protocol
 
-   storage service
+introducer
-     a Python object held in memory in the storage server which provides the implementation of the storage protocol
+ a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers
 
-   introducer
+:ref:`fURLs <fURLs>`
-     a Tahoe-LAFS process at a known location configured to re-publish announcements about the location of storage servers
+ a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol
+ (the storage service is an example of such an object)
 
-   :ref:`fURLs <fURLs>`
+:ref:`NURLs <NURLs>`
-     a self-authenticating URL-like string which can be used to locate a remote object using the Foolscap protocol
+ a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap
-     (the storage service is an example of such an object)
 
-   :ref:`NURLs <NURLs>`
+swissnum
-     a self-authenticating URL-like string almost exactly like a fURL but without being tied to Foolscap
+ a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service
 
-   swissnum
+lease
-     a short random string which is part of a fURL/NURL and which acts as a shared secret to authorize clients to use a storage service
+ state associated with a share informing a storage server of the duration of storage desired by a client
 
-   lease
+share
-     state associated with a share informing a storage server of the duration of storage desired by a client
+ a single unit of client-provided arbitrary data to be stored by a storage server
+ (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached)
 
-   share
+bucket
-     a single unit of client-provided arbitrary data to be stored by a storage server
+ a group of one or more immutable shares held by a storage server and having a common storage index
-     (in practice, one of the outputs of applying ZFEC encoding to some ciphertext with some additional metadata attached)
 
-   bucket
+slot
-     a group of one or more immutable shares held by a storage server and having a common storage index
+ a group of one or more mutable shares held by a storage server and having a common storage index
+ (sometimes "slot" is considered a synonym for "storage index of a slot")
 
-   slot
+storage index
-     a group of one or more mutable shares held by a storage server and having a common storage index
+ a 16 byte string which can address a slot or a bucket
-     (sometimes "slot" is considered a synonym for "storage index of a slot")
+ (in practice, derived by hashing the encryption key associated with contents of that slot or bucket)
 
-   storage index
+write enabler
-     a 16 byte string which can address a slot or a bucket
+ a short secret string which storage servers require to be presented before allowing mutation of any mutable share
-     (in practice, derived by hashing the encryption key associated with contents of that slot or bucket)
 
-   write enabler
+lease renew secret
-     a short secret string which storage servers require to be presented before allowing mutation of any mutable share
+ a short secret string which storage servers required to be presented before allowing a particular lease to be renewed
 
-   lease renew secret
+Additional terms related to the Tahoe-LAFS project in general are defined in the :doc:`../glossary`
-     a short secret string which storage servers required to be presented before allowing a particular lease to be renewed
 
 The key words
 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL"

newsfragments/4116.documention

@@ -0,0 +1 @@
+Add a global Sphinx generated glossary. Link the static GBS glossary to the global glossary.