wire formats in docs clarified

2 files changed, 44 insertions, 18 deletions

diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
index c92824e..ffbe9bd 100644
--- a/doc/zmq_pgm.txt
+++ b/doc/zmq_pgm.txt
@@ -81,20 +81,42 @@ order specifying either the offset of the first message 'frame' in the datagram
 or containing the value 0xFFFF if the datagram contains solely an intermediate
 part of a larger message.
 
-A single PGM datagram as used by 0MQ can thus be defined by the following ABNF
-grammar:
+The payload of a single PGM datagram as used by 0MQ can thus be defined by the
+following ABNF grammar:
 
 ....
-datagram               = message / intermediate
-message                = (frame-offset *data 1*frame)    <1>
-intermediate           = (escape 1*data)
-frame-offset           = 2OCTET
-escape                 = %xFF %xFF
-data                   = 1*OCTET
+datagram               = (offset data)
+offset                 = 2OCTET
+data                   = *OCTET
 ....
 
-<1> 'frame' as defined in linkzmq:zmq_tcp[7].
+As already explained above, the data from consecutive datagrams are interpreted
+as a bytestream that's parsed according to the grammar described in
+linkzmq:zmq_tcp[7].
 
+Each packet thus looks like this:
+ 
+----
++-----------+------------+------------------+----------------------+
+| IP header | PGM header | offset (16 bits) |        data          |
++-----------+------------+------------------+----------------------+
+----
+ 
+Following example shows how messages are arranged in subsequent packets:
+ 
+----
++---------------+--------+-----------+-----------------------------+
+| PGM/IPheaders | 0x0000 | message 1 |      message 2 (part 1)     |
++---------------+--------+-----------+-----------------------------+
+ 
++---------------+--------+-----------------------------------------+
+| PGM/IPheaders | 0xFFFF |            message 2 (part 2)           |
++---------------+--------+-----------------------------------------+
+ 
++---------------+--------+--------------------------+-----------+
+| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
++---------------+--------+--------------------------+-----------+
+----
 
 EXAMPLE
 -------
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
index c6eba21..3f21352 100644
--- a/doc/zmq_tcp.txt
+++ b/doc/zmq_tcp.txt
@@ -54,32 +54,35 @@ A 'peer address' may be specified by either of the following:
 WIRE FORMAT
 -----------
 0MQ messages are transmitted over TCP in frames consisting of the message
-length followed by the message data.  The size of the message data MUST
-correspond to the message length. A single 'frame' can be defined by the
+length followed by flags byte and the message data. The length MUST correspond
+to the length of the remaining part of the frame. 
+
+. A single 'frame' can be defined by the
 following ABNF grammar:
 
 ....
-    frame           = (message-length message-data)
-    message-length  = OCTET / (escape 8OCTET)
+    frame           = (length flags data)
+    length          = OCTET / (escape 8OCTET)
+    flags           = OCTET
     escape          = %xFF
-    message-data    = *OCTET
+    data            = *OCTET
 ....
 
 
-For messages of 0 to 254 octets in length, the message length is represented by
+For messages of 0 to 253 octets in length, the message length is represented by
 a single octet:
 
 ....
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| Message size  |                Message body               ... |
+| Message size  |     Flags     |       Message body        ... |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Message body ...
 +-+-+-+-+-+-+- ...
 ....
 
-For messages of 255 or more octets in length, the message length is represented
+For messages of 254 or more octets in length, the message length is represented
 by a single octet with the value `255` followed by the message length
 represented as a 64-bit unsigned integer in network byte order:
 
@@ -91,12 +94,13 @@ represented as a 64-bit unsigned integer in network byte order:
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                        Message size                       ... |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-|  Message size |                Message body               ... |
+|  Message size |     Flags     |        Message body       ... |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |  Message body ...
 +-+-+-+-+-+-+-+ ...
 ....
 
+The flags field is reserved and MUST be set to 0.
 
 EXAMPLES
 --------