docs: mention the audience for authorization rules

Signed-off-by: David Zeuthen <zeuthen@gmail.com>

2 files changed, 23 insertions, 0 deletions

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index 1aebfc9..aaac4f4 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -503,6 +503,19 @@ System Context         |                        |
       (in other words, the JavaScript interpreter used may change in future versions of polkit).
     </para>
 
+    <para>
+      Authorization rules are intended for two specific audiences
+    </para>
+    <itemizedlist mark='opencircle' spacing='compact'>
+      <listitem><para>System Administrators</para></listitem>
+      <listitem><para>Special-purpose Operating Systems / Environments</para></listitem>
+    </itemizedlist>
+    <para>
+      and those audiences only. In particular, applications,
+      mechanisms and general-purpose operating systems must never
+      include any authorization rules.
+    </para>
+
     <refsect2 id="polkit-rules-polkit">
       <title>The <type>Polkit</type> type</title>
 
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index 45cdba0..8d22570 100644
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -196,6 +196,16 @@
           </para>
         </listitem>
 
+        <listitem>
+          <para>
+            <emphasis role='bold'>DON'T</emphasis> include any
+            authorization rules with your application as this is only
+            intended for administrators and special-purpose operating
+            systems / environments. See <xref linkend="polkit-rules"/>
+            for more information.
+          </para>
+        </listitem>
+
       </itemizedlist>
     </simplesect>