Docs: Introduce the concept of "userid" into the glossary.

1 files changed, 17 insertions, 7 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index deb4c1c8b..eb57f3d0d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -286,13 +286,23 @@ Glossary
      :term:`authorization policy`.
 
    principal
-     A *principal* is a string or unicode object representing a userid
-     or a group id.  It is provided by an :term:`authentication
-     policy`.  For example, if a user had the user id "bob", and Bob
-     was part of two groups named "group foo" and "group bar", the
-     request might have information attached to it that would
-     indicate that Bob was represented by three principals: "bob",
-     "group foo" and "group bar".
+     A *principal* is a string or unicode object representing an
+     entity, typically a user or group, having zero or more
+     :term:`permissions <permission>`.  Principals are provided by an
+     :term:`authentication policy`.  For example, if a user had the
+     user id "bob", and Bob was part of two groups named "group foo"
+     and "group bar", the request might have information attached to
+     it that would indicate that Bob was represented by three
+     principals: "bob", "group foo" and "group bar".
+
+   userid
+     A *userid* is a a string or unicode object used to identify and
+     authenticate a real-world user, often a person.  A userid is
+     supplied to an :term:`authentication policy` in order to discover
+     the user's :term:`principals <principal>`.  The default behavior
+     of the authentication policies :app:`Pyramid` provides is to
+     return the user's userid as one of the user's principals, but a
+     userid need not be a principal.
 
    authorization policy
      An authorization policy in :app:`Pyramid` terms is a bit of