Subject: [Gen-art] review of draft-ietf-manet-nhdp-11.txt

From: Francis Dupont <[email-masked]>
Date: Wed, 17 Mar 2010 19:18:26 +0100

I have been selected as the General Area Review Team (Gen-ART)
reviewer for this draft (for background on Gen-ART, please see
http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html).

Please resolve these comments along with any other Last Call comments
you may receive.

Document: draft-ietf-manet-nhdp-11.txt
Reviewer: Francis Dupont
Review Date: 2010-03-16
IETF LC End Date: 2010-03-19
IESG Telechat date: unknown

Summary: Ready

Major issues: None

Minor issues: None

Nits/editorial comments:
 - Title: I note the title uses the term Neighborhood so should avoid
  too much confusion with IPv6 Neighbor Discovery Protocol (thanks!).

 - Abstract page 2: a 1-hop -> an 1-hop??

 - ToC page 23: Bases -> Base? (for consistency)

 - ToC page 4: Acknowledgements -> Acknowledgments

 - 2 page 7: Network Address  An address -> Network Address  - An address

 - 4.3.2 page 16 (and *many* other places): i.e. -> i.e.,

 - 9 page 27: may -> MAY and must -> MUST?

 - 9 page 27: the the -> the

 - 10 page 32: [RFC5444] -> [RFC5444])

 - 11 page 34: (another) a 1-hop -> an 1-hop

 - 12 page 36 (twice): the message need not have??

 - 12.1 page 37: my dict doesn't know "unverifiable"
 (note there is another occurrence of this word)

 - 12.3 page 39: IMHO '-' is not a good character to introduce a list item
  (I really prefer * or +)

 - 12.5 page 41, 12.6 pages 42 43, 13.2 page 45: same concern

 - 14.4 page 48: acknowledgement -> acknowledgement? (consistency)

 - 16 page 51: e.g. -> e.g.,

 - 17.1 page 54: ; -> . (at end of list items, for consistency)

 - 20 page 58: Acknowledgements -> Acknowledgments

 - B page 60: ALWAYS -> *always* (to avoid confusion with 2119 KEYWORDS)

 - C pages 64 and 65: packet details are unreadable (I prefer the name
  and value of fields)

 - C page 64: IMHO the (whole) packet length is wrong (45 = 0b101101,
  0b110001 = 49)

 - F.3 and all, pages 77 and all:
  the alternative ASCII art is very ugly:

                        _.---{3}
       {1}--------{2}--<_
                         '---{4}

  I suggest something like:

                       +-----{3}
       {1}--------{2}--+
                       +-----{4}

 - F.6 and all, page 78 and all:
  the circle is even worse! I suggest a box which is far easier
  (BTW in tis case circling -> boxing :-)

 - F.10 page 82: are the pairings 9+10 and 11+12 an artefact of
 the ASCII art or have they an intended meaning?

Regards

[email-masked]

---

From: Thomas Heide Clausen <[email-masked]>
Date: Tue, 23 Mar 2010 22:50:54 +0100

Dear Francis,

Merci beaucoup pour la relecture et les commentaires détaillés!

>  too much confusion with IPv6 Neighbor Discovery Protocol (thanks!).

Thank you. Avoiding such confusion was part of our reflections in  
naming, also for the abbreviation (NHDP).

> - Abstract page 2: a 1-hop -> an 1-hop??

I have asked around, and there seems to be opinions both ways. Not  
being a native English-speaker, I would suggest deferring to the RFC  
Editor on this matter?

> - ToC page 23: Bases -> Base? (for consistency)

Thank you for pointing out that inconsistency in the text.

Each router has one "Local Information Base" (etc. for the others),  
but has multiple "Interface Information Bases" (i.e., one per  
interface). We therefore think that it is better to retain "Interface  
Information Bases" as it is in 4.2.2 -- and have modified 7 to match  
this (also "Interface Information Bases").

We also rectified some text in section 7, which did not clearly call  
this out.

> - ToC page 4: Acknowledgements -> Acknowledgments

Done.

> - 2 page 7: Network Address  An address -> Network Address  - An  

Done.

> - 4.3.2 page 16 (and *many* other places): i.e. -> i.e.,

Done. Also did the same for e.g. -> e.g., -- thank you for reminding us.

> - 9 page 27: may -> MAY and must -> MUST?

Absolutely, Done.
Your comment made us pay attention to this, and we found another "may"  
that should be "MAY" in section 15. Thanks.

> - 9 page 27: the the -> the

Done.

> - 10 page 32: [RFC5444] -> [RFC5444])

Done.

> - 11 page 34: (another) a 1-hop -> an 1-hop

I have asked around, and there seems to be opinions both ways. Not  
being a native English-speaker, I would suggest deferring to the RFC  
Editor on this matter?

> - 12 page 36 (twice): the message need not have??

Changed to "the message does not need to have..." both places.

> (note there is another occurrence of this word)

Fair enough. I took it from the "Compact Oxford English Dictionary" (http://www.askoxford.com:80/concise_oed/unverifiable?view=uk 
), as meaning "unable to be verified".

> - 12.5 page 41, 12.6 pages 42 43, 13.2 page 45: same concern

(To both of the above)

These are artifacts of how xml2rfc constructs (nested) itemized lists.  
I'm afraid that I do not know how to change this behavior of xml2rfc,  
but I assume that the RFC Editor will make the final document conform  
to their style-guides also on this matter.

> - 14.4 page 48: acknowledgement -> acknowledgement? (consistency)

I assume you meant -> acknowledgment -- which we've fixed.

> - 16 page 51: e.g. -> e.g.,

Done.

> - 17.1 page 54: ; -> . (at end of list items, for consistency)

Done.

> - 20 page 58: Acknowledgements -> Acknowledgments

Done.

> - B page 60: ALWAYS -> *always* (to avoid confusion with 2119  

You are right. We also think it better to "not stress it" and simply  
write "always".

> - C pages 64 and 65: packet details are unreadable (I prefer the name

An explanatory paragraph is added to this appendix. As NHDP supports  
any combinations of header options and address encodings provided by  
RFC5444, there is no "single way" to illustrate how "all HELLO  
messages look". The explanatory paragraph (tries to) explain just  
that, hopefully clarifying this issue.

> - C page 64: IMHO the (whole) packet length is wrong (45 = 0b101101,

You are right, good catch! Thanks a bunch. Done.

>  the alternative ASCII art is very ugly:

;)

Good point, we have fixed those pictures.

>  (BTW in tis case circling -> boxing :-)

Done.

> the ASCII art or have they an intended meaning?

Artifact of the ASCII art -- should have been resolved with the  
general redrawing as per your suggestions.

Thank you again, Francis, for your careful review and your efforts in  
helping us improve the quality of this document!

Amities,

Thomas

---

From: Francis Dupont <[email-masked]>
Date: Tue, 23 Mar 2010 23:22:01 +0100

=> yes, it is a typical example of a point where the RFC Editor
can/should help!

   > (note there is another occurrence of this word)
   
=> note the question was not the meaning but where it belongs to
the English language (as it is in your dict it does).
   
   > - 12.3 page 39: IMHO '-' is not a good character to introduce a list =20=
   
   > item
   
   (To both of the above)

=> I already patched the character list in the xml2rfc.tcl script (:-)...
(if you'd like to know how to do)

Regards

PS: as you seem to like the gen-art review process, we are looking
for reviewers...