From 2787a192012d1ad6a57e9f1af3df0c2bc1fbc63b Mon Sep 17 00:00:00 2001
From: Nick Coghlan <ncoghlan@gmail.com>
Date: Nov 30 2017 06:34:03 +0000
Subject: Issue #93: Add a glossary


Initial entries for install profiles and system profiles.

---

diff --git a/source/development/building-modules.rst b/source/development/building-modules.rst
index a8176cc..0733cd1 100644
--- a/source/development/building-modules.rst
+++ b/source/development/building-modules.rst
@@ -23,9 +23,9 @@ separated such that:
   that's tracking a particular upstream release series, a set of arbitrary
   calendar dates, a particular Fedora release, or even just the main line of
   upstream development.
-* the system profile for a given release then nominates the default streams
-  for each module known to the system. For example, the system profile for
-  the F27 modular server release can be found in the f27 branch of the
+* the :term:`system profile` for a given release then nominates the default
+  streams for each module known to the system. For example, the system profile
+  for the F27 modular server release can be found in the f27 branch of the
   `fedora-modular-server repo`_
   in dist-git.
 
diff --git a/source/development/building-modules/testing.rst b/source/development/building-modules/testing.rst
index 4c46f57..e5176f2 100644
--- a/source/development/building-modules/testing.rst
+++ b/source/development/building-modules/testing.rst
@@ -58,8 +58,8 @@ PostreSQL 9.6 stream, set up a local repository for them (including the module
 metadata), enable that repository, and then install the module with its default
 profile.
 
-A non-default install profile can be requested by appending the profile name to
-the build identifer, separated by a ``/``::
+A non-default :term:`install profile` can be requested by appending the profile
+name to the build identifer, separated by a ``/``::
 
     # /LOCAL.sh postgresql:9.6:20171018083530/client
 
@@ -116,7 +116,7 @@ Modular compose tests
 ~~~~~~~~~~~~~~~~~~~~~
 
 Finally, a base set of automated tests check that the core set of modules
-defined in Fedora's system profile can all be installed and updated.
+defined in Fedora's :term:`system profile` can all be installed and updated.
 
 These tests are written as Ansible playbooks, and can be found in the
 `compose-tests repository <https://github.com/fedora-modularity/compose-tests/tree/master/tests>`__.
diff --git a/source/development/glossary.rst b/source/development/glossary.rst
new file mode 100644
index 0000000..c8de9cd
--- /dev/null
+++ b/source/development/glossary.rst
@@ -0,0 +1,27 @@
+Glossary
+========
+
+Definitions of key terms and concepts for the Modular Fedora project.
+
+.. glossary::
+
+   default install profile
+      The install profile used when no other install profile is specified.
+      It is always called `"default"`. When the default profile is empty,
+      it indicates the module is intended solely to help manage dependencies
+      for other modules, rather than being installed by end users directly.
+
+   install profile
+      A named set of packages within a module that can readily be installed
+      with a single command. Akin to package groups at the distro level, but
+      specific to the module that defines them.
+
+      For example, the PostgreSQL module's `"client"` profile installs only the
+      client libraries, instead of the full database server::
+
+          dnf install postgresql:9.6/client
+
+   system profile
+      The system profile nominates a set of modules that it expects to have
+      available for installation, and the default stream to use within each
+      of those modules when no specific stream is selected.
diff --git a/source/docs.rst b/source/docs.rst
index f350583..09e662d 100644
--- a/source/docs.rst
+++ b/source/docs.rst
@@ -1,10 +1,5 @@
-.. Test1 documentation master file, created by
-   sphinx-quickstart on Sun Jan  1 09:40:17 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Documentation Index
-=================================
+===================
 
 
 .. toctree::
@@ -27,6 +22,7 @@ Documentation Index
     :caption: Development
     :maxdepth: 2
 
+    development/glossary
     development/resources
     development/building-modules
     development/building-containers