docs, privileges: more streamlining of how to work with privs/modes

Super-duper deemphasized that privileges are integer values. Removed the
actual values from code examples, to show logic only.

Condensed admonitions about nonstandard privilege levels/modes into a
single location, with cross-references.

docs/source/plugin/privileges.rst

@@ -21,7 +21,10 @@ channel privileges available:
 * :attr:`~sopel.privileges.AccessLevel.VOICE`: the privilege to send messages to
   a channel with the ``+m`` mode, set and unset by modes ``+v`` and ``-v``
 
-Since then, other privileges have been adopted by IRC servers and clients:
+.. _nonstandard privilege levels:
+
+Over time, IRC servers and clients have adopted various combinations of
+nonstandard, less formally defined privilege levels:
 
 * :attr:`~sopel.privileges.AccessLevel.HALFOP`: intermediate level between VOICE
   and OP, set and unset by modes ``+h`` and ``-h``
@@ -30,11 +33,10 @@ Since then, other privileges have been adopted by IRC servers and clients:
 * :attr:`~sopel.privileges.AccessLevel.OWNER`: channel owner, above ADMIN and OP,
   set and unset by modes ``+q`` and ``-q``
 
-.. important::
-
-    Not all IRC networks support these added privilege modes. If you are writing
-    a plugin for public distribution, ensure your code behaves sensibly if only
-    ``+v`` (voice) and ``+o`` (op) modes exist.
+**It's important to note that not all IRC networks support these nonstandard
+privileges, and the ones that do may not support all of them.** If you are
+writing a plugin for public distribution, ensure your code behaves sensibly when
+only the standardized ``+v`` (voice) and ``+o`` (op) modes exist.
 
 Access rights
 =============

sopel/privileges.py

@@ -15,26 +15,17 @@
 class AccessLevel(enum.IntFlag):
     """Enumeration of available user privilege levels.
 
-    Comparing privileges
-    ====================
-
-    This class represents privileges as powers of two, with higher values
-    assigned to higher-level privileges::
+    This class represents privileges as comparable, combinable flags. Lower
+    privilege levels compare as *less than* (``<``) higher ones::
 
         >>> from sopel.privileges import AccessLevel
         >>> AccessLevel.VOICE < AccessLevel.HALFOP < AccessLevel.OP \\
         ... < AccessLevel.ADMIN < AccessLevel.OWNER
         True
 
-    Then a user's privileges are represented as a sum of privilege levels::
+    A user's privileges are represented as a combination of privilege levels::
 
-        >>> AccessLevel.VOICE
-        1
-        >>> AccessLevel.OP
-        4
         >>> priv = AccessLevel.VOICE | AccessLevel.OP
-        >>> priv
-        5
 
     This allows using comparators and bitwise operators to compare privileges.
     Here, ``priv`` contains both VOICE and OP privileges, but not HALFOP::
@@ -46,9 +37,9 @@ class AccessLevel(enum.IntFlag):
 
     .. important::
 
-        Do not refer directly to the integer value of a privilege level in your
-        code; the values may change. Use the appropriate member of this class as
-        a reference point instead.
+        Do not hard-code the value of a privilege level in your code; the values
+        may change. Always reference or compare to the appropriate member of
+        this class directly.
 
     """
     # values should behave as ints, but their string representations should
@@ -77,9 +68,7 @@ class AccessLevel(enum.IntFlag):
 
     .. important::
 
-        Not all IRC networks support this privilege mode. If you are writing a
-        plugin for public distribution, ensure your code behaves sensibly if
-        only ``+v`` (voice) and ``+o`` (op) modes exist.
+        Beware: This is one of the `nonstandard privilege levels`_.
 
     """
 
@@ -105,9 +94,7 @@ class AccessLevel(enum.IntFlag):
 
     .. important::
 
-        Not all IRC networks support this privilege mode. If you are writing a
-        plugin for public distribution, ensure your code behaves sensibly if
-        only ``+v`` (voice) and ``+o`` (op) modes exist.
+        Beware: This is one of the `nonstandard privilege levels`_.
 
     """
 
@@ -122,9 +109,7 @@ class AccessLevel(enum.IntFlag):
 
     .. important::
 
-        Not all IRC networks support this privilege mode. If you are writing a
-        plugin for public distribution, ensure your code behaves sensibly if
-        only ``+v`` (voice) and ``+o`` (op) modes exist.
+        Beware: This is one of the `nonstandard privilege levels`_.
 
     """
 
@@ -142,8 +127,6 @@ class AccessLevel(enum.IntFlag):
 
     .. important::
 
-        Not all IRC networks support this privilege mode. If you are writing a
-        plugin for public distribution, ensure your code behaves sensibly if
-        only ``+v`` (voice) and ``+o`` (op) modes exist.
+        Beware: This is one of the `nonstandard privilege levels`_.
 
     """