Subject: Re: Call for review of proposed update to ID-Checklist

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Sat, 9 Aug 2008 21:35:20 +0200

Ted, a glib response would be:

     We can ask the RC-Editor to fix everything that is broken

But do we (IETF/ISOC) really want to spend a lot of real money on
payed RFC-Editor to fix up things that authors/editors can easily do,
specifically with a ID-Checklist in hand that points out the many
simple "things-to-fix" that we often found in many submitted
I-Ds?

My take is that we should put that responsibility with the
authors/editors and the WG chairs. That is what the document
does, and that is also what a WG chair is asked to check
when they fill out the questionaire in RFC4848 in section
3.1, The shepherd (often WG chair) is asked to confirm that he did check
the document to meet the ID-Checklist (see question 1.g on page 6).

And that SAVES a lot of time on already overloaded ADs/IESG
and also SAVES real dollars in the RFC-Editor cycle.

Bert
Editor for ID_Checklist

----- Original Message ----- 
From: "Theodore Tso" <[email-masked]>
To: "Pete Resnick" <[email-masked]>
Cc: "IETF Chair" <[email-masked]>; <[email-masked]>; <[email-masked]>
Sent: Tuesday, July 08, 2008 11:35 PM
Subject: Re: Call for review of proposed update to ID-Checklist

Re: Call for review of proposed update to ID-ChecklistOn Tue, Jul 08, 2008 
at 02:27:41PM -0500, Pete Resnick wrote:
> The document says:
>
> "If ABNF is used, you MUST include a normative reference to RFC 4234."
>
> To quote two fine radio personalities here in the states, this one seems
> "boooooooooogus". Yes, any I-D that uses ABNF must include a normative
> reference to RFC 4234, but for the IESG to not engage in review until it
> is in there is silly beyond belief. Make a note to the author that they
> need the reference and continue consideration.

Stupid question ---- isn't this specific thing something we should
allow the secretariat to fix as part of the RFC publishing process,
and in fact give them instructions to add the reference if they find
it missing?  They do things like fix/update references IIRC, and this
is only a minor step beyond that, and should be well within their
capabilities, I would think.

Sure, we can ask document editors to add the reference to RFC 4234,
and maybe we can even do things like include a reference to RFC 4234
in an RFC template file with a note to remove if the standard ends up
not using ABNF, but there must be a class of things which could be
streamlined to save time on both the document editors, reviewers, and
AD's time.

Regards,

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

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

---

From: Paul Hoffman <[email-masked]>
Date: Sun, 10 Aug 2008 08:18:48 -0700

An additional check should be added to the list: all URLs that are 
meant to be able to be resolved must actually resolve at the time of 
submission.

For example, the first URL in the ID-Checklist document does not resolve...

--Paul Hoffman, Director
--VPN Consortium

---

From: Julian Reschke <[email-masked]>
Date: Sun, 10 Aug 2008 18:03:27 +0200

Hi,

things I'd like to see done in IDs more consistently:

In an Editorial Note on the front page:

- state on which mailing list discussions should take place (include 
mailing list archive and subscription links)

- point to issues lists when available

References:

- check that if the document obsoletes or updates another document, that 
one appear in the references section, and make sure that the document 
actually says what's going on with respect to the other documents (such 
as "Normative Changes from RFC xxxx")

- use symbolic references

- when quoting RFCs, consider calling out a specific section in the 
referenced document (it's preferable that the author does it once, 
instead of the readers having to figure it out; also, it helps revising 
the document when the referenced document was revised)

Code:

- when using xml2rfc, add type parameters to artwork so that things like 
ABNF can be automatically extracted and checked

Versioning:

- (this probably is controversial :-) - keep an appendix that gives a 
short overview of what changed compared to previous drafts

BR, Julian

---

From: John C Klensin <[email-masked]>
Date: Sun, 10 Aug 2008 19:32:18 -0400

--On Sunday, August 10, 2008 6:03 PM +0200 Julian Reschke 
<[email-masked]> wrote:

