Subject: RE: WG Last Call: ABNF to Draft Standard

From: Dan Kohn <[email-masked]>
Date: Tue, 1 Dec 1998 17:26:07 -0800

Here are some minor edits:

+ The Introduction needs to say that this document replaces RFC 2234,
and then add the reference at the bottom.

+ I would also suggest replacing "RFC733" and "RFC822" with "RFC 733"
and "RFC 822", or even better, with "[RFC 733]" and "[RFC 822]" to
indicate that they are in the references.

+ Would it be possible for me to convince you to remove capitalizations
in the section headers and table of contents?  Besides the fact that
mixed case is standard, many people (including myself), find it
impossible to read all-caps text (other than basic-rules, of course) and
just skip over it.  I would even recommend changing "NOTE:" to "Note:".
Also, your right-justification of subheaders is also somewhat confusing
(yes, it took me a second to find the text).

+ You have an extra 2CRLF before each top-level section header.

+ In 2.3, the phrase that begins "To specify a rule which IS case
SENSITIVE..." should either be left-justified or be a "Note:".

+ At the very end of 2.3, you should put the "abc" in quotes to be
consistent with your usage elsewhere.

+ In 2.4, you say: "By separating external encoding from the syntax, it
is intended that alternate encoding environments can be used for the
same syntax."  The first example seems to potentially contradict this,
by specifying a US-ASCII value:

                  foo = %x61             ; a

Would it make sense to add a sentence saying: "Examples in the text
below use the US-ASCII environment as specified in Appendix A."?

+ In 3.4, I believe the discussion of mixing concatenated numeric values
and numeric value ranges needs to be moved to the appendix, section 7.1.

+ In 3.9, would it make sense to add a sentence saying, "When a rule
includes a multi-line comment, it is common to include an extra space
between the semicolon and comment on the second and subsequent lines."?

+ In the definition of "bin-value" in Section 4 and 7.2, does "ONEOF
range" have an obvious meaning I'm not aware of?  It appears to be the
only word in all caps that's not a rule.

+ In the definition of "prose-value" in Section 4, you are missing
semicolons on the 2nd and 4th comment lines, apparently because of
unexpected line wraps.

+ In the definition of "char-value" in Section 4, the second comment
line is missing a semicolon.

+ In the definition of "CHAR" in Section 6.1, the second comment line is
missing a semicolon.

+ It seems like a new section above the acknowledgements would be
warranted describing changes from RFC 2234 (e.g., creation of section 7
and minor edits).

+ In section 8, change "RFC #733" to "RFC 733" or "[RFC 733]".

		- dan

--
Daniel Kohn <[email-masked]>
Teledesic LLC
+1-425-602-6222 (voice)   602-0002 (fax)
http://www.teledesic.com 

>-----Original Message-----
>From: DRUMS WG Chair [mailto:[email-masked]]
>Sent: Monday, November 30, 1998 12:36 PM
>To: Detailed Revision/Update of Message Standards
>Subject: WG Last Call: ABNF to Draft Standard
>
>
>On Mon, 23 Nov 1998 [email-masked] wrote:
>> 	Title		: Augmented BNF for Syntax Specifications: ABNF
>> 	Author(s)	: D. Crocker, P. Overell
>> 	Filename	: draft-ietf-drums-abnf-v2-01.txt
>> 	Pages		: 10
>> 	Date		: 20-Nov-98
>> ...
>> A URL for the Internet-Draft is:
>> ftp://ftp.ietf.org/internet-drafts/draft-ietf-drums-abnf-v2-01.txt
>
>In one week, I will ask for an IETF last call to move this to Draft
>Standard.  Speak up now if you have any objections.
>
>		- DRUMS WG Chair
>

---

From: Dave Crocker <[email-masked]>
Date: Wed, 02 Dec 1998 16:51:25 -0800

>indicate that they are in the references.

done

>+ Would it be possible for me to convince you to remove capitalizations

I'll spare you the lengthy explanation of the lengthy (and thorough)
analysis which is the basis for the RFC format I use and will, instead,
note that even MORE thorough analysis revealed an alternative format which
achieves the same goal and will make you happy.  (And, yes, the
capitalization of "more" is intended for irony.)

>just skip over it.  I would even recommend changing "NOTE:" to "Note:".

nahh.  these need to jump out at the reader and the capitalization helps,
since ASCII doesn't have size or font controls.  In other words, the visual
dissonance it causes you is exactly the right effect.

>(yes, it took me a second to find the text).

An error in the first couple of sub-headings, now fixed.  The later use
distinguishes section title from right-hand description.

>+ You have an extra 2CRLF before each top-level section header.

I've fixed it.  Now there should be 3...

>SENSITIVE..." should either be left-justified or be a "Note:".

done.

>consistent with your usage elsewhere.

grrr.  mumble.

the quotes were left off, of course, so no one would think the string was
case-independent, but I've put them back in, since this is regular prose.

>below use the US-ASCII environment as specified in Appendix A."?

No harm in adding it.

And, by the way, if you are going to do such a thorough proof-reading, how
is it that you missed the double-commas in the first sentence of section
3.1?...

>and numeric value ranges needs to be moved to the appendix, section 7.1.

It specifies a constraint on the language.  Seems to me it should stay in
the main text.

>between the semicolon and comment on the second and subsequent lines."?

No.  That is entirely a matter of usage style, rather than formal requirement.

The ABNF specification, of course, is itself an example of pleasant ABNF
formatting, but I suspect others are possible.

>only word in all caps that's not a rule.

awkward, and probably wrong, wording.  replaced with less creatively
confusing verbiage.

>semicolons on the 2nd and 4th comment lines, apparently because of

cleaned up a range (?-?) of comments.

>line is missing a semicolon.

ditto.

>+ In the definition of "CHAR" in Section 6.1, the second comment line is

""

>warranted describing changes from RFC 2234 (e.g., creation of section 7

they are quite minor.  unless others feel a strong urge on this, I'll demure.

>+ In section 8, change "RFC #733" to "RFC 733" or "[RFC 733]".

fixed.

thanks.

d/

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Dave Crocker                                       Tel: +60 (19) 3299 445
<mailto:[email-masked]>             Post Office Box 296, U.P.M.
                                         Serdang, Selangor 43400 MALAYSIA
Brandenburg Consulting                                          
<http://www.brandenburg.com>                       Tel: +1 (408) 246 8253
Fax: +1(408)273 6464              675 Spruce Dr., Sunnyvale, CA 94086 USA