[Emailcore] Navigating 5321bis (and predecessors)

[John C Klensin <[e-mail]>]

Hi.

In trying to look for some other things today, I was reminded of
an issue that I think we should be clear about.   RFC 2821, and
hence 5321 and, in its present form, 5321bis, are badly
organized and show the results of basically being a merge of
three separate documents written at very different times.  Those
documents -- and consequently different sections of 2821 and
5321 -- depending a bit on how you count, show the different
writing styles and perhaps the motivations of as many as seven
different authors.  The result is that it is over-long and it is
hard to find things.  As a specific example from yesterday, Dave
wrote

	"with apologies to all, for my reading comprehension,
	limitations, but would someone point to the place in RFC
	5321 where the semantics of the FOR clause are
	explained, and especially in terms of it's coming from a
	RCPT TO?"

The implicit question of whether that portion of the
specification appears and where to find it turns out to be hard
to answer, much harder than it ideally should be, and that
problem is by no means limited to a particular clause in a
particular trace header.

We ended up in this uncomfortable situation because of a
decision at the time of DRUMS, reaffirmed at the time of YAM,
that the disadvantages of doing things that way were outweighed
by the risks of making inadvertent and problematic changes in
the process of a rewrite.  It doesn't make much difference then
and shouldn't now, but I came to conclude (along with many
others) that it was the right decision even though I hated it
then, still do, and my dislike gets stronger every time someone
says "I dare you to find where it says that" or "probably this
paragraph should be somewhere else".

I'm adding a warning note about this to 5321bis-02.  The WG
should decide whether it should be rewritten or removed prior to
Last Call or publication.

Two questions I'd like WG participants to think about:

(1) How much reorganizing and rewriting do we want to do and
what are our stopping rules?  Moving a paragraph from one place
to another (as in Erratum 1851; Ticket #28) seems rather easy
and safe.  Changing section titles and/or rewriting their
introductory paragraphs may be a bit more risky.  Or, in
principle, we could reverse the decision above and start on a
large-scale rewrite.  WHatever we choose, I think it would help
to have some sort of consensus about our target sooner rather
than later.

(2) Are there ways that we can mitigate the problems with
finding things.  The index in 5321 (and carried forward into
5321bis) was created as part of a compromise with the IESG after
the Last Call closed on what became 5321.  Because of how <iref>
elements are handled in xml2rfc v2, those index entries should
up as pointing to page numbers (as do the index entries in RFC
7749.  Presumably xml2rfc v3 will show section numbers.  Do we
want to retain the index?  If so, are there additional things
that could and should be indexed?   In particular, it occurs to
me that, with some hours of work, I could index keywords from
section titles.  Would that be worth doing in terms of finding
information or is the table of contents sufficient?   Other
ideas?

thanks,
   john