Proposed documentation patch: adding field names to header table

[David A. Wheeler]

Attached is a minor patch against the D-BUS specification document.

I think the D-BUS specification's table that describes
the header needs another column that gives each header field a name.
It can be confusing to read or discuss a spec where
the various parts aren't named. Code that manipulates the
header has to give names to each part, and that's easier to read
if there are conventional names.  So, I tweaked the table
to give names to the various header fields.

Hopefully, you'll like and apply it. I think it makes the text
a little easier to read, and it's definitely easier to discuss
the header when each part has a conventional name.

--- David A. Wheeler
-------------- next part --------------
--- dbus-specification.xml.orig	2005-01-20 22:44:10.000000000 -0500
+++ dbus-specification.xml	2005-01-22 17:58:34.000000000 -0500
@@ -627,74 +627,86 @@
       </para>
 
       <para>
-        These values have the following meanings:
+        The heading's format is as follows:
         <informaltable>
-          <tgroup cols="2">
+          <tgroup cols="3">
             <thead>
               <row>
-                <entry>Value</entry>
+                <entry>Field Name</entry>
+                <entry>Type</entry>
                 <entry>Description</entry>
               </row>
             </thead>
             <tbody>
               <row>
-                <entry>1st <literal>BYTE</literal></entry>
-                <entry>Endianness flag; ASCII 'l' for little-endian 
+                <entry>byte_order</entry>
+                <entry>(1st) <literal>BYTE</literal></entry>
+                <entry>Endianness marker; ASCII 'l' for little-endian 
                   or ASCII 'B' for big-endian. Both header and body are 
-                in this endianness.</entry>
+                  in this endianness.</entry>
               </row>
               <row>
-                <entry>2nd <literal>BYTE</literal></entry>
-                <entry><firstterm>Message type</firstterm>. Unknown types MUST be ignored. 
+                <entry>message_type</entry>
+                <entry>(2nd) <literal>BYTE</literal></entry>
+                <entry>The <firstterm>Message type</firstterm>, e.g., 1 is
+                  a method call. Unknown types MUST be ignored. 
                   Currently-defined types are described below.
                 </entry>
               </row>
               <row>
-                <entry>3rd <literal>BYTE</literal></entry>
-                <entry>Bitwise OR of flags. Unknown flags
+                <entry>flags</entry>
+                <entry>(3rd) <literal>BYTE</literal></entry>
+                <entry>Bitwise OR of message flags. Unknown flags
                   MUST be ignored. Currently-defined flags are described below.
                 </entry>
               </row>
               <row>
-                <entry>4th <literal>BYTE</literal></entry>
+                <entry>major_version</entry>
+                <entry>(4th) <literal>BYTE</literal></entry>
                 <entry>Major protocol version of the sending application.  If
                 the major protocol version of the receiving application does not
                 match, the applications will not be able to communicate and the
                 D-BUS connection MUST be disconnected. The major protocol
                 version for this version of the specification is 0.
-                  FIXME this field is stupid and pointless to put in 
-                  every message.
                 </entry>
               </row>
               <row>
-                <entry>1st <literal>UINT32</literal></entry>
+                <entry>body_len</entry>
+                <entry>(1st) <literal>UINT32</literal></entry>
                 <entry>Length in bytes of the message body, starting 
                   from the end of the header. The header ends after 
                   its alignment padding to an 8-boundary.
                 </entry>
               </row>
               <row>
-                <entry>2nd <literal>UINT32</literal></entry>
+                <entry>serial</entry>
+                <entry>(2nd) <literal>UINT32</literal></entry>
                 <entry>The serial of this message, used as a cookie 
                   by the sender to identify the reply corresponding
                   to this request.
                 </entry>
               </row>      
               <row>
+                <entry>header_fields</entry>
                 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
                 <entry>An array of zero or more <firstterm>header
                   fields</firstterm> where the byte is the field code, and the
                   variant is the field value. The message type determines 
-                  which fields are required.
+                  which fields are required.  Since this is an array,
+                  the first 4 bytes of this value provide the length (in bytes)
+                  of this array.
                 </entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
+        Note that the length (in bytes) of a message is 16 bytes
+        (the fixed header size) + the value of the length of "header_fields" +
+        body_len.
       </para>
       <para>
         <firstterm>Message types</firstterm> that can appear in the second byte
-        of the header are:
+        of the header (the message_type value) are:
         <informaltable>
           <tgroup cols="3">
             <thead>
@@ -737,7 +749,8 @@
         </informaltable>
       </para>
       <para>
-        Flags that can appear in the third byte of the header:
+        Flags that can appear in the value of flags
+        (the third byte of the header) are:
         <informaltable>
           <tgroup cols="3">
             <thead>