[Telepathy-commits] [telepathy-doc/master] Unbadger ids
Davyd Madeley
davyd at madeley.id.au
Wed Mar 18 00:03:46 PDT 2009
---
docs/book/C/accounts.xml | 6 +-
docs/book/C/basics.xml | 204 +++++++++++++++++++++++++-----------
docs/book/C/channel-dispatcher.xml | 4 +-
docs/book/C/channel.xml | 51 +++++-----
docs/book/C/connection.xml | 38 ++++----
docs/book/C/contactinfo.xml | 2 +-
docs/book/C/introduction.xml | 2 +-
docs/book/C/telepathy.xml | 8 +-
docs/book/C/tubes.xml | 2 +-
9 files changed, 200 insertions(+), 117 deletions(-)
diff --git a/docs/book/C/accounts.xml b/docs/book/C/accounts.xml
index 4f31dce..3b8b9bd 100644
--- a/docs/book/C/accounts.xml
+++ b/docs/book/C/accounts.xml
@@ -16,7 +16,7 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-accounts">
+<chapter id="chapter.accounts">
<title>Accounts and AccountManager</title>
<note>
<para>
@@ -57,7 +57,7 @@
<title>Accounts</title>
<para>
Account objects store off of the information that is used for making a
- <link linkend="chapter-connection">Connection</link> to a remote
+ <link linkend="chapter.connection">Connection</link> to a remote
service. Mission Control can be used to establish connections for valid
accounts.
</para>
@@ -156,7 +156,7 @@
<entry>ConnectAutomatically</entry><entry>Boolean</entry>
<entry>
Whether or not the Account Manager should automatically establish a
- <link xref="chapter-connection">Connection</link> for this account.
+ <link linkend="chapter.connection">Connection</link> for this account.
</entry>
<entry>True</entry>
</row>
diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
index ccd7b3c..1095322 100644
--- a/docs/book/C/basics.xml
+++ b/docs/book/C/basics.xml
@@ -16,7 +16,7 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-basics">
+<chapter id="chapter.basics">
<title>Basics</title>
<para>This chapter introduces some basic techniques and concepts that you must understand to use Telepathy confidently. You should read through this chapter before proceeding, but you will probably want to refer back here again later.</para>
@@ -32,7 +32,7 @@
<para>
The design of Telepathy is heavily influenced by D-Bus, so much of its
terminology is shared in common with D-Bus. For those unfamiliar with
- D-Bus, a quick primer is presented in <xref linkend="sec-basics-dbus"/>.
+ D-Bus, a quick primer is presented in <xref linkend="sect.basics.dbus"/>.
For more indepth information, consult A MANUAL THAT PROBABLY HASN'T BEEN
WRITTEN YET.<!-- FIXME -->
</para>
@@ -40,7 +40,7 @@
<!-- FIXME: what order do these go in? -->
<!-- FIXME: some of this information is too detailed for this glossary
and should be moved further down the manual -->
- <sect2>
+ <sect2 id="sect.basics.terminology.mission-control">
<title>Mission Control</title>
<para>
Mission Control is responsible for the management of messaging
@@ -54,7 +54,7 @@
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.basics.terminology.connection-manager">
<title>Connection Manager</title>
<para>
Connection managers are simply factories for connections.
@@ -77,7 +77,7 @@
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.basics.terminology.connection">
<title>Connection</title>
<para>
Connections represent active protocol sessions. A connection has a set
@@ -105,11 +105,11 @@
<para>
Setting up and using connections is documented in
- <xref linkend="chapter-connection"/>.
+ <xref linkend="chapter.connection"/>.
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.basics.terminology.channel">
<title>Channel</title>
<para>
A <interfacename>Channel</interfacename> is used by Telepathy to
@@ -122,11 +122,11 @@
</para>
<para>
A complete explanation of channels is presented in
- <xref linkend="chapter-channel"/>.
+ <xref linkend="chapter.channel"/>.
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.basics.terminology.handle">
<title>Handle</title>
<para>
Handles are used to represent various kinds of protocol resources
@@ -136,18 +136,18 @@
</para>
<para>
- The use of handles is documented in <xref linkend="sec-basics-handles"/>.
+ The use of handles is documented in <xref linkend="sect.basics.handles"/>.
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.basics.terminology.interface">
<title>Interface</title>
<para>
</para>
</sect2>
</sect1>
- <sect1 id="sec-basics-dbus">
+ <sect1 id="sect.basics.dbus">
<title>Using D-Bus</title>
<para>
Telepathy is a <indexterm><primary>D-Bus</primary></indexterm>D-Bus API.
@@ -168,7 +168,7 @@
<para>
Most of the Telepathy examples in this book will use a
- <link linkend="sec-basics-language-bindings">language binding</link>
+ <link linkend="sect.basics.language-bindings">language binding</link>
instead of using D-Bus directly. However, an understanding of D-Bus is
very helpful when learning Telepathy.
</para>
@@ -475,7 +475,7 @@
</para>
</tip>
- <sect2 id="sect.basics-dbus-glib.types">
+ <sect2 id="sect.basics.dbus.types">
<title>D-Bus Type Signatures</title>
<para>
@@ -488,7 +488,7 @@
<!-- FIXME: should write more here -->
</sect2>
- <sect2 id="sec-basics-dbus-glib">
+ <sect2 id="sect.basics.dbus.glib">
<title>Using D-Bus from C, with glib</title>
<!-- FIXME: something about dbus-glib
@@ -523,7 +523,7 @@
<title>Acquiring a Proxy Object</title>
</example>
- <sect3 id="sect-basics-dbus-glib-methods">
+ <sect3 id="sect.basics.dbus.glib.methods">
<title>Calling Methods</title>
<para>
Method calls in D-Bus should <emphasis>always</emphasis> be made
@@ -569,7 +569,7 @@
</example>
</sect3>
- <sect3 id="sect-basics-dbus-glib-properties">
+ <sect3 id="sect.basics.dbus.glib.properties">
<title>Using Properties</title>
<para>
D-Bus properties are available via an additional
@@ -593,7 +593,7 @@
</example>
</sect3>
- <sect3 id="sect-basics-dbus-glib-signals">
+ <sect3 id="sect.basics.dbus.glib.signals">
<title>Handling Signals</title>
<para>
Handlers for D-Bus signals may be connected with the function
@@ -620,7 +620,7 @@
</sect2>
- <sect2 id="sec-basics-dbus-python">
+ <sect2 id="sect.basics.dbus.python">
<title>Using D-Bus from Python</title>
<para>
@@ -659,7 +659,7 @@
<title>Acquiring a Proxy Object</title>
</example>
- <sect3 id="sect-basics-dbus-python-methods">
+ <sect3 id="sect.basics.dbus.python.methods">
<title>Calling Methods</title>
<para>
<xref linkend="dbus-python-call-method"/>
@@ -687,7 +687,7 @@
</example>
</sect3>
- <sect3 id="sect-basics-dbus-python-properties">
+ <sect3 id="sect.basics.dbus.python.properties">
<title>Using Properties</title>
<para>
D-Bus properties are available via an additional
@@ -709,7 +709,7 @@
</example>
</sect3>
- <sect3 id="sect-basics-dbus-python-signals">
+ <sect3 id="sect.basics.dbus.python.signals">
<title>Handling Signals</title>
<para>
D-Bus signal handlers may be specified in Python with the proxy object's
@@ -731,14 +731,29 @@
</sect2>
</sect1>
- <sect1 id="sec-basics-language-bindings">
+ <sect1 id="sect.basics.language-bindings">
<title>Language Bindings</title>
- <para>As mentioned in the <link linkend="sec-basics-dbus">Using D-Bus</link> section, many programming languages have their own generic ways of using D-Bus APIs. In addition, there are some Telepathy-specific APIs to make the use of Telepathy even easier. For instance, <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink> provides an API that is familiar to users of Glib and GTK+, using the GObject system and related conventions.</para>
- <para>Likewise, the <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink> project provides a more Qt-like API for Telepathy and <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> does the same for Python.</para> <!-- TODO: Link to Telepathy-Qt4 when it is ready. -->
+ <para>
+ As mentioned in <xref linkend="sect.basics.dbus"/>, many programming
+ languages have their own generic ways of using D-Bus APIs. In addition,
+ there are some Telepathy-specific APIs to make the use of Telepathy
+ easier. For instance,
+ <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink>
+ provides an API that aims to be more familiar to users of Glib and GTK+.
+ Likewise,
+ <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink>
+ provides a Qt API for Telepathy and
+ <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> for Python.
+ </para>
- <para>Remember that, like raw use of D-Bus from these programming languages, the Telepathy language bindings only create <literal>proxies</literal> to the D-Bus objects, providing a way to use their API. The actual objects are instantiated in the service's process.</para>
+ <para>
+ Remember that, like raw use of D-Bus from these programming languages,
+ the Telepathy language bindings only create <literal>proxies</literal>
+ to the D-Bus objects, providing a way to use their API. The actual
+ objects are instantiated in the service's process.
+ </para>
- <sect2 id="sec-basics-language-bindings-telepathy-glib">
+ <sect2 id="sect.basics.language-bindings.telepathy-glib">
<title>telepathy-glib</title>
<para>The C examples in this book will use telepathy-glib, which provides a GObject-based API for the Telepathy framework.</para>
@@ -746,9 +761,21 @@
<para>The reference documentation only makes sense in terms of the Telepathy D-Bus Specification.</para>
-->
- <sect3 id="sec-basics-language-bindings-telepathy-glib-async">
+ <sect3 id="sect.basics.language-bindings.telepathy-glib.async">
<title>Asynchronous Calls</title>
- <para>For each Telepathy D-Bus method, telepathy-glib generally provides both a "run" and a "call" function. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-call-connect">tp_cli_connection_call_connect()</ulink>. The "run" function is synchronous, blocking until the D-Bus service has returned the value, whereas the "call" function is asynchronous, immediately returning and later providing the result to a callback function.</para>
+ <para>
+ For each Telepathy D-Bus method, telepathy-glib generally provides
+ both a "run" and a "call" function.
+ For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect"><methodname>tp_cli_connection_run_connect</methodname></ulink>
+ and <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-call-connect"><methodname>tp_cli_connection_call_connect</methodname></ulink>.
+ The "run" functions are synchronous, and blocks until the
+ D-Bus service has returned the value. They have been deprecated and
+ should never be used in Telepathy programs (see
+ <xref linkend="warning.dbus.sync"/>). Instead use the "call"
+ functions, which are asynchronous; immediately returning and later
+ providing the result to a callback function.
+ </para>
+
<para>
However, the use of the "run" functions is strongly
discouraged (see <xref linkend="warning.dbus.sync"/>), so all
@@ -758,67 +785,122 @@
</para>
</sect3>
- <sect3 id="sec-basics-language-bindings-telepathy-glib-generated">
+ <sect3 id="sect.basics.language-bindings.telepathy-glib.generated">
<title>Generated Functions</title>
- <para>telepathy-glib provides both hand-coded and generated API. The generated functions have these prefixes:</para>
+ <para>
+ telepathy-glib provides both hand-coded and generated API. The
+ generated functions have these prefixes:
+ </para>
<variablelist>
<varlistentry>
<term>tp_cli_</term>
- <listitem>
- <para>These functions are useful for client applications. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_call_connect()</ulink>.</para>
- </listitem>
+ <listitem><para>
+ These functions are used for client applications. For instance,
+ <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect"><methodname>tp_cli_connection_call_connect</methodname></ulink>.
+ </para></listitem>
</varlistentry>
<varlistentry>
<term>tp_svc_</term>
- <listitem>
- <para>These functions are useful for service implementations, such as connection managers. For instance, <ulink url="&url_telepathy_glib_base;svc-connection.html#tp-svc-connection-implement-connect">tp_svc_connection_implement_connect()</ulink>.</para>
- </listitem>
+ <listitem><para>
+ These functions are used for service implementations, such as
+ connection managers. For instance,
+ <ulink url="&url_telepathy_glib_base;svc-connection.html#tp-svc-connection-implement-connect"><methodname>tp_svc_connection_implement_connect</methodname></ulink>.
+ </para></listitem>
</varlistentry>
</variablelist>
- <para>The generated functions make simple direct calls to the D-Bus methods, without any additional logic and without using more appropriate types. For instance, they use unsigned integers for parameters because D-Bus does not have a concept of enumerations. However, the Telepathy D-Bus Specification does describe enumerations of possible values for these parameters, so the hand-written functions do use enums. Likewise, raw D-Bus methods can only identify object instances in terms of a <literal>bus name</literal> and <literal>object path</literal> combination, but telepathy-glib can directly provide a GObject instance that is a proxy for a D-Bus object without exposing those intermediate details.</para>
- <para>Hand-coded functions have a simple <literal>tp_</literal> prefix and should be preferred whenever they exist. The generated functions exist only because hand-written functions have not yet been implemented for all Telepathy D-Bus methods.</para>
- <para>In addition to more pleasant syntax, some hand-written objects contain a large amount of useful logic which can simplify application code. For instance, <ulink url="&url_telepathy_glib_base;contact.html"><classname>TpContact</classname></ulink> uses GObject signals. <!-- TODO: Finish this sentence. --></para>
+ <!-- FIXME: huh? -->
+ <para>
+ The generated functions make direct calls to the D-Bus methods,
+ without any additional logic and without using more appropriate
+ types. For instance, they use unsigned integers for parameters
+ because D-Bus does not have a concept of enumerations.
+ However, the Telepathy D-Bus Specification does describe enumerations
+ of possible values for these parameters, so the hand-written
+ functions do use enums. Likewise, raw D-Bus methods can only
+ identify object instances in terms of a <literal>bus name</literal>
+ and <literal>object path</literal> combination, but telepathy-glib
+ can directly provide a GObject instance that is a proxy for a
+ D-Bus object without exposing those intermediate details.
+ </para>
+
+ <para>
+ Hand-coded functions have a simple <literal>tp_</literal> prefix and
+ should be preferred whenever they exist. The generated functions
+ exist only because hand-written functions have not yet been
+ implemented for all Telepathy D-Bus methods.
+ </para>
+
+ <para>
+ In addition to more pleasant syntax, some hand-written objects
+ contain a large amount of useful logic which can simplify
+ application code. For instance,
+ <ulink url="&url_telepathy_glib_base;contact.html"><classname>TpContact</classname></ulink>
+ uses GObject signals. <!-- TODO: Finish this sentence. -->
+ </para>
</sect3>
- <sect3>
+ <sect3 id="sect.basics.language-bindings.telepathy-glib.readiness">
<title>Instantiation and Readiness</title>
<!-- TODO: Keep any eye on http://bugs.freedesktop.org/show_bug.cgi?id=13422 -->
- <para>Some of the hand-coded objects, such as <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> and <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpChannel</classname></ulink>, call additional D-Bus methods to acquire necessary information. When they have received this information they are then "ready", meaning that other hand-written functions can then be called. This concept of "readiness" does not exist in the raw D-Bus API because it describes the status of the hand-written behaviour. For instance, you should call <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-call-when-ready">tp_connection_call_when_ready()</ulink> after instantiating a TpConnection, or <ulink url="&url_telepathy_glib_base;channel.html#tp-channel-call-when-ready">tp_channel_call_when_ready()</ulink> after instantiating a TpChannel.</para>
+ <para>
+ Some of the hand-coded objects, such as
+ <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> and
+ <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpChannel</classname></ulink>,
+ call additional D-Bus methods to acquire necessary information. When they have received this information they are then "ready",
+ meaning that other hand-written functions can then be called.
+ This concept of "readiness" does not exist in the raw
+ D-Bus API because it describes the status of the hand-written
+ behaviour. For instance, you should call
+ <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-call-when-ready"><methodname>tp_connection_call_when_ready</methodname></ulink>
+ after instantiating a <classname>TpConnection</classname>, or
+ <ulink url="&url_telepathy_glib_base;channel.html#tp-channel-call-when-ready"><methodname>tp_channel_call_when_ready</methodname></ulink>
+ after instantiating a <classname>TpChannel</classname>.
+ </para>
</sect3>
- <sect3>
+ <sect3 id="sect.basics.language-bindings.telepathy-glib.linking">
<title>Headers and Linking</title>
- <para>To use the telepathy-glib API, you must include the headers for the library, and link to its shared library. The necessary compiler and linker commands can be obtained from the <literal>pkg-config</literal> utiltity like so:</para>
<para>
-<programlisting>
+ To use the telepathy-glib API, you must include the headers for the
+ library, and link to its shared library. The necessary compiler
+ and linker commands can be obtained from the
+ <application>pkg-config</application> utiltity like so:
+ </para>
+
+ <informalexample><programlisting>
pkg-config telepathy-glib --cflags
-pkg-config telepathy-glib --libs
-</programlisting>
- </para>
- <para>However, if you are using the "autotools" (automake, autoconf, etc) build system, you will find it more convenient to use the <function>PKG_CHECK_MODULES</function> macro in your <literal>configure.ac</literal> file.
+pkg-config telepathy-glib --libs</programlisting>
+ </informalexample>
+
+ <para>
+ However, if you are using the "autotools"
+ (automake, autoconf, etc) build system, you will find it more
+ convenient to use the <function>PKG_CHECK_MODULES</function> macro
+ in your <filename>configure.ac</filename> file.
</para>
- <para>
-<programlisting>
+
+ <informalexample><programlisting>
PKG_CHECK_MODULES(EXAMPLE, telepathy-glib)
AC_SUBST(EXAMPLE_CFLAGS)
-AC_SUBST(EXAMPLE_LIBS)
-</programlisting>
- </para>
- <para>You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.</para>
+AC_SUBST(EXAMPLE_LIBS)</programlisting>
+ </informalexample>
+
+ <para>
+ You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.
+ </para>
</sect3>
</sect2>
</sect1>
- <!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
- <sect1 id="sec-basics-optional-interfaces">
+ <sect1 id="sect.basics.optional-interfaces">
<title>Optional Interfaces</title>
<para>
@@ -895,7 +977,7 @@ AC_SUBST(EXAMPLE_LIBS)
<!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
</sect1>
- <sect1 id="sec-basics-handles">
+ <sect1 id="sect.basics.handles">
<title>Handles</title>
<para>
@@ -942,7 +1024,7 @@ AC_SUBST(EXAMPLE_LIBS)
the anonymous handle, and also has special meaning.
</para>
- <sect2>
+ <sect2 id="sect.basics.handle.lifecycle">
<title>Handle Lifecycle</title>
<para>
@@ -1011,7 +1093,7 @@ AC_SUBST(EXAMPLE_LIBS)
</sect2>
- <sect2>
+ <sect2 id="sect.basics.handles.telepathy-glib">
<title>Handles in telepathy-glib</title>
<para>
@@ -1039,7 +1121,7 @@ AC_SUBST(EXAMPLE_LIBS)
</sect1>
- <sect1 id="sec-basics-api-conventions">
+ <sect1 id="sect.basics.api-conventions">
<title>API conventions</title>
<para>
diff --git a/docs/book/C/channel-dispatcher.xml b/docs/book/C/channel-dispatcher.xml
index e5a8ed5..349c361 100644
--- a/docs/book/C/channel-dispatcher.xml
+++ b/docs/book/C/channel-dispatcher.xml
@@ -16,8 +16,8 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-channel-dispatcher">
- <title>TODO: ChannelDispatcher</title>
+<chapter id="chapter.channel-dispatcher">
+ <title>ChannelDispatcher</title>
<para>TODO:
Notes:
- This is in mission control.
diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index 78f7946..50799ae 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -16,11 +16,11 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-channel">
+<chapter id="chapter.channel">
<title>Channels</title>
<para>
Each <interfacename>Connection</interfacename> provides
- <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>s,
+ <interfacename>Channel</interfacename>s,
which allow the local application to exchange data with the remote server,
for instance to retrieve a list of contacts in a chat room, or to send a
message to a contact.
@@ -43,7 +43,7 @@
<varlistentry>
<term>
<indexterm><primary>ContactList</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink>
+ <interfacename>ContactList</interfacename>
</term>
<listitem>
<para>
@@ -52,7 +52,7 @@
contacts to whom you publish your presence information.
</para>
<para>
- See <xref linkend="sect-channel-contactlist"/>.
+ See <xref linkend="sect.channel.contactlist"/>.
</para>
</listitem>
</varlistentry>
@@ -60,20 +60,23 @@
<varlistentry>
<term>
<indexterm><primary>RoomList</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.RoomList"><interfacename>RoomList</interfacename></ulink>
+ <interfacename>RoomList</interfacename>
</term>
<listitem>
<para>
A channel type for listing named channels (e.g. chatrooms)
available on the server.
</para>
+ <para>
+ See <xref linkend="sect.channel.roomlist"/>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary>Text</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.Text"><interfacename>Text</interfacename></ulink>
+ <interfacename>Text</interfacename>
</term>
<listitem>
<para>
@@ -81,7 +84,7 @@
messages.
</para>
<para>
- See <xref linkend="sect-channel-text"/>.
+ See <xref linkend="sect.channel.text"/>.
</para>
</listitem>
</varlistentry>
@@ -89,7 +92,7 @@
<varlistentry>
<term>
<indexterm><primary>StreamedMedia</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.StreamedMedia"><interfacename>StreamedMedia</interfacename></ulink>
+ <interfacename>StreamedMedia</interfacename>
</term>
<listitem>
<para>
@@ -102,7 +105,7 @@
<!--varlistentry>
<term>
<indexterm><primary>Tubes</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.Tubes"><interfacename>Tubes</interfacename></ulink>
+ <interfacename>Tubes</interfacename>
</term>
<listitem>
<para>
@@ -113,8 +116,7 @@
<varlistentry>
<term>
<indexterm><primary>FileTransfer</primary></indexterm>
- <ulink
- url="&url_spec_base;Channel.Type.FileTransfer"><interfacename>FileTransfer</interfacename></ulink>
+ <interfacename>FileTransfer</interfacename>
</term>
<listitem>
<para>
@@ -125,13 +127,12 @@
</variablelist>
- <sect1 id="sec-channel-requesting">
+ <sect1 id="sect.channel.requesting">
<title>Requesting Channels</title>
<para>
Channels are requested from a <classname>Connection</classname> object
- using the <ulink url="&url_spec_base;Connection.Interface.Requests"><interfacename>Requests</interfacename></ulink>
- interface.
+ using the <interfacename>Requests</interfacename> interface.
</para>
<para>
@@ -271,7 +272,7 @@
</example>
</warning>
- <sect2 id="sec.channel.requesting.python">
+ <sect2 id="sect.channel.requesting.python">
<title>telepathy-python</title>
<para>
@@ -308,7 +309,7 @@
</sect1>
- <sect1 id="sect-channel-contactlist">
+ <sect1 id="sect.channel.contactlist">
<title>Contact Lists</title>
<indexterm><primary>ContactList</primary></indexterm>
@@ -322,7 +323,7 @@
<para>
Like individual remote contacts themselves, lists of remote contacts
is referred to by numeric
- <link linkend="sec-basics-handles">handle</link> of type
+ <link linkend="sect.basics.handles">handle</link> of type
<type>Handle_Type_List</type> (for
<link linkend="sect.channel.contactlist.server-defined">server defined
lists</link>) or
@@ -335,7 +336,7 @@
<para>
To request a contact list, three properties must be provided to
<methodname>EnsureChannel</methodname>
- (see <xref linkend="sec-channel-requesting"/>): the channel type
+ (see <xref linkend="sect.channel.requesting"/>): the channel type
(org.freedesktop.Telepathy.Channel.Type.ContactList), the target handle
type (either <type>Handle_Type_List</type> or
<type>Handle_Type_Group</type>) and
@@ -597,7 +598,7 @@
</sect1>
- <sect1 id="sect-channel-text">
+ <sect1 id="sect.channel.text">
<title>Text Channels</title>
<indexterm><primary>Text</primary></indexterm>
@@ -611,7 +612,7 @@
<para>
Channels for text chat are usually <emphasis>ensured</emphasis>
- (see <xref linkend="sec-channel-requesting"/>) with the channel type
+ (see <xref linkend="sect.channel.requesting"/>) with the channel type
<type>Channel_Type_Text</type>. For one-to-one chats, the target handle
is a contact (<type>Handle_Type_Contact</type>). For named chatrooms
(e.g. Jabber multi-user-chats, IRC chatrooms) the target handle is a
@@ -720,7 +721,7 @@
</para>
</note>
- <sect2 id="sec.channel.text.password">
+ <sect2 id="sect.channel.text.password">
<title>Private Channels</title>
<para>
@@ -743,7 +744,7 @@
</sect2>
- <sect2 id="sec.channel.text.rich">
+ <sect2 id="sect.channel.text.rich">
<title>Rich Text Interface</title>
<note>
@@ -998,7 +999,7 @@
<para>
Set up a D-Bus proxy for the channel, like you would for any other
- channel (see <xref linkend="sec-channel-requesting"/>). Check to
+ channel (see <xref linkend="sect.channel.requesting"/>). Check to
ensure that the <interfacename>Messages</interfacename> interface
is available.
</para>
@@ -1077,7 +1078,7 @@
<para>
<interfacename>RoomList</interfacename>s channels are stateful, so
they should be <emphasis>created</emphasis> (see
- <xref linkend="sec-channel-requesting"/>). On protocols that support
+ <xref linkend="sect.channel.requesting"/>). On protocols that support
multiple conference servers (e.g. XMPP), the <property>Server</property>
property can be included in the request.
</para>
@@ -1184,7 +1185,7 @@
<entry>Boolean</entry>
<entry>
If a password is required for this channel.
- See <xref linkend="sec.channel.text.password"/>.
+ See <xref linkend="sect.channel.text.password"/>.
</entry>
</row>
<row>
diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
index e225adb..f40b104 100644
--- a/docs/book/C/connection.xml
+++ b/docs/book/C/connection.xml
@@ -16,14 +16,14 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-connection">
+<chapter id="chapter.connection">
<title>Connections</title>
<para>
A <interfacename>Connection</interfacename> object in Telepathy
represents an active (or activatable) protocol session. Connections are
created by the appropriate
- <link xref="chapter-connection-manager">Connection Manager</link>.
+ <link xref="sect.connection.connection-manager">Connection Manager</link>.
</para>
<para>
@@ -56,9 +56,9 @@
<para><interfacename>Requests</interfacename></para>
<para>
The <interfacename>Requests</interfacename> interface is used to
- obtain <link linkend="chapter-channel">channels</link>, which are how
+ obtain <link linkend="chapter.channel">channels</link>, which are how
data is exchanged in Telepathy. Its use is documented in
- <xref linkend="sec-channel-requesting"/>.
+ <xref linkend="sect.channel.requesting"/>.
</para>
</listitem>
<listitem>
@@ -131,7 +131,7 @@
</listitem>
</itemizedlist>
- <sect1 id="sect.connection-manager">
+ <sect1 id="sect.connection.connection-manager">
<title>Connection Managers</title>
<para>
@@ -173,7 +173,7 @@
Mission Control.
</para>
- <sect2>
+ <sect2 id="sect.connection.connection-manager.glib">
<title>telepathy-glib</title>
<para>
telepathy-glib provides the
@@ -196,7 +196,7 @@
<sect1 id="sect.connection.obtaining">
<title>Obtaining a Connection</title>
- <sect2>
+ <sect2 id="sect.connection.obtaining.account-manager">
<title>From the Account Manager</title>
<note>
@@ -216,13 +216,13 @@
In general, Telepathy clients will want to share the same set of
already-configured accounts rather than managing their own accounts
and setting up their own connections. The
- <link linkend="chapter-accounts">Account Manager</link> manages
+ <link linkend="chapter.accounts">Account Manager</link> manages
connections for configured accounts which can be retrieved as a
property from each <interfacename>Account</interfacename> object.
</para>
</sect2>
- <sect2>
+ <sect2 id="sect.connection.obtaining.connection-manager">
<title>From a Connection Manager</title>
<para>
There might be times when you are using Telepathy without an
@@ -235,9 +235,9 @@
<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="sect.connection-manager">Connection
- Manager</link> (e.g. gabble), providing a map of connection details.
- Assuming the connection succeeds this method will return the
+ on the appropriate <link xref="sect.connection.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>
of a newly created Telepathy <interfacename>Connection</interfacename>
object.
@@ -366,9 +366,9 @@
<!--
<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>
- <note><para>See the <link linkend="sec-basics-language-bindings-telepathy-glib-generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
+ <note><para>See the <link linkend="sect.basics.language-bindings.telepathy-glib.generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
- <para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts .</para>
+ <para>See the <link linkend="chapter.channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts.</para>
-->
<example id="example.connection.establish-connection">
@@ -403,10 +403,10 @@
</para>
</warning>
- <sect2>
+ <sect2 id="sect.connection.presence.user">
<title>Setting the User's Presence</title>
- <sect3>
+ <sect3 id="sect.connection.presence.user.account-manager">
<title>Via the Account Manager</title>
<note>
<para>
@@ -424,7 +424,7 @@
<para>
If this Connection was obtained from the
- <link linkend="chapter-accounts">Account Manager</link>, then the
+ <link linkend="chapter.accounts">Account Manager</link>, then the
user's presence can be set on the appropriate
<link linkend="sect.accounts.accounts">Account</link> object using
the <property>RequestedPresence</property> property of the
@@ -433,7 +433,7 @@
</para>
</sect3>
- <sect3>
+ <sect3 id="sect.connection.presence.connection">
<title>Via the Connection</title>
<para>
The user sets their own presence via the
@@ -453,7 +453,7 @@
</sect3>
</sect2>
- <sect2>
+ <sect2 id="sect.connection.presence.contacts">
<title>Retrieving Contacts' Presence</title>
<para>
diff --git a/docs/book/C/contactinfo.xml b/docs/book/C/contactinfo.xml
index 0e41001..07dfe71 100644
--- a/docs/book/C/contactinfo.xml
+++ b/docs/book/C/contactinfo.xml
@@ -139,7 +139,7 @@
</informaltable>
</example>
- <sect2>
+ <sect2 id="sect.contactinfo.contacts.receiving-updates">
<title>Receiving Updates</title>
<para>
While <interfacename>Contacts</interfacename>/
diff --git a/docs/book/C/introduction.xml b/docs/book/C/introduction.xml
index 29019b8..62f5b1c 100644
--- a/docs/book/C/introduction.xml
+++ b/docs/book/C/introduction.xml
@@ -26,7 +26,7 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-introduction">
+<chapter id="chapter.introduction">
<title>Introduction</title>
<para>
Telepathy is a flexible, modular communications framework that enables
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 98ffefc..77dbf59 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -98,14 +98,14 @@ code snippets which will also be in dbus-glib, but python versions could be
added in future.
-->
-<chapter id="chapter-chat-client">
+<chapter id="chapter.chat-client">
<title>Implementing a Chat Client</title>
<para>TODO:
- Text Channels (Messages Interface?)
</para>
</chapter>
-<chapter id="chapter-voip-client">
+<chapter id="chapter.voip-client">
<title>Creating a VoIP Client</title>
<para>TODO:
(Streaming Audio/Video)
@@ -113,13 +113,13 @@ added in future.
</para>
</chapter>
-<chapter id="chapter-transferring-files">
+<chapter id="chapter.transferring-files">
<title>Transferring Files</title>
<para>TODO
</para>
</chapter>
-<chapter id="chapter-networked-application">
+<chapter id="chapter.networked-application">
<title>Making an application networked</title> <!-- TODO: Rename the title. -->
<para>TODO:
- For instance, turn-based Tic-Tac-Toe.
diff --git a/docs/book/C/tubes.xml b/docs/book/C/tubes.xml
index f568609..413070e 100644
--- a/docs/book/C/tubes.xml
+++ b/docs/book/C/tubes.xml
@@ -26,7 +26,7 @@
<!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
]>
-<chapter id="chapter-tubes">
+<chapter id="chapter.tubes">
<title>Tubes</title>
<para>TODO:
- Helps me to implement an ad-hoc protocol or data-exchange structure above
--
1.5.6.5
More information about the telepathy-commits
mailing list