Subject: Re: Please review updated 1id-guidelines

From: Bruce Lilly <[email-masked]>
Date: Tue, 1 Mar 2005 20:06:36 -0500

>  Date: 2005-02-19 19:02
>  From: Bill Fenner <[email-masked]>

>   I'm working on an update for 1id-guidelines.txt so that it
> will be ready to reflect the new IPR RFCs (RFC 3907 and 3908)
> when they are published.  It's gone through one round of
> discussion in the IESG; now I'm looking for more complete
> review.
> 
>   Pieces that could use extra review:
> - Section 3 - in particular, are the 4 choices for copyright
>   statements clear enough, and what type of document needs what?
> - Section 7 - the section on naming was redone, removing the
>   part about asking the secretariat for a filename, and adding
>   the rules for an I-D filename.
> - Section 9 - this was significantly updated to reflect the
>   authors' responsibilities under 3667/3668 (it still said
>   "if you know about IPR, you should consider sending an IPR
>   disclosure")

Below are my comments. Aside from some overall questions/comments,
they're in the same order as the document.

It's unclear what the status of the document is intended to be.
I suspect it should probably be a BCP RFC.

Sect. 2 mentions "six months" for expiration, whereas the actual
rule appears to be 185 days (six months from August 31 would be
February 31).  And of course, given some of the provisions late
in the document, a draft might nor expire then.  As I understand
the intended procedure, drafts are not deleted as such, they are
replaced with a "tombstone" file.  Sect. 2 mentions the "instructions
to RFC Authors" document; that should probably refer (instead or
additionally) to RFC 2223 or its successor (which the named
document is apparently intended to become).  An error was made in
conversion of "10 inches" -- the text "less than about 250mm"
should be replaced with "no greater than 254.00mm". How about
"Internet Draft" rather than the HYPHENATED-SHOUTING
"INTERNET-DRAFT"?  There is a discussion about restrictions on
content of the title -- RFC 2223 has text prohibiting a dot in
the title (implying that some circumlocution would be required
in a title addressing use of 802.11, etc.).

Section 3 gives some boilerplate text.  I believe that some options
should be available to conform that boilerplate to specific
circumstances.  For example, in the case of a draft written by
an individual author, saying "each author represents" is silly;
"the author represents" is more sensible. Likewise if a draft
has no female authors, it is silly, pointless, and offensive to
have multiple repetitions of "he or she" where "he" is accurate
and concise.  Likewise for use of "she" if the draft has no male
authors.  Some of the boilerplate has SCREAMING ALL CAPS -- is
that really necessary?  It looks awful.  Same concept as above
applies to the screaming "HE/SHE" in that text.  In the section
3 and in the later copyright boilerplate:
1. I'd like to see a statement that spaces around "(C)" are
   optional and that PostScript and PDF versions may use the
   copyright symbol in place of a parenthesized C.
2. Presumably the draft should not literally contain the
   characters "(year)"; should the year of publication be
   parenthesized or not -- it's not clear.
In place of "I accept" in some boilerplate, "the author accepts"
or "the authors accept", as appropriate for the draft, should
probably be substituted for consistency with other boilerplate.

Section 4, paragraph labeled a raises some amusing issues: by
referring to "languages other than English" there are a couple
of possible implications:
1. all drafts MUST be in English; but that is nowhere stated, at
   least not in the document under review
2. drafts in a language other than English (except for boilerplate)
   containing such a statement cannot under any circumstances be
   translated into English!
I think that needs some work.  Perhaps "languages other than
that of the original" solves the second problem w/o addressing
the first.  There are some references to change control mentioning
"IETF"; since the IETF is a large body with ill-defined membership,
perhaps change control issues should refer to the IESG (rather than
the IETF at large), since it is the IESG that makes such decisions
on behalf of the IETF.

Section 6 has another "six months" reference which should probably
be changed to "185 days".  [I'm resisting the urge to comment on
the ASCII-only provision; I'll leave that to somebody who is directly
affected.]

Section 8 discusses file names and tombstone files.  Can we please
add an IANA considerations section directing IANA to provide
working links to draft files (or tombstone files) when registering
some assignment based on a draft (prior to publication as an RFC)?
Currently, IANA has links from their web-based assignments tables
that point to a non-existent file, which leads to an HTTP 404
error and a lot of work to figure out where exactly the particular
assigned "number" is defined, how it is intended to be used, etc.

What's the deal with "Ignore this partial reference"?

Regarding updating of references, consistent use of BCP numbers
might save such effort in the future, since BCP numbers don't
change.

There is either a stray "bullet" or some missing text on page 12.

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 02 Mar 2005 13:59:57 +0100

Bruce,

 > I suspect it should probably be a BCP RFC.

At the risk of flamage, IMHO it shouldn't. I think we need more
flexibility in operational procedures than we can get from the
BCP mechanism. Asking for community input, and posting the resulting
text on the web site, seems to give that flexibility.

(If there are any true changes of principle involved, then touching
up the relevant BCPs would be called for. But, for example, your comments
about the required boilerplate are not comments on this text, but on
BCP 78, just re-published.)

    Brian

---

