From 9c1604e39e7859e92c5c7ad0bc674435f69f4d4c Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <progval+git@progval.net>
Date: Wed, 13 May 2020 19:57:09 +0200
Subject: [PATCH] Add more examples of capability management.

---
 use/capabilities.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/use/capabilities.rst b/use/capabilities.rst
index 72d5cc1..67fb325 100644
--- a/use/capabilities.rst
+++ b/use/capabilities.rst
@@ -215,6 +215,38 @@ Defaultcapabilities can be restored with either of these two commands::
     config setdefault capabilities
     config capabilities [config default capabilities]
 
+
+Example
+-------
+
+To make all this less abstract, here is a popular example of what
+capabilities are used for: disabling a plugin or command for everyone
+but a select group of people
+
+Allowing only user ``foo`` to use the ``Games`` plugin, globally::
+
+    defaultcapability add -games
+    admin capability add foo games
+
+And to undo it::
+
+    defaultcapability remove -Games
+    admin capability remove foo Games
+
+Same, but only on ``#channel``::
+
+    channel capability set #channel -games
+    channel capability add #channel foo games
+
+    channel capability unset #channel -games
+    channel capability remove #channel foo games
+
+
+And to forbid only the ``dice`` command of the ``Games`` plugin instead of the
+entire plugin, you would use the same commands, but with ``-games.dice`` and
+``games.dice`` instead of ``-games`` and ``games``.
+
+
 Final Word
 ----------