Organise Connection interfaces by purpose.

Connection interfaces fall into a bunch of pretty orthogonal categories:

• Now-mandatory interfaces like Requests;
• Contact lists;
• Interfaces for getting contact attributes and stuff about contacts in
  general;
• Interfaces for manipulating the connection itself.

1 files changed, 60 insertions, 24 deletions

diff --git a/spec/all.xml b/spec/all.xml
index 3c1edd0f..7a72364c 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -40,36 +40,72 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
  <tp:section name="Connection Object">
   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
    <p>
-    Connections represent active protocol sessions.
+    Connections represent active protocol sessions. There are a number of core
+    interfaces which all connections should implement, and a number of optional
+    interfaces which provide various functionality related to contacts and to
+    the connection itself.
    </p>
   </tp:docstring>
   <xi:include href="Connection.xml"/>
   <xi:include href="Connection_Future.xml"/>
-  <xi:include href="Connection_Interface_Addressing.xml"/>
-  <xi:include href="Connection_Interface_Aliasing.xml"/>
-  <xi:include href="Connection_Interface_Anonymity.xml"/>
-  <xi:include href="Connection_Interface_Avatars.xml"/>
-  <xi:include href="Connection_Interface_Balance.xml"/>
-  <xi:include href="Connection_Interface_Capabilities.xml"/>
-  <xi:include href="Connection_Interface_Cellular.xml"/>
-  <xi:include href="Connection_Interface_Client_Types.xml"/>
-  <xi:include href="Connection_Interface_Communication_Policy.xml"/>
-  <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
-  <xi:include href="Connection_Interface_Contact_Groups.xml"/>
-  <xi:include href="Connection_Interface_Contact_Info.xml"/>
-  <xi:include href="Connection_Interface_Contact_List.xml"/>
   <xi:include href="Connection_Interface_Contacts.xml"/>
-  <xi:include href="Connection_Interface_Forwarding.xml"/>
-  <xi:include href="Connection_Interface_Keepalive.xml"/>
-  <xi:include href="Connection_Interface_Location.xml"/>
-  <xi:include href="Connection_Interface_Mail_Notification.xml"/>
-  <xi:include href="Connection_Interface_Power_Saving.xml"/>
-  <xi:include href="Connection_Interface_Presence.xml"/>
-  <xi:include href="Connection_Interface_Renaming.xml"/>
-  <xi:include href="Connection_Interface_Resources.xml"/>
   <xi:include href="Connection_Interface_Requests.xml"/>
-  <xi:include href="Connection_Interface_Service_Point.xml"/>
-  <xi:include href="Connection_Interface_Simple_Presence.xml"/>
+
+  <tp:section name="Contact list interfaces">
+   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+    <p>
+     On protocols that support contact lists, these interface expose the user's
+     contact lists, along with presence subscription information and contact
+     list groups (if supported).
+    </p>
+   </tp:docstring>
+
+   <xi:include href="Connection_Interface_Contact_List.xml"/>
+   <xi:include href="Connection_Interface_Contact_Groups.xml"/>
+  </tp:section>
+
+  <tp:section name="Contact metadata interfaces">
+   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+    <p>
+     These optional Connection interfaces expose metadata about contacts on
+     this connection—from their current presence through to the type of client
+     they're connected with—and allow the local user to publish such metadata
+     back to their contacts.
+    </p>
+   </tp:docstring>
+
+   <xi:include href="Connection_Interface_Aliasing.xml"/>
+   <xi:include href="Connection_Interface_Avatars.xml"/>
+   <xi:include href="Connection_Interface_Capabilities.xml"/>
+   <xi:include href="Connection_Interface_Client_Types.xml"/>
+   <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
+   <xi:include href="Connection_Interface_Contact_Info.xml"/>
+   <xi:include href="Connection_Interface_Location.xml"/>
+   <xi:include href="Connection_Interface_Presence.xml"/>
+   <xi:include href="Connection_Interface_Renaming.xml"/>
+   <xi:include href="Connection_Interface_Resources.xml"/>
+   <xi:include href="Connection_Interface_Simple_Presence.xml"/>
+  </tp:section>
+
+  <tp:section name="Connection feature interfaces">
+   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+    <p>
+     These optional Connection interfaces expose protocol-specific features,
+     and allow configuring the running connection.
+    </p>
+   </tp:docstring>
+
+   <xi:include href="Connection_Interface_Addressing.xml"/>
+   <xi:include href="Connection_Interface_Anonymity.xml"/>
+   <xi:include href="Connection_Interface_Balance.xml"/>
+   <xi:include href="Connection_Interface_Cellular.xml"/>
+   <xi:include href="Connection_Interface_Communication_Policy.xml"/>
+   <xi:include href="Connection_Interface_Forwarding.xml"/>
+   <xi:include href="Connection_Interface_Keepalive.xml"/>
+   <xi:include href="Connection_Interface_Mail_Notification.xml"/>
+   <xi:include href="Connection_Interface_Power_Saving.xml"/>
+   <xi:include href="Connection_Interface_Service_Point.xml"/>
+  </tp:section>
  </tp:section>
 
  <xi:include href="Channel_Bundle.xml"/>