From: Bill Fenner <[email-masked]>
Date: Thu, 3 Mar 2005 18:32:50 -0800

> I suspect it should probably be a BCP RFC.

It's intended to replace http://www.ietf.org/ietf/1id-guidelines.txt .

> rule appears to be 185 days

Indeed, the secretariat's review also caught this error; thanks!

> Sect. 2 mentions the "instructions
> document is apparently intended to become).

The draft says 'This format is specified fully in "instructions to RFC
Authors" (see the RFC Editor's Web pages and
[I-D.rfc-editor-rfc2223bis]).' - is the reference there not the one
you're suggesting?

>  An error was made in
> should be replaced with "no greater than 254.00mm".

I did say "about".  I didn't think that the 4mm was particularly
important; maybe I'm just remembering how stupid I thought it read
when a book I was reading said "...about 621.37119 miles" when it was
converted from "about 1000 kilometers".

> How about
> "INTERNET-DRAFT"?

I don't mind removing the shouting, but the hyphenation is on purpose.
 Internet-Draft is meant to be a noun.

>  There is a discussion about restrictions on
> the title

rfc2223bis doesn't have this restriction.  However, it's worth
including 2223bis's restriction on acronyms.

> circumstances.

I copied the boilerplate in sections 3 and 4 from the lawyer-approved
text in RFC 3978.  I'm not inclined to change it without advice from
the lawyer (which I'm becoming convinced that I should seek - you're
not the only one who wants to vary the text.)

>    copyright symbol in place of a parenthesized C.

Do you mean that "Copyright(C)The Internet Society" is acceptable?

>    characters "(year)"

Indeed, that's why the document says 'The "year" in the copyright
statement should be replaced with the current year.'.  Can you suggest
a way to make this more clear?

> should the year of publication be

I think the intent is that it is, but again, I'm just interpreting RFC
3978, I didn't write the boilerplate.

> probably be substituted for consistency with other boilerplate.

I agree, but the ipr working group didn't make this change in the
updated RFC.  I'm still discussing this section with the RFC Editor so
these "I accept" options may just go away anyway.

> Section 4, paragraph labeled a raises some amusing issues

Again, these are RFC 3978 issues.  1id-guidelines is reflecting the
ipr policies, not making them.

> assigned "number" is defined, how it is intended to be used, etc.

I don't think 1id-guidelines is the place for this kind of specific
instruction to IANA - but it is a reasonable request.  I will bring
this up during our IETF/IANA coordination lunch on Monday.

> What's the deal with "Ignore this partial reference"?

It's a draft document and I wasn't focusing on the format of references.

> might save such effort in the future, since BCP numbers don't

Well, the whole reason for this update to 1id-guidelines is because
the content of BCP 78 changed between when it was published as RFC
3667 and RFC 3978, so I'm not sure that stability of reference is good
in this context.

> There is either a stray "bullet" or some missing text on page 12.

A stray bullet - sorry.

  Bill

---

From: Bruce Lilly <[email-masked]>
Date: Thu, 3 Mar 2005 23:26:33 -0500

> [I-D.rfc-editor-rfc2223bis]).' - is the reference there not the one

It's a matter of either having a stable reference (e.g. a published
RFC) or referring to something subject to change as a "work in
progress".  At least that's what would be expected if the document
were itself an Internet-Draft or RFC.

> converted from "about 1000 kilometers".

The problem is that it's not clear how to interpret "less than about".
Clearly 254mm was allowed (exactly equal to 10 in.); is that "less
than about 250mm"?  What about 254.1mm (> 10 in.)?
 
>  Internet-Draft is meant to be a noun.

OK. (note however that a number of recent drafts (not just mine)
lack the hyphen)
 
> including 2223bis's restriction on acronyms.

Good about the dot (considering that there in fact have been RFCs
with 802.3 etc. in titles).

> not the only one who wants to vary the text.)

At the same time, could you ask if it's possible to make the text
more concise.  It's difficult to fit a meaningful Abstract on page
1 so that the TOC can be placed on page 2 (as specified in 2223)
with boilerplate as verbose as it is (of course that's not all
due to legalese).

> Do you mean that "Copyright(C)The Internet Society" is acceptable?

Yes. The reason is that when preparing both text and formatted
versions with the same line and page breaks, both versions need
to have the same number of characters.  In the case of formatted
documents, that's <SP><copyright><SP> -- three characters.  Now it
would be possible to retain the spaces in the text version if the
formatted version has <SP><SP><copyright><SP><SP> -- five characters --
but that looks weird.  Breaking consistency usually wouldn't be a
problem on page 1, since the copyright line stands alone (ergo, line
and page breaks are unaffected).  But it can cause strange
inconsistencies at the end, where it's followed by "This document is
subject to [...]".

> a way to make this more clear?

Maybe an example?  Maybe it would be clearer with "YYYY" instead
of the word "year"?  Maybe both (example and YYYY)?

> ipr policies, not making them.

The draft update to 2223 states that RFCs are in English (2223
itself does not), but there doesn't seem to be any such requirement
for drafts.   Maybe there should be one (otherwise, we may need
different boilerplate).