[APPS-REVIEW] Gen-ART review of draft-ietf-dkim-overview-11

[Dave CROCKER <[e-mail]>]

I have been selected as the App Area Review Team reviewer for:
    <http://www.ietf.org/internet-drafts/draft-kim-abnf-codegen-00.txt>

The Apps Area Review team reference is at:
    <http://www.standardstrack.com/ietf/apps-review/>




Document:      An ABNF Extension for code generation
I-D:           draft-kim-abnf-codegen-00
Reviewer:      Dave Crocker
Review Date:   2009-06-24



Summary:

      This draft proposes two types of enhancements for ABNF:  an unordered set
construct and a generation-time directives construct.  The draft provides far
too little explanation for its choices or specification of them.  Further it
requires special-case handling of numerous existing ABNF constructs and is
likely to be confusing to use and complex to implement.



Extended Comments:

      ABNF permits specifying formats of protocol data units and payload
contents. It was first codified in RFC 733 and then RFC 822 and gained
popularity from amongst a variety of efforts that tailored pure BNF notation. As
part of the DRUMS effort to revise the primary email specifications, ABNF was
split out as a stand-alone reference, in RFC 5234.  The DRUMS effort included
extensive review of existing and proposed ABNF refinements.  The draft under
review, "An ABNF Extension for code generation" proposes enhancements to ABNF.
The stated purpose is to facilitate automated generate of software based on ABNF
specification.

      ABNF permits specifying an ordered sequence with the "( )" construct. The
current draft adds the construct of an unordered set noted with "{ }". The
draft also defines a means of adding code-generation directions, with an
enhanced commenting notation:  ";-- ".

      Over the years, many proposals for enhancing ABNF have been made. From
this it has become clear that the single biggest requirement for ABNF
enhancement is to develop a community demand for the change.  This review notes
that requirement but does not have the task of commenting on its presence or
absence for this particular proposal.

      In general, the draft text has clear and understandable text, with few
typographical or language errors.  However it has virtually no explanation for
the motivation behinds its particulars, or detailed explanation for how the
particulars work, including extended examples.  The draft needs a substantial
amount of both.

      Structurally, the draft has Section 2 defining Non-Sequence Group with
restrictions imposed by it, and Sections 3 & 4 discussion the Extension rule and
restrictions imposed by it.  That is, the two discussions have different
sub-structures and should be made to be comparable.

      The draft notes that an unordered set ("Non-sequence Group") construct was
part of the DRUMS effort but was dropped due to ambiguity concerns.  The draft
does not discuss how the current proposal satisfies those concerns.

      Within the context of Non-sequence Groups, the draft imposes special
interpretations of ABNF repetition, sequence, grouping and alternation.  This
makes Non-sequence Groups essentially independent of existing ABNF.  Having to
make definition of existing constructs be context-dependent -- non-sequence
group versus other uses -- is highly problematic.  It is certain to be confusing
and to make the code for an ABNF parser notably more complex.

      There is a long history in having parsing languages support
generation-time directives.  Hence, the basic idea in this part of the draft
could be useful.  Unfortunately, this portion of the draft is insufficiently
specified.

      The draft proposes a meta-notation for ABNF comments, by having the
comment begin with two dashes.  Hence:  ;-- .  This is specified as providing
"data type" and "variable name".  However I was not able to see that these were
provided in the particular Extension rules that were supplied.

      Mechanically, the draft needs to define a registry for directives.

      More basically, it needs to explain each provided directive in far more
detail than is supplied in the current draft.  Frequently, I could not tell what
a particular directive was meant to accomplish.  Other times I could not tell
how it as meant to accomplish it; that is, whether the supplied information was
sufficient.


d/


-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net