docs: mention the audience for authorization rules

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

diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index 1aebfc95fa7a8ad48644a1496bc4b60c6333057f..aaac4f401dd319e0af86dc92badc3726c4df516e 100644 (file)
--- 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 45cdba0356f3a62f9e795ee6d4cceb929dcd0dfd..8d22570b0e3e8806ce2a517f55760a3c160e129c 100644 (file)
--- 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>