[dhcwg] draft-ietf-dhc-dhcpv4-vendor-message-00 WGLC comments

[Alfred Hönes <[e-mail]>]

I have studied  draft-ietf-dhc-dhcpv4-vendor-message-00
and have a couple of recommendations for editorial improvements
of the draft.


(1)  Section 1, 1st para -- improved wording

For enhanced readability, I suggest to swap words:

              vvvvvvvvvvvvvvvvvv
|  The DHCPv4 [RFC2131] protocol specifies a mechanism for the
   assignment of addresses and configuration information to nodes. [...]
---           vvvvvvvvvvvvvvvvvv
|  The DHCPv4 protocol [RFC2131] specifies a mechanism for the
   assignment of addresses and configuration information to nodes. [...]


(2)  Section 3 -- document structure

This draft is structured along his DHCPv6 companion draft;
but the message structure in DHCPv4 is significantly different
than in DHCPv6.

Therefore, and to easily allow making future references to parts
of the document more precise, I suggest to split Section 3 into
three new sections:

 3.  Vendor-specific Message
 4.  Vendor Message Option
 4.1   Vendor Message Sub-Options

The new Section 3 should comprise the first 4 paragraphs of the
current Section 3.

Section 4 would start with:

|4.  Vendor Message Option
|
   The format of the Vendor Message Option is shown below:
   ...

[ Alternatively, the 4th para of Section 3 could be moved into this
  section as well -- maybe with slight rewording. ]

This section should extend down to the field explanations for the
Vendor Message Option, and include the last two paragraphs of the
old Section 3.  More details for this section are discussed below.

[ Alternatively, the last paragraph could go to the end of the new
  Section 3. ]

The remainder of the old Section 3 would go into the new subsection 4.1:

|4.1. Vendor Message Sub-Options
|

More details for this section are discussed below as well.

Note: All subsequent section numbers need to be bumped accordingly.


(3)  [old] Section 3 -- terminological clarification

The field designation "vendor-option-data" in the Vendor Message Option
seems to be chosen in an unfortunate manner.
I suggest to precisely indicate what the subsequent text specifies:
a series of regularly structured *sub*-options.
It seems to be important for clarity (within this document and future
documents making reference of it) to precisely distinguish the terms
"option" and "suboption".

Hence the field should better be designated as "vendor-msg-subopts"
[name chosen to be no longer than the old name].

This change needs to be applied to the diagram and the explanation of
"option-len", and the final field explanation should be made more
precise:

      vendor-option-data  Vendor specific data (of length option-len
                          minus 5 octets). This is optional.
---
|     vendor-msg-subopts  A sequence of zero or more sub-options
|                         (of length option-len minus 5 octets).

I suggest to split the subsequent paragraph and leave its first part
in the new Section 4, while moving the second part into Section 4.1.
There, I suggest to rename the data field using a more regular
naming pattern.

|  The vendor-msg-subopts field MUST be encoded as a sequence of code/
|  length/value fields in a format identical to the DHCP options field,
|  as specified in Section 4.1 below.
|
   << last two paragraphs of old Section 3 >>
|
|4.1. Vendor Message Sub-Options
|
|  The Vendor Message Suboptions placed into the Vendor Message Option
|  are TLV structured like regular DHCP options.
|
|  The suboption codes are defined by the vendor identified in the
|  enterprise-number field of the Vendor Message Option and are not
|  managed by IANA.  Suboption codes 0 and 255 have no pre-defined
|  interpretation or format.
|
|  Each of the encapsulated suboptions is formatted as follows:

                          1 1 1 1 1 1
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |  subopt-code  |  subopt-len   |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    /          subopt-data          /
     ~            ...                ~
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

|    subopt-code        The code for the encapsulated suboption.

     subopt-len         An unsigned integer giving the length of the
|                       subopt-data field in this encapsulated
|                       suboption in octets.

|    subopt-data        Data area for the encapsulated suboption.


[ Note: In all field explanations above, the word "encapsulated"
        might well be deleted; it should suffice to have it in the
        intial text of the new section -- the designation
        "sub"[option] has taken over its role. ]


Kind regards,
  Alfred Hönes.

-- 

+------------------------+--------------------------------------------+
| TR-Sys Alfred Hoenes   |  Alfred Hoenes   Dipl.-Math., Dipl.-Phys.  |
| Gerlinger Strasse 12   |  Phone: [phone], Fax: -18         |
| D-71254  Ditzingen     |  E-Mail:  [e-mail]                     |
+------------------------+--------------------------------------------+