DOC: Add text on role permissions

src/doc/permissions.rst

@@ -44,7 +44,21 @@ below: role permissions and entity permissions.
 Role permissions
 ***********************
 
-See the :ref:`Role Permission Table` for a full list of role permissions.
+As the name suggests, role permissions are assigned to a specific role and
+define whether, in general, a particular role is allowed, e.g., to perform
+specific transactions, update roles or users, or execute server-side
+scripts. See the :ref:`role-permissions table<Role Permission Table>` for a full list of role
+permissions. The most common are
+
+- ``TRANSACTiON:*``: Allows to perform any write transaction (in general). Note
+  that this is the necessary but not sufficient condition for
+  deleting/inserting/updating an entity and the corresponding :ref:`entity
+  permissions<entity-permissions>` are required, too.
+- ``SCRIPTING:EXECUTE:?PATH?``: Permission to execute a server-side script under
+  the given path. Note that, for utilizing the wild cards feature, you have to
+  use ``':'`` as path separator. E.g. ``'SCRIPTING:EXECUTE:my_scripts:*'`` would
+  be the permission to execute all executables below the ``my_scripts``
+  directory.
 
 .. _entity-permissions:
 
@@ -55,8 +69,8 @@ As the name suggests, entity permissions define what a certain user or role is
 allowed to do with a specific entity. Thus, entity permissions can be used to,
 e.g., deny everone but administration users to update or delete a specific
 record types, or to allow everyone to retrieve a specific record. See the
-:ref:`Entity permissions table` for a full list of possible entity
-permissions. Typical permissions are:
+:ref:`entity-permissions table<Entity permissions table>` for a full list of
+possible entity permissions. Typical permissions are:
 
 -  ``RETRIEVE:ENTITY``: To retrieve the full entity (name,
    description, data type, …) with all parents and properties (unless
@@ -139,13 +153,15 @@ find a more detailed description of the possible ways of setting permissions.
    Python library. Currently the best documentation is inside various files
    which use the permission API:
 
-   -  The `example file
-      <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/set_permissions.py>`__
-   -  The ``caosdb_admin.py`` `utility script
-      <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
-   -  The `integration tests
-      <https://gitlab.com/caosdb/caosdb-pyinttest/-/blob/main/tests/test_permissions.py>`__
-      also cover quite a bit of the permission API.
+   - The `example file
+     <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/examples/set_permissions.py>`__
+   - The ``caosdb_admin.py`` `utility script
+     <https://gitlab.com/caosdb/caosdb-pylib/-/blob/main/src/caosdb/utils/caosdb_admin.py>`__
+   - There is a comprehensive `example <TODO/insert/when/pylib/MR/is/merged>`_
+     in PyCaosDB's gode gallery.
+   - The `integration tests
+     <https://gitlab.com/caosdb/caosdb-pyinttest/-/blob/main/tests/test_permissions.py>`__
+     also cover quite a bit of the permission API.
 
 -  **WebUI:** This is currently work in progress. A WebUI ACM module which uses the
    GRPC interface is under `active development