Clarify pkexec(1) variables

Signed-off-by: David Zeuthen <davidz@redhat.com>

2 files changed, 25 insertions, 11 deletions

diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index d84aa1d..236f9f1 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -82,8 +82,8 @@
   <refsect1 id="pkexec-security-notes"><title>SECURITY NOTES</title>
     <para>
       Executing a program as another user is a privileged
-      operation. By default the required authorization (See
-      <xref linkend="pkexec-required-authz"/>) requires administrator
+      operation. By default the action to check for (see
+      <xref linkend="pkexec-action"/>) requires administrator
       authentication. In addition, the authentication dialog presented
       to the user will display the full path to the program to be
       executed so the user is aware of what will happen.
@@ -125,7 +125,7 @@
     </para>
   </refsect1>
 
-  <refsect1 id="pkexec-required-authz"><title>REQUIRED AUTHORIZATIONS</title>
+  <refsect1 id="pkexec-action"><title>ACTION AND AUTHORIZATIONS</title>
     <para>
       By default, the
       <emphasis>org.freedesktop.policykit.exec</emphasis> action is
@@ -134,10 +134,13 @@
       annotation on an action with the value set to the full path of
       the program. In addition to specifying the program, the
       authentication message, description, icon and defaults can be
-      specified. The strings <literal>$(user)</literal>,
-      <literal>$(program)</literal> and
-      <literal>$(command_line)</literal> in the message will be
-      expanded, see <xref linkend="pkexec-variables"/>.
+      specified.
+    </para>
+    <para>
+      Note that authentication messages may reference variables (see
+      <xref linkend="pkexec-variables"/>), for example
+      <literal>$(user)</literal> will be expanded to the value of the
+      <literal>user</literal> variable.
     </para>
   </refsect1>
 
@@ -178,7 +181,7 @@
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term><emphasis>user_full</emphasis></term>
+        <term><emphasis>user.gecos</emphasis></term>
         <listitem>
           <para>
             The full name of the user to execute the program as.
@@ -186,6 +189,17 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><emphasis>user.display</emphasis></term>
+        <listitem>
+          <para>
+            A representation of the user to execute the program as
+            that is suitable for display in an authentication dialog.
+            Is typically set to a combination of the user name and the
+            full name.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
   </refsect1>
diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index 9718541..bd39299 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -486,7 +486,7 @@ System Context         |                        |
       <literal>polkit</literal> object (of type <type>Polkit</type>).
     </para>
 
-    <refsect2 id="polkit-rules-actions">
+    <refsect2 id="polkit-rules-polkit">
       <title>The <type>Polkit</type> type</title>
 
       <para>
@@ -616,10 +616,10 @@ polkit.addRule(function(action, subject) {
 });
 ]]></programlisting>
       <para>
-        will produce the following when the user runs 'pkexec bash -i' from a shelll:
+        will produce the following when the user runs 'pkexec -u bateman bash -i' from a shell:
       </para>
       <programlisting><![CDATA[
-May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user_full='root (root)' user='root']
+May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user='bateman' user.gecos='Patrick Bateman' user.display='Patrick Bateman (bateman)']
 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:4: subject=[Subject pid=1352 user='davidz' groups=davidz,wheel, seat='seat0' session='1' local=true active=true]
 ]]></programlisting>