Subject: [draft-freed-sieve-in-xml-02] Minor Improvements

From: Robert Burrell Donkin <[email-masked]>
Date: Fri, 30 Jan 2009 16:39:32 +0000

(Some minor suggestions, typos, etc. I've batched these up since they
are not substantial.)

In "3. Grammatical structure of Sieve"
======================================
Original
--------
   Finally, comments are allowed between lexical elements in a Sieve
   script.  It is very important that comments be preserved in the XML
   representation.

Comment
-------
This is covered later but perhaps a little justification should be
offered at this point for the last remark

Suggested
---------
   Finally, comments are allowed between lexical elements in a Sieve
   script. One important use case for comments is encoding meta-data
   about the script, a facility which is lacking in the Sieve language.
   Therefore comments should be preserved in the XML representation.

In "4.1. XML Display Directives"
================================
Original
--------
   However, such information can be represented in XML very easily so it
   makes sense to define a framework to do this as part of the XML
   format.  Implementations may choose to use structured comments to
   retain this information when the script is converted to normal Sieve
   format.

Comment
-------
I think "may" should be "MAY"

Suggested
---------
   However, such information can be represented in XML very easily so it
   makes sense to define a framework to do this as part of the XML
   format.  Implementations MAY choose to use structured comments to
   retain this information when the script is converted to normal Sieve
   format.

In "4.2. Structured Comments"
=============================
Original
--------
   2.  Displaydata elements are placed in Sieve bracketed comments
       begining with the string "/* [|" and ending with the string "|]
       */".

Comments
--------
Typo (begining)
Easier to read when quoted text is not split

Suggested
---------
   2.  Displaydata elements are placed in Sieve bracketed comments
       beginning with the string "/* [|" and ending with the string
       "|] */".

Original
--------
   3.  The begininng of a displayblock element is mapped to a bracketed
       Sieve comment beginning with the string "/* [*" which then lists
       any displayblock attribute names and values in XML format.  The
       end of a displaydata element is mapped to a comment of the form
       "/* *] */".

Comments
--------
Typo (begininng)

Suggested
---------
   3.  The beginning of a displayblock element is mapped to a bracketed
       Sieve comment beginning with the string "/* [*" which then lists
       any displayblock attribute names and values in XML format.  The
       end of a displaydata element is mapped to a comment of the form
       "/* *] */".

---

From: Ned Freed <[email-masked]>
Date: Fri, 30 Jan 2009 10:19:46 -0800 (PST)

>    Therefore comments should be preserved in the XML representation.

Good idea. I'll add this or something very close to it.

>    retain this information when the script is converted to normal Sieve

Seems reasonable. Changed.

>        beginning with the string "/* [|" and ending with the string

Good catch - since I'm usually looking at the XML source I tend to miss stuff
like this in the final output. Unfortunately AFAIK xml2fc doesn't have a
"nonbreaking space" construct available, so I had to reword the sentence to get
the break to appear in the right place.

Of course the RFC Editor gets a crack at this, and has been known to reword
things, so this problem may reappear. I'll try to be alert to it during the
final approval process so we don't end up with this problem in the RFC.

>        end of a displaydata element is mapped to a comment of the form

Fixed.

Thanks for the review. I'll post a revised draft in a day or to that includes
these and a few other fixes.

				Ned