From bde9d0a76db0f7eee2d5a12a9ee2052782554018 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Mon, 13 Jun 2011 15:24:21 +0100
Subject: [PATCH 7/8] Promote the marshalling format to a top-level section

---
 doc/dbus-specification.xml |   40 +++++++++++++++++++++++++++++++++-------
 1 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 75d7d78..715a4f6 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -805,9 +805,21 @@
       </para>
 
     </sect2>
+  </sect1>
+
+  <sect1 id="message-protocol-marshaling">
+    <title>Marshaling (Wire Format)</title>
+
+    <para>
+      D-Bus defines a marshalling format for its type system, which is
+      used in D-Bus messages. This is not the only possible marshalling
+      format for the type system: for instance, GVariant (part of GLib)
+      re-uses the D-Bus type system but implements an alternative marshalling
+      format.
+    </para>
 
-    <sect2 id="message-protocol-marshaling">
-      <title>Marshaling (Wire Format)</title>
+    <sect2>
+      <title>Byte order and alignment</title>
 
       <para>
         Given a type signature, a block of bytes can be converted into typed
@@ -816,11 +828,11 @@
       </para>
 
       <para>
-        A block of bytes has an associated byte order. The byte order 
-        has to be discovered in some way; for D-Bus messages, the 
-        byte order is part of the message header as described in 
-        <xref linkend="message-protocol-messages"/>. For now, assume 
-        that the byte order is known to be either little endian or big 
+        A block of bytes has an associated byte order. The byte order
+        has to be discovered in some way; for D-Bus messages, the
+        byte order is part of the message header as described in
+        <xref linkend="message-protocol-messages"/>. For now, assume
+        that the byte order is known to be either little endian or big
           endian.
       </para>
 
@@ -834,6 +846,10 @@
         not be left uninitialized (it can't contain garbage), and more padding
         than required must not be used.
       </para>
+    </sect2>
+
+    <sect2>
+      <title>Marshalling basic types</title>
 
       <para>
         To marshal and unmarshal fixed types, you simply read one value
@@ -861,6 +877,16 @@
         byte. As a result, alignment padding is never required before a
         SIGNATURE.
       </para>
+    </sect2>
+
+    <sect2>
+      <title>Marshalling containers</title>
+
+      <para>... to be written ...</para>
+    </sect2>
+
+    <sect2>
+      <title>Summary of D-Bus marshalling</title>
 
       <para>
         Given all this, the types are marshaled on the wire as follows:
-- 
1.7.5.4