> - state on which mailing list discussions should take place
> (include mailing list archive and subscription links)
>
> - check that if the document obsoletes or updates another
> document, that one appear in the references section, and make
> sure that the document actually says what's going on with
> respect to the other documents (such as "Normative Changes
> from RFC xxxx")

Of course, if one does this, the automated nits checker 
complains about a reference to an obsolete RFC :-(

> - use symbolic references

The RFC Editor is still flexible about this, IMO for good 
reason.   It should not be the prerogative of this document, or 
even the IESG, to change the preference to a rule.

>...
> Code:
>
> - when using xml2rfc, add type parameters to artwork so that
> things like ABNF can be automatically extracted and checked

FWIW, I continue to believe, based on experience with a few 
fairly large and complex documents (most recently rfc2821bis) 
that the xml2rfc approach of treating ABNF as a special type of 
artwork is seriously broken for at least two reasons:

    (1) It effectively forces the author to do formatting on a
    line by line basis, which is not what generic markup is
    supposed to be all about and is pathological for
    pretty-print applications (including HTML and Postscript
    output) because it prevents taking advantage of different
    line length and wrapping options.  That problem gets more
    severe if productions extend over several lines and/or
    contain comments.

    (2) It prevents indexing and use of XML elements to identify
    and organize portions of the ABNF (e.g., distinguishing rule
    names (LHS) from definitions (RHS) and comments).

For both of these, use of hanging <list> elements can actually 
work better than the artwork model even those that option has 
more than its share of disadvantages as well.

While I understand that this is a sufficiently large change to 
xml2rfc that I should not hold my breath, I think it would be 
very unfortunate to use the Checklist and/or its automatic 
instantiation to aggressively push a sometimes-unfortunate 
practice.

> Versioning:
>
> - (this probably is controversial :-) - keep an appendix that
> gives a short overview of what changed compared to previous
> drafts

Yep, it is controversial.   Good idea sometimes, bad idea 
others, hence probably a poor checklist guideline beyond, 
perhaps, "please consider keeping...".

best,
   john

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Aug 2008 07:46:21 +0200

John C Klensin wrote:
> Of course, if one does this, the automated nits checker complains about 
> a reference to an obsolete RFC :-(
> ...

It's only a warning if it is an informative reference...

> FWIW, I continue to believe, based on experience with a few fairly large 
> and complex documents (most recently rfc2821bis) that the xml2rfc 
> approach of treating ABNF as a special type of artwork is seriously 
> broken for at least two reasons:

I do agree that the approach of "either it is prose or it is artwork" 
does not work well for things lik e BNF, example mssages and so on...

>    severe if productions extend over several lines and/or

That sounds a bit like the problem is more related to the RFC line 
length, and the ABNF comment placement rules. If there's something that 
can be done in xml2rfc, I'd be interested to discuss this further 
(preferably on the xml2rfc mailing list).

>    names (LHS) from definitions (RHS) and comments).

I'm working around that by using custom extensions in rfc2629.xslt, and 
by translating these extensions into something xml2rfc understands 
(example: 
<http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p1-messaging-03.html>).

> For both of these, use of hanging <list> elements can actually work 
> better than the artwork model even those that option has more than its 
> share of disadvantages as well.
> 
> While I understand that this is a sufficiently large change to xml2rfc 
> that I should not hold my breath, I think it would be very unfortunate 
> to use the Checklist and/or its automatic instantiation to aggressively 
> push a sometimes-unfortunate practice.

Sounds like we need better tools. If automatic line wrapping for BNF is 
the issue, maybe a preprocessor would be sufficient.

BR, Julian

---

From: Lars Eggert <[email-masked]>
Date: Mon, 11 Aug 2008 10:52:02 +0300

Hi,

On 2008-8-11, at 2:32, ext John C Klensin wrote:
> --On Sunday, August 10, 2008 6:03 PM +0200 Julian Reschke <[email-masked] 
> > wrote:
> Of course, if one does this, the automated nits checker complains  
> about a reference to an obsolete RFC :-(

you only get an (incorrect) warning if the referenced RFC has  
_already_ been obsoleted by another document. For the normal case -  
document B obsoleting document A - there is no warning when B  
references A, because A's status changes to "obsolete" only after B is  
IESG-approved.

And as Brian correctly points out, idnits warnings/errors are  
sometimes bogus, which is where "think mode" comes in.

Lars

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 11 Aug 2008 09:52:27 +0200

All, 

PLEASE change the subject line if you change the topic to be discussed.

I do NOT think that the below has anything to do with my editing (or the
Call for review) of the ID_Checklist. 

The below list seems like a new set of desires that some people have
w.r.t. Internet Drafts (and resulting RFCs). The listed items may all be 
things for authors/editors to consider. They may also be things that 
some TOOL could possibly detect and warn about. But they are not
(and in my view should not be) topics of the ID_Checklist.

So I am not considering the below (and follow up discussions) as
part of my current editing cycle of ID-Checklist.

Bert
Editor for ID_Checklist.