2006-11-07 Havoc Pennington <hp@redhat.com>

	* doc/dbus-specification.xml, doc/dbus-faq.xml, README: various
	documentation updates. Bump faq/spec versions (not to 1.0; I don't
	think the spec will be "finished"/1.0 when we ship the 1.0 library).

3 files changed, 39 insertions, 14 deletions

diff --git a/doc/TODO b/doc/TODO
index ace86872..7b6e1191 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -8,6 +8,8 @@ Important for 1.0
 
  - the spec should say "the protocol will not be changed incompatibly after Month DD, YYYY"
 
+ - the README documents the configure flags, should check this for being in sync with reality
+
 Important for 1.0 GLib Bindings
 ===
 
diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml
index 47072e9e..07324049 100644
--- a/doc/dbus-faq.xml
+++ b/doc/dbus-faq.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus FAQ</title>
-    <releaseinfo>Version 0.1</releaseinfo>
-    <date>22 January 2005</date>
+    <releaseinfo>Version 0.2</releaseinfo>
+    <date>07 November 2006</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -38,10 +38,14 @@
       </question>
       <answer>
         <para>
-          This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>. In
+          This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink> or
+          the introduction to the <ulink url="dbus-specification.html">specification</ulink>. In
           short, it is a system consisting of 1) a wire protocol for exposing a
           typical object-oriented language/framework to other applications; and
           2) a bus daemon that allows applications to find and monitor one another.
+          Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level 
+          structure (lifecycle tracking, service activation, security policy) provided by two bus daemons,
+          one systemwide and one per-user-session.
         </para>
       </answer>
     </qandaentry>
@@ -54,12 +58,13 @@
       </question>
       <answer>
         <para>
-          D-Bus has not yet reached 1.0. The <ulink url="README">README</ulink>
-          file has a discussion of the API/ABI stability guarantees before and
-          after 1.0. In short, there are no guarantees before 1.0, and stability
-          of both protocol and reference library will be maintained after 1.0.
-          As of January 2005 we don't expect major protocol or API changes prior
-          to the 1.0 release, but anything is possible.
+          The low-level library "libdbus" and the protocol specification are considered 
+          ABI stable. The <ulink url="README">README</ulink>
+          file has a discussion of the API/ABI stability guarantees.
+          Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each 
+          have their own release schedules and degree of maturity, not linked to 
+          the low-level library and bus daemon release. Check the project page for
+          the binding you're considering to understand that project's policies.
         </para>
       </answer>
     </qandaentry>
@@ -144,6 +149,13 @@
           are normally launched according to the bus name they will 
           have.
         </para>
+        <para>
+          People often misuse the word "service" for any 
+          bus name, but this tends to be ambiguous and confusing so is discouraged.
+          In the D-Bus docs we try to use "service" only when talking about 
+          programs the bus knows how to launch, i.e. a service always has a 
+          .service file.
+        </para>
       </answer>
     </qandaentry>
 
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 1e4ac4f5..e1b02f38 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>
-    <releaseinfo>Version 0.11</releaseinfo>
-    <date>6 February 2005</date>
+    <releaseinfo>Version 0.12</releaseinfo>
+    <date>7 November 2006</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -114,9 +114,20 @@
       </itemizedlist>
       D-Bus is not intended to be a generic IPC system for any possible 
       application, and intentionally omits many features found in other 
-      IPC systems for this reason. D-Bus may turn out to be useful 
-      in unanticipated applications, but future versions of this 
-      spec and the reference implementation probably will not 
+      IPC systems for this reason.
+    </para>
+
+    <para>
+      At the same time, the bus daemons offer a number of features not found in
+      other IPC systems, such as single-owner "bus names" (similar to X
+      selections), on-demand startup of services, and security policies.
+      In many ways, these features are the primary motivation for developing 
+      D-Bus; other systems would have sufficed if IPC were the only goal.
+    </para>
+
+    <para>
+      D-Bus may turn out to be useful in unanticipated applications, but future
+      versions of this spec and the reference implementation probably will not
       incorporate features that interfere with the core use cases.
     </para>