[Telepathy-commits] [telepathy-doc/master] Content

[Davyd Madeley]

---
 docs/book/C/accounts.xml   |    2 +-
 docs/book/C/basics.xml     |   32 +++++++++++++---------
 docs/book/C/connection.xml |   64 +++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 83 insertions(+), 15 deletions(-)

diff --git a/docs/book/C/accounts.xml b/docs/book/C/accounts.xml
index 19e8e64..4f31dce 100644
--- a/docs/book/C/accounts.xml
+++ b/docs/book/C/accounts.xml
@@ -203,7 +203,7 @@
       <row>
        <entry>Valid</entry><entry>Boolean</entry>
        <entry>
-        Whether this account is considered by the Account Banager to be
+        Whether this account is considered by the Account Manager to be
 	complete and usable.
        </entry>
        <entry>True</entry>
diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
index a9a3364..8982528 100644
--- a/docs/book/C/basics.xml
+++ b/docs/book/C/basics.xml
@@ -41,13 +41,27 @@
    <!-- FIXME: some of this information is too detailed for this glossary
                and should be moved further down the manual -->
    <sect2>
+    <title>Mission Control</title>
+    <para>
+     Mission Control is responsible for the management of messaging
+     accounts, the creation of connections (if an account is considered
+     online) and setting the user's requested presence for that account.
+    </para>
+    <para>
+     This manual is specifically concerned with Mission Control 5. There are
+     earlier versions of Mission Control, but they are extremely different
+     to the version documented here.
+    </para>
+   </sect2>
+
+   <sect2>
     <title>Connection Manager</title>
     <para>
-     Connection managers are simply factories for connections; new
-     connections are created using the
-     <methodname>RequestConnection</methodname> method on the
-     <interfacename>org.freedesktop.Telepathy.ConnectionManager</interfacename>
-     interface.
+     Connection managers are simply factories for connections.
+     In general, there is little need for a client to interact much with
+     the <interfacename>ConnectionManager</interfacename> interface. Most of
+     the work in obtaining and managing connections should be done via
+     Mission Control.
     </para>
     <para>
      The term
@@ -61,14 +75,6 @@
      interface (the common D-Bus introspection and properties interfaces
      excepted).
     </para>
-    <para>
-     Connection managers are typically started via D-Bus service activation,
-     when a Telepathy application would like to create a new connection.
-    </para>
-    <para>
-     Connection managers are discussed in more detail in
-     <xref linkend="chapter-connection-manager"/>.
-    </para>
    </sect2>
 
    <sect2>
diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
index 6c2bef3..6a08d28 100644
--- a/docs/book/C/connection.xml
+++ b/docs/book/C/connection.xml
@@ -129,6 +129,68 @@
     </para>
    </listitem>
   </itemizedlist>
+
+  <sect1 id="sect.connection-manager">
+    <title>Connection Manager</title>
+  
+    <para>
+     Support for the various communication protocols is provided by several
+     <literal>Connection Managers</literal>. For instance, the
+     <literal>telepathy-gabble</literal> Connection Manager provides support
+     for the <acronym>XMPP</acronym> protocol, also known as
+     <literal>Jabber</literal>.
+    </para>
+    
+    <para>
+     There is no central &app; D-Bus service in Telepathy. Instead there are
+     several connection manager services, activated on demand. Each
+     connection manager implements the Telepathy specification, allowing a
+     Telepathy client to utilise any messaging protocol.
+    </para>
+  
+    <para>
+     All Telepathy Connection Managers have <literal>bus name</literal>s that
+     begin with &quot;org.freedesktop.Telepathy.ConnectionManager&quot;.
+     You can discover all available connection managers by calling the D-Bus
+     <methodname>ListActivatableNames</methodname> method and then comparing
+     the names with that prefix.
+    </para>
+    
+    <para>
+     A Connection Manager may implement more than one protocol (e.g.
+     <application>telepathy-haze</application> is a connection manager using
+     <application>libpurple</application> and thus provides many protocols).
+     You may then discover what protocols are provided by each connection
+     manager by calling the ConnectionManagers's
+     <methodname>ListProtocols</methodname> method.
+    </para>
+
+    <para>
+     In general, there is little need for a client to interact much with
+     the <interfacename>ConnectionManager</interfacename> interface. Most of
+     the work in obtaining and managing connections should be done via
+     Mission Control.
+    </para>
+
+    <sect2>
+     <title>telepathy-glib</title>
+     <para>
+      telepathy-glib provides the
+      <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers</function></ulink> function
+      to list the available connection managers.
+     </para>
+ 
+     <para>
+      telepathy-glib's
+      <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink>
+      object automatically calls <methodname>ListProtocols</methodname> upon
+      creation and emits the <literal>got-info</literal>
+      signal when it has returned. You can examine the
+      TpConnectionManager::protocols struct field in your signal handler.
+     </para>
+    </sect2>
+    
+  </sect1>
   
   <sect1>
     <title>Obtaining a Connection</title>
@@ -172,7 +234,7 @@
      <para>
       To setup your own connection to the remote server (e.g. your Jabber
       IM account) you need to call <methodname>RequestConnection</methodname>
-      on the appropriate <link xref="chapter-connection-manager">Connection
+      on the appropriate <link xref="sect.connection-manager">Connection
       Manager</link> (e.g. gabble), providing a map of connection details.
       Assuming the connection succeeds this method will return the
       <literal>bus name</literal> and <literal>object path</literal>
-- 
1.5.6.5