Re: [Extra] AD Review of draft-ietf-extra-imap4rev2

["Murray S. Kucherawy" <[e-mail]>]

On Mon, Jan 4, 2021 at 7:39 AM Alexey Melnikov <[e-mail]>
wrote:

> Hi Murray,
>
> Replying to some remaining editorial comments:
> On 04/01/2021 08:18, Murray S. Kucherawy wrote:
>
> Section 5.1
>
> There’s a reference “see the Formal Syntax” which could probably benefit
> from a section number reference as well.  This is actually something I’d
> thought about many times earlier in the document up to this point, but I’m
> finally saying something here; some of them were clear references like
> this, while others were references to commands or flags that are “described
> elsewhere in this document”.
>
> I fixed several cases of missing references. If you find anything else I
> missed, please let me know.
>

I'll check out -23.

Section 6.4.4.4
>
> I think the inline comments in the various examples don’t really need to
> be inline.  They could just as easily be prose below each example.
>
> For some examples this might be more involved than for others. Are you
> happy for this to be addressed directly with RFC Editor via an XML comment?
>

Sure.  I just found the inline comments caused the whole example to appear
a bit cluttered, and it didn't seem necessary to have them inline.  It's
more of a presentation thing.

>
> Section 7.2 and its subsections
>
> A fair bit of this text is repeated verbatim from earlier sections and
> should probably be consolidated.  I really noticed this when I hit Section
> 7.2.3 where, for instance, \HasChildren is defined both here and in Section
> 6.3.9.5, with the paragraphs in both sections being identical.  However,
> now that I look earlier in 7.2.2, I see the same issue.
>
> I struggled with some of this, as initially not all mailbox attributes
> were listed in Section 7.2.3 (LIST Response). In other sections it is had
> to talk about some options without introducing the corresponding mailbox
> attribute(s) first. So it would really help to have some specific
> suggestions on where you think text can be dropped.
>

Basically anything that's a verbatim copy from one section to the next
should be common factored someplace.  For a first suggestion, maybe a
section early on enumerating known mailbox attributes, to which later
sections can then refer?

You could also constrain Section 6 to discuss only the syntax and semantics
of the commands themselves and their options, and leave discussion of the
responses until their Section 7 counterparts.  To cite one particular
example, Section 6.3.9.5, the first paragraph is all you need because it
describes the modification to the LIST request in general prose; it can
then refer to the piece of Section 7 that gives details about the reply.
So 6.3.9.5 is reduced to something like:

   The CHILDREN return option is simply an indication that the client
   wants information about whether or not mailboxes contain children
   mailboxes; a server MAY provide it even if the option is not
   specified.

   This will cause the reply to contain \HasChildren or \HasNoChildren

   attributes on the responses to LIST.  These are described in Section

   7.x.y where the LIST response is defined.

-MSK