Add a "PolicyKit Overview" section to the docs

5 files changed, 98 insertions, 1 deletions

diff --git a/docs/extensiondir.xml.in b/docs/extensiondir.xml.in
new file mode 100644
index 0000000..c12c3d6
--- /dev/null
+++ b/docs/extensiondir.xml.in
@@ -0,0 +1 @@
+@libdir@/polkit-1/backends
diff --git a/docs/man/polkitd-1.xml b/docs/man/polkitd-1.xml
index 5a6fdee..3080f74 100644
--- a/docs/man/polkitd-1.xml
+++ b/docs/man/polkitd-1.xml
@@ -3,7 +3,7 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY version SYSTEM "../version.xml">
 ]>
-<refentry id="devkit-disks-daemon.8">
+<refentry id="polkitd-1.8">
   <refentryinfo>
     <title>polkitd-1</title>
     <date>May 2009</date>
diff --git a/docs/polkit/Makefile.am b/docs/polkit/Makefile.am
index 4e182af..ebfb06f 100644
--- a/docs/polkit/Makefile.am
+++ b/docs/polkit/Makefile.am
@@ -48,6 +48,8 @@ MKTMPL_OPTIONS=
 
 # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
 content_files =  			    								\
+	overview.xml											\
+	../extensiondir.xml			    							\
 	../version.xml			    								\
 	../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml			\
 	../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthorityManager.xml		\
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
new file mode 100644
index 0000000..f3ebca9
--- /dev/null
+++ b/docs/polkit/overview.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+<!ENTITY extensiondir SYSTEM "../extensiondir.xml">
+]>
+<part id="overview">
+  <title>PolicyKit Overview</title>
+  <chapter>
+    <title>Introduction</title>
+    <para>
+      PolicyKit provides an authorization API intended to be used by
+      privileged programs (<quote>MECHANISMS</quote>) offering service
+      to unprivileged programs (<quote>CLIENTS</quote>). See
+      <link linkend="PolicyKit-1.8">this page</link> for the system
+      architecture and big picture.
+    </para>
+  </chapter>
+
+  <chapter>
+    <title>Writing PolicyKit applications</title>
+    <para>
+      PolicyKit applications are privileged mechanisms using the
+      PolicyKit authority as a decider component. To do this, a
+      <emphasis>mechanism</emphasis> use either
+      the <link linkend="ref-api">GObject API</link>,
+      the <link linkend="ref-dbus-api">D-Bus API</link> or
+      the <link linkend="pkcheck.1">pkcheck</link> command to speak
+      to the PolicyKit Authority.
+    </para>
+    <para>
+      Note that <emphasis>clients</emphasis> never use the PolicyKit
+      API directly – it is intended solely for privileged
+      <emphasis>mechanisms</emphasis>. If a client needs to disable,
+      modify or remove UI elements to e.g. convey to the user that a
+      certain action cannot be carried out (because e.g. the user is
+      not authorized) or authentication is needed (by
+      e.g. displaying a padlock icon in the UI), the mechanism will
+      need to provide API for this.
+    </para>
+    <para>
+      As an example of code using the GObject API, see <xref linkend="cancel-example"/>.
+    </para>
+    <example id="cancel-example"><title>Querying the Authority</title>
+      <programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../src/examples/cancel.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
+    </example>
+  </chapter>
+
+  <chapter>
+    <title>Extending PolicyKit</title>
+    <para>
+      PolicyKit exports a number of extension points to
+      replace/customize behavior of the PolicyKit daemon. Note that
+      all extensions run with super user privileges in the same
+      process as the PolicyKit daemon.
+    </para>
+    <para>
+      The PolicyKit daemons loads extensions
+      from the <filename>&extensiondir;</filename> directory. See
+      the <link linkend="gio-Extension-Points">GIO Extension Point
+        documentation</link> for more information about the extension
+      system used by PolicyKit.
+    </para>
+    <para>
+      The following extension points are currently defined by
+      PolicyKit:
+    </para>
+
+    <formalpara>
+      <title>POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME</title>
+      <para>
+        Allows replacing the Authority – the entity responsible for
+        making authorization decisions. Implementations of this
+        extension point must be derived from the
+        PolkitBackendAuthority class. See
+        the <filename>src/nullbackend/</filename> directory in the
+        PolicyKit sources for an example.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title>POLKIT_BACKEND_ACTION_LOOKUP_EXTENSION_POINT_NAME</title>
+      <para>
+        Allows a mechanism to customize the contents of authentication
+        dialogs. Implementations of this extension point must
+        implement the #PolkitBackendActionLookup interface.
+      </para>
+    </formalpara>
+
+  </chapter>
+</part>
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 7283c98..fb2082b 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -2,6 +2,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY version SYSTEM "../version.xml">
+<!ENTITY extensiondir SYSTEM "../extensiondir.xml">
 ]>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
@@ -55,6 +56,8 @@
     </legalnotice>
   </bookinfo>
 
+  <xi:include href="overview.xml"/>
+
   <reference id="ref-dbus-api">
     <title>D-Bus API Reference</title>
     <xi:include href="../../src/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml"/>