[telepathy-doc/master] Obtaining connections with MC5

[Davyd Madeley]

---
 docs/book/C/accounts.xml   |   11 +++++--
 docs/book/C/connection.xml |   63 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 68 insertions(+), 6 deletions(-)

diff --git a/docs/book/C/accounts.xml b/docs/book/C/accounts.xml
index 7c31762..6bd0e99 100644
--- a/docs/book/C/accounts.xml
+++ b/docs/book/C/accounts.xml
@@ -9,9 +9,8 @@
   <note>
    <para>
     The <interfacename>AccountManager</interfacename> and
-    <interfacename>Account</interfacename> interfaces are not implemented
-    in <application>Mission Control 5</application> exactly as they are
-    specified in the Telepathy API specification.
+    <interfacename>Account</interfacename> interfaces are implemented
+    in <application>Mission Control 5</application>.
    </para>
 
    <para>
@@ -70,6 +69,12 @@
     properties of an <interfacename>Account</interfacename> object.
    </para>
 
+   <para>
+    Obtaining connections and managing the online/offline status of accounts
+    is documented in
+    <xref linkend="sect.connection.obtaining.account-manager"/>.
+   </para>
+
    <table id="table.accounts.account-properties">
     <title>Account Properties</title>
     <tgroup cols="4">
diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
index f51035b..a561645 100644
--- a/docs/book/C/connection.xml
+++ b/docs/book/C/connection.xml
@@ -198,9 +198,8 @@
      <note>
       <para>
        The <interfacename>AccountManager</interfacename> and
-       <interfacename>Account</interfacename> interfaces are not implemented
-       in <application>Mission Control 5</application> exactly as they are
-       specified in the Telepathy API specification.
+       <interfacename>Account</interfacename> interfaces are implemented
+       in <application>Mission Control 5</application>.
       </para>
       <para>
        <application>Mission Control 4</application> implements a completely
@@ -216,6 +215,64 @@
       connections for configured accounts which can be retrieved as a
       property from each <interfacename>Account</interfacename> object.
      </para>
+
+     <para>
+      Connections are created and managed by the Account Manager for valid,
+      online accounts.
+      The Account Manager is available via the well known D-Bus name
+      <literal>org.freedesktop.Telepathy.AccountManager</literal> and object
+      path <literal>/org/freedesktop/Telepathy/AccountManager</literal>.
+     </para>
+
+     <para>
+      Valid, connectable (or connected) accounts are available via the
+      <property>ValidAccounts</property> property of the Account Manager.
+      This property contains a list of D-Bus object paths the Account
+      Manager exports. An account's current presence can be read via the
+      <property>CurrentPresence</property> property.
+     </para>
+
+     <para>
+      To bring an account online, set
+      <property>RequestedPresence</property> to an online state (e.g.
+      <type>Connection_Presence_Type_Available</type> (the account must also
+      be <property>Enabled</property>).
+      Equally, to take an account offline, set the
+      <property>RequestedPresence</property> property to
+      <type>Connection_Presence_Type_Offline</type>.
+     </para>
+
+     <tip>
+      <title>Automatically Onlining Accounts</title>
+      <para>
+       Mission Control will automatically bring online any
+       <property>Enabled</property> account when a channel is requested for
+       that account via the Channel Dispatcher. This is done by setting
+       <property>RequestedPresence</property> to the value set in
+       <property>AutomaticPresence</property>.
+      </para>
+      <para>
+       See ...
+      </para>
+     </tip>
+
+     <para>
+      The <property>Connection</property> property gives the object path for
+      the connection associated with the account. A value of
+      <literal>/</literal> indicates that no connection has been created.
+     </para>
+
+     <para>
+      The well-known bus name of the connection can be determined from the
+      object path by removing the leading forward-slash and replacing
+      the remaining slashes with periods (for example,
+      <literal>/org/freedesktop/Telepathy/Connection/gabble/jabber/bob_40example_2ecom_2ftelepathy</literal>
+      becomes
+      <literal>org.freedesktop.Telepathy.Connection.gabble.jabber.bob_40example_2ecom_2ftelepathy</literal>).
+      Note that doing this conversion is not normally required, as most
+      Telepathy bindings are able to do it for you (e.g.
+      <function>tp_connection_new</function>).
+     </para>
     </sect2>
 
     <sect2 id="sect.connection.obtaining.connection-manager">
-- 
1.5.6.5