[Telepathy-commits] [telepathy-doc/master] 2009-02-06 Murray Cumming <murrayc at openismus.com>

[Murray Cumming]

* docs/book/C/telepathy.xml: Basics: Handles: Add notes about
normalization and about 0 being invalid.
Connection: In the TODO comment about GetParameters(), mention some
text from Davyd so we remember to investigate the account parameter.
Channel: Add a TODO with some text from Davyd so we remember to
mention implictly-created channels that are signalled to us.
The text is from Davyd's proposed Glossary, which I don't want because
we already have the same stuff as chapter titles and because we have an
index.
---
 ChangeLog                 |   12 ++++++++++++
 docs/book/C/telepathy.xml |   15 ++++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8d47244..ceb3bf7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2009-02-06  Murray Cumming  <murrayc at openismus.com>
 
+	* docs/book/C/telepathy.xml: Basics: Handles: Add notes about 
+	normalization and about 0 being invalid.
+	Connection: In the TODO comment about GetParameters(), mention some 
+	text from Davyd so we remember to investigate the account parameter.
+	Channel: Add a TODO with some text from Davyd so we remember to 
+	mention implictly-created channels that are signalled to us.
+	The text is from Davyd's proposed Glossary, which I don't want because 
+	we already have the same stuff as chapter titles and because we have an 
+	index.
+
+2009-02-06  Murray Cumming  <murrayc at openismus.com>
+
 	* docs/book/C/telepathy.xml: Connection Manager: Duplicate (rephrasing) 
 	a little of the basics section for context. Direct people to the 
 	Connection chapter.
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 285a724..84ff39c 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -147,6 +147,11 @@ of the Telapathy specification.
     <para>The Telepathy D-Bus API does not have D-Bus objects to represent contacts, groups, or rooms. These are instead identified by numeric <literal>handles</literal>. This is for performance reasons, and because it is easier to compare numeric handles than to discover if two D-Bus proxy objects refer to the same object instance.</para>
     <para>These numeric handles are only unique within a Telepathy Connection. For instance, don't try to use a Connection's contact handle with a different Connection. The handles also only make sense when combined with a <ulink url="&url_spec;#type-Handle_Type">handle type</ulink>, telling the API whether it represents a contact, group, or list. In fact, two handles may be numerically identical but be for different types.</para>
 
+    <note><para>Some protocols might consider two identifiers, such as foobar at example.com and fooBAR at example.com, to be equivalent. In this case a single handle will represent them both, allowing the application to test for equality by simply comparing the handles' integer values. This is called &quot;Normalization&quot;.</para></note>
+    <!-- TODO: Normalization is often stated as a reason for having handles, but I don't see how normalization requires numeric values. It would work with objects too, if they weren't bad for performance reasons, which is reason enough for me. Is normalization really a reason? murrayc -->
+
+    <note><para>The handle 0 is never a valid handle, but that value may be used in the API to indicate a special case.</para></note>
+
     <sect2>
       <title>Hold and Release</title>
       <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to &quot;hold&quot; the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> has been called, so be careful not to call it while other code may be using the handle.</para>
@@ -434,7 +439,11 @@ AC_SUBST(EXAMPLE_LIBS)
     <title>Connecting</title>
     <para>To attempt a connection to the remote server, for instance to your Jabber IM account, you should call a <interfacename>ConnectionManager</interfacename>'s <ulink url="&url_spec_base;ConnectionManager.RequestConnection"><methodname>RequestConnection()</methodname></ulink> D-Bus method, providing the connection details. If the connection succeeds then this method returns the <literal>bus name</literal> and <literal>object path</literal> of a Telepathy <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> object.</para>
 
-    <!-- TODO: Mention (and ad an example (below) of) using ConnectionManager::GetParameters() to discover what parameters are needed by RequestConnection() for this ConnectionManager. -->
+    <!-- TODO: Mention (and ad an example (below) of) using ConnectionManager::GetParameters() to discover what parameters are needed by RequestConnection() for this ConnectionManager.
+
+    Text from Davyd's proposed Glossary (which I, murrayc, don't want because we already have the same stuff as chapter titles and because we have an index): Although the parameters used vary from protocol to protocol, some parameter names have a standard meaning. A notable example is the account parameter, used to specify a persistent identity, usually stored on a server. Some protocols, however, do not have accounts, in which case the account parameter will be absent. TODO: What protocols have this account parameter and what does it look/act like? murrayc.
+
+ -->
 
     <para>As of this writing, there is no hand-coded telepathy-glib function to request the connection and directly provide a <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> proxy. However, you may use the generated <ulink url="&url_telepathy_glib_base;connection-manager.html#tp_cli_connection_manager_call_request_connection"><function>tp_cli_connection_manager_call_request_connection()</function></ulink> function. In the callback, you can then use the provided <literal>bus name</literal> and <literal>object path</literal> to instantiate a TpConnection proxy object.</para>
 
@@ -548,8 +557,6 @@ AC_SUBST(EXAMPLE_LIBS)
 <chapter id="chapter-channel">
   <title>Channel</title>
 
-
-
   <para>TODO:
    Notes:
    - A connection has <ulink url="&url_spec_base;Channel">Channel</ulink>s.
@@ -560,6 +567,8 @@ AC_SUBST(EXAMPLE_LIBS)
      and a handle (contact, room, list or group) handle. 
   </para>
 
+  <!-- TODO: Mention channels that are not directly created by the application: Davyd's text: "in response to communication initiated by someone else, in which case their advent is heralded by the NewChannel signal." -->
+
   <para>TODO:
    Notes:
    - <ulink url="&url_spec_base;Connection.RequestChannel">Connection.RequestChannel</ulink>, <ulink url="&url_spec_base;Channel">Channel</ulink>
-- 
1.5.6.5