Comments on draft-roach-bis-documents-00

[David Noveck <[e-mail]>]

First of all, I'd like to thank you for writing this document.   Magnus
Westerlund brought it to my attention in connection with my attempt to
provide an updated explanation of the multi-server namespace features of
NFSv4.1 (with draft-nfsv4-ietf-mv1-msns-update and then
draft-ietf-nfsv4-rfc5661-msns-update).  It seems to me that your document
provides a good model to present an updated description of NFSv4.1 without
having to deal with NFSv4's lingering security deficits which are pretty
orthogonal to the multi-server namespace features which require revisions
to deal with trunking and transparent state migration.

I have a couple of issues with the doument that I'd like to bring to your
attention.   They concern the use of the term "bis documents" and some
apparent assumptions about how easy/diffcult it might be to get to a usable
base document to which desirted cghanges might be made.  Details below.

The first issue has to do with terminology, specfically your use of the
term "bis documents".    Since I anticipate a non-major update to NFSv4.1
using your procedure and also a later major update, I'm particularly
focused on that distinction and feel it would be wrong to obscure it, since
both your form of document, (to effect non-major revisions) as well as the
sort of bis documents that the NFSv4 working group has on rare occasions
been doing, will continue to exist even though the former are likely to
greatly outnumber the latter.

Specfically I feel that your use of the followng phrase in the
Abstract: "updated
procedure for publishing newer versions (colloquially known as 'bis
versions')" should be changed for the following reasons:

   - It ibscures the important distinction between mahor and non-major
   updates.
   - Different working groups use this term in different ways.   For may
   working groups, such as the NFSv4 working group, bis documents are rarely
   done and limited to major updates.   While other groups may have different
   experiences, it really doesn't make sense to build your document around an
   approach to terminology that is not universal
   - It has the unfortunate effect of obscuring what you have done, which
   is provide a way to do something desirable, that had not been possible
   before.  Instead, it treats your work as merely providing a new procedure
   for doing something that has been done all along.  In fact, the procedure
   for making major updates remains as it was, while you have provided a
   usable procedure for doing something that has, practically speaking, for
   many working groups, not been possible before, i.e. as your title
   indicates, it provides "A Process for Handling Non-Major Revisions to
   Existing RFCs"

I'd like to suggest the following changes:

   - Replace the second clause of the first sentence of the abstract by
   "presents a procedure for publishing newer versions of existing RFCs that
   is appropiate when major changes are not being made to an existing
   specfication".
   - Replace the second sentence of the abstract by "This procedure, which
   produces a document whose form is quite similar to that of existing bis
   documents, is expected to be easier for both authors and consumers of RFCs.
   - Add the following as a new first paragrph to section 3:

The process of producing revised versions is designed to allow the
production of revised documents, each of which will constitute a complete
replacement for the updated document in a fashiion similar to that which
has been used for bis documents.   Sections not affected by the updates to
be made will be reproduced unchanged.


   - In the existing first sentence of Section 3, replace  " At a high
   level, the process described in this document allows bis versions of
   documents" by "This process allows revised versions of existing RFCs"
   - Replace subsequent uses of the phrase "the process described in this
   document" by "the process of producing revised versions"
   - Delete Section 4.

The other set of issuues has to do with the document's assumption that one
could start with a document identical to the base rfc, and make only the
desired changes, considering all other changes as "spurious".   I have some
experience trying to produce the framework for an rfc5661bis (making a
major respecfication of the protocol, i.e. a "true bis document" as I would
have it) and I've seen a number of difficulties in which diffs will show,
for various reasons, differences between rfc5661 and any reasonably
possible base document.   Let me tell you my experiences.  I'll try not to
sound whiny but it may be unavoidable:

   - First of all .xml files for rfcs are not routinely kept, although they
   should be.  I'm not sure how to get that to change or exactly how it might
   affect your document but it is certainly relevant to what you want to do.
   - I was able to get a .xml file for rfc5661, somehow, from the RFC
   editor.
   - I found that xml2rfc would not process it successfully.   It took
   consideable work to get a file xml2rfc would process successfully.

Apparently an .xml file used to prodtce an rfc is not necessarily
acceptable to later versions of xml2rfc.  You can get an idea of the issues
by looking at rc5661Base.xml and the file I wound up with,
rfc5661Ready.xml; both are attached.

I was able to get a an .xml from which a .txt file could be generated, but
despite my best efforts there were differences (more than a few) between it
and rfc5661, which your document would consider to be "spurious" but appear
to be unavoidable. In any case they are not gratuitous changes and should
not interfere with consideration of the document.   The majority of the
diffs arise from the following  issues:

   - Despite the fact that the xml for the reference sections of both xml
   files are identical and the processing options are identical (symrefs="no"
   sortrefs="yes") the reference ids in rfc5661Ready.txt and in rfc5661 are
   different so that rfcdiff shows every line containing a reference as part
   of a diff.  Apparently, different versions of xml2rfc use different
   approaches to sorting references.
   - There are a fair number of difference that seem to have arisen because
   the RFC edtitor made minor corrections directly on the .txt file so that
   each such correction (while valid) is reported by rfcdiiff as a difference.
   - The reference sections are exposed to the same sorting issues as the
   reference id's.  To the naked eye, and to rfcdiff they look very different,
   despite that fact that they contain the same references.

To top it all off, it seems that there is a bug in rfcdiff.  it appears to
get confused, not report diffs in the reference and, fairly late in the
document start reporting major differences that dont exist.  Sigh!

I'm not sure exactly how to deal with all these these issues in your
document but I think that it is necessary to rethink item 3 in the
qualification list in section 3.1.   Even without these specific issues, it
seem unduly harsh to me to have any such difference foreclose consideration
of a document under your procedure.   There would be room for criteria
rejecting gratuitous changes as part of the process, even fairly strict
ones.  In any case, I don't feel that denying acess to the process totally
is right particularly in light of the kind of issues I've run up against.
:-(