Subject: ID Nits

From: Gonzalo Camarillo <[email-masked]>
Date: Thu, 26 Oct 2006 16:50:54 +0300

Hi,

when a chair does requests the publication of a draft, he or she needs
to do a PROTO write up for the draft. One of the questions the chair
needs to answer is whether or not the draft passes the ID Nits tool.

However, when I review drafts under the General Area review process, the
ID Nits tool complains about a lot of them.

I guess this means we should all stress in our respective WGs that
authors should always check their drafts with that tool before
submitting a supposedly final revision.

Cheers,

Gonzalo

---

From: Stewart Bryant <[email-masked]>
Date: Thu, 26 Oct 2006 15:14:08 +0100

> submitting a supposedly final revision.
I have always taken that to mean "has the chair run it through
the nits tool?", so that is what I do. It only takes a minute.

- Stewart

---

From: Lars Eggert <[email-masked]>
Date: Thu, 26 Oct 2006 16:18:40 +0200

> submitting a supposedly final revision.

And the PROTO shepherd needs to also personally check this. The  
writeup specifically asks:

    (1.g)  Has the Document Shepherd personally verified that the
           document satisfies all ID nits?  (See
           http://www.ietf.org/ID-Checklist.html and
           http://tools.ietf.org/tools/idnits/).  Boilerplate checks are
           not enough; this check needs to be thorough.  Has the  
document
           met all formal review criteria it needs to, such as the MIB
           Doctor, media type and URI type reviews?

(But sometimes Henrik updates the tool to catch new things, and the  
result of running the idnits tool changes.)

Also, there are additional verification steps in the latest version  
of the writeup, because these frequently aren't detected until IESG  
review:

    (1.h)  Has the document split its references into normative and
           informative?  Are there normative references to documents  
that
           are not ready for advancement or are otherwise in an unclear
           state?  If such normative references exist, what is the
           strategy for their completion?  Are there normative  
references
           that are downward references, as described in [RFC3967]?  If
           so, list these downward references to support the Area
           Director in the Last Call procedure for them [RFC3967].

    (1.i)  Has the Document Shepherd verified that the document IANA
           consideration section exists and is consistent with the body
           of the document?  If the document specifies protocol
           extensions, are reservations requested in appropriate IANA
           registries?  Are the IANA registries clearly identified?  If
           the document creates a new registry, does it define the
           proposed initial contents of the registry and an allocation
           procedure for future registrations?  Does it suggested a
           reasonable name for the new registry?  See
           [I-D.narten-iana-considerations-rfc2434bis].  If the document
           describes an Expert Review process has Shepherd conferred  
with
           the Responsible Area Director so that the IESG can appoint  
the
           needed Expert during the IESG Evaluation?

    (1.j)  Has the Document Shepherd verified that sections of the
           document that are written in a formal language, such as XML
           code, BNF rules, MIB definitions, etc., validate correctly in
           an automated checker?

See http://tools.ietf.org/wg/proto/draft-ietf-proto-wgchair-doc- 
shepherding/draft-ietf-proto-wgchair-doc-shepherding-08.txt

Lars
-- 
Lars Eggert                                     NEC Network Laboratories

---

From: Gonzalo Camarillo <[email-masked]>
Date: Thu, 26 Oct 2006 17:24:49 +0300

Hi,

yes, as a chair, I also run drafts through the tool... I sometimes need
to ask authors for a new revision only to fix a few nits before I
request the publication of a particular draft.

In any case, if authors used the tool in the first place, we would save
a few unproductive transactions in the process. Chairs would anyway need
to check drafts before shipping them, but, ideally, they would seldom
need to return a draft for a new revision only because of a few nits the
authors missed because they did not use the tool.

Cheers,

Gonzalo

Stewart Bryant wrote:
> Gonzalo Camarillo wrote:
> 
>> Hi,
>> 
>> when a chair does requests the publication of a draft, he or she
>> needs to do a PROTO write up for the draft. One of the questions
>> the chair needs to answer is whether or not the draft passes the ID
>> Nits tool.
>> 
>> However, when I review drafts under the General Area review
>> process, the ID Nits tool complains about a lot of them.
>> 
> I have always taken that to mean "has the chair run it through the
> nits tool?", so that is what I do. It only takes a minute.
> 
> - Stewart
> 
>

---

From: "Lars-Erik Jonsson \(LU/EAB\)" <[email-masked]>
Date: Thu, 26 Oct 2006 16:29:16 +0200

Whether there are nits or not can be seen on the tools wg pages, for
each version of each WG draft. 

/L-E

---

From: "James Kempf" <[email-masked]>
Date: Thu, 26 Oct 2006 07:44:32 -0700

The last time I ran a draft with normative and informative references split 
out through the idnits tool, it complained about a lot of unresolved 
references. The draft passed through fine prior to splitting the references.

            jak

----- Original Message ----- 
From: "Lars Eggert" <[email-masked]>
To: "Gonzalo Camarillo" <[email-masked]>
Cc: "Working Group Chairs" <[email-masked]>
Sent: Thursday, October 26, 2006 7:18 AM
Subject: Re: ID Nits

> And the PROTO shepherd needs to also personally check this. The  writeup 
> specifically asks:
>
>           not enough; this check needs to be thorough.  Has the  document
> Also, there are additional verification steps in the latest version  of 
> the writeup, because these frequently aren't detected until IESG  review:
>
>           informative?  Are there normative references to documents  that
>           strategy for their completion?  Are there normative  references
>           describes an Expert Review process has Shepherd conferred  with
>           the Responsible Area Director so that the IESG can appoint  the

---

From: Lars Eggert <[email-masked]>
Date: Thu, 26 Oct 2006 16:45:18 +0200

On Oct 26, 2006, at 16:44, James Kempf wrote:
> The last time I ran a draft with normative and informative  
> references split out through the idnits tool, it complained about a  
> lot of unresolved references. The draft passed through fine prior  
> to splitting the references.

FWIW, I've never run into this problem.

Lars

---

From: Alexey Melnikov <[email-masked]>
Date: Thu, 26 Oct 2006 15:49:03 +0100

Lars Eggert wrote:

>> lot of unresolved references. The draft passed through fine prior  to 
>> splitting the references.
>

I've seen that in several documents now. I've checked each one of them 
and they were bogus. I think something became broken recently.

---

From: Acee Lindem <[email-masked]>
Date: Thu, 26 Oct 2006 10:51:20 -0400

Lars Eggert wrote:
>> The last time I ran a draft with normative and informative references 
>> split out through the idnits tool, it complained about a lot of 
>> unresolved references. The draft passed through fine prior to 
I believe this warning is due to a new version of the tools. I noticed
xml2rfc now complains as well even if you have manually inserted
references [...]. Apparently, it is looking for some other format but I
haven't investigated. Perhaps, someone more familiar with the changes
could comment.

Acee
>
> Lars
> --Lars Eggert                                     NEC Network 
> Laboratories
>
>

---

From: Lars Eggert <[email-masked]>
Date: Thu, 26 Oct 2006 16:51:39 +0200

On Oct 26, 2006, at 16:49, Alexey Melnikov wrote:
>>> references split out through the idnits tool, it complained about  
>>> a  lot of unresolved references. The draft passed through fine  
>>> prior  to splitting the references.
>>
> I've seen that in several documents now. I've checked each one of  
> them and they were bogus. I think something became broken recently.

Can you point me at an example?

Thanks,
Lars

---

From: Jari Arkko <[email-masked]>
Date: Thu, 26 Oct 2006 17:55:01 +0300

> FWIW, I've never run into this problem.
I have not had any major problems with idnits either
recently or in fact ever. However, I know that
the likelihood of getting various boilerplate, I-D nits
and other problems increases when one writes drafts
using something else than xml2rfc (I think James uses
Word for at least some of his drafts, not sure if it
was the case here). This is easy to understand since
Henrik has to build recognition patterns to things
like the references section, and if the tool does
not force you to write in one specific way, its
possible that its not recognized.

--Jari

---

From: Vijay Devarapalli <[email-masked]>
Date: Thu, 26 Oct 2006 08:01:03 -0700

> Can you point me at an example?

when you for e.g. have an IKEv2 exchange with
[CERTREQ] payload, idnits complains there that
is no reference by that name.

but it does say it is an "experimental warning".

Vijay

> 
> Thanks,
> Lars
> --Lars Eggert                                     NEC Network Laboratories
> 
>

---

From: Alexey Melnikov <[email-masked]>
Date: Thu, 26 Oct 2006 16:01:39 +0100

Lars Eggert wrote:

>> I've seen that in several documents now.
>
Correction: I've seen many "unused references" which are actually used.

>> I've checked each one of  them and they were bogus. I think something 
>> became broken recently.
>

http://tools.ietf.org/wg/usefor/draft-ietf-usefor-usefor/draft-ietf-usefor-usefor-10.nits.txt

Experimental warnings:

  - Missing Reference: 'FWS' is mentioned on line 1532, but not defined
(ignore this one, this is not a reference)
  - Unused Reference: 'RFC2616' is defined on line 1484, but not referenced
  - Unused Reference: 'RFC0850' is defined on line 1474, but not referenced
  - Unused Reference: 'RFC3851' is defined on line 1497, but not referenced
  - Unused Reference: 'PGPVERIFY' is defined on line 1467, but not referenced
  - Unused Reference: 'RFC3864' is defined on line 1501, but not referenced
  - Unused Reference: 'RFC2980' is defined on line 1488, but not referenced
  - Unused Reference: 'RFC3156' is defined on line 1491, but not referenced
  - Unused Reference: 'RFC3696' is defined on line 1494, but not referenced

---

From: Lars Eggert <[email-masked]>
Date: Thu, 26 Oct 2006 17:16:18 +0200

> but it does say it is an "experimental warning".

Sorry for being unclear, I meant a draft that throws this error.

Lars

---

From: Vijay Devarapalli <[email-masked]>
Date: Thu, 26 Oct 2006 08:20:04 -0700

> Sorry for being unclear, I meant a draft that throws this error.

http://tools.ietf.org/wg/mip6/draft-ietf-mip6-ikev2-ipsec/draft-ietf-mip6-ikev2-ipsec-07.nits.txt

Vijay

---

From: Stewart Bryant <[email-masked]>
Date: Thu, 26 Oct 2006 16:43:25 +0100

I assume that the nits checker at

http://tools.ietf.org/tools/idnits/idnits.pyht

is not the same tool that the secretariat use?

We have just had a draft thrown back from the secretariat
as being boilerplate error, but the tool above passes the draft
and the problem seems to be just white space differences.

It would be a good idea in the identity/location of the definitive
nits checker was published before each IETF.

Also has any one had any trouble with the secretariat's
version database being out of sync. We has a bunch
of IDs thrown back with too high a version number and
had to go back to the announce archive to find the earlier
announces and show that we had used right numbers
in the first place.

- Stewart

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 26 Oct 2006 18:57:08 +0200

Hi Vijay,

> http://tools.ietf.org/wg/mip6/draft-ietf-mip6-ikev2-ipsec/draft-ietf-mip6-ikev2-ipsec-07.nits.txt

Yes, in this case the occurrence of '[CERTREQ]' in the draft is not
a reference, but idnits is unable to understand that it isn't a
reference.  I'd be happy to have a heuristic which lets me identify
this as not being a reference; I'm not happy about having idnits spit
out false positives, but I'm not currently able to distinguish the
usage in this draft from an actual missing reference, and I'd rather
mention the problem than remove this check altogether.

If the consensus here is that the occasional false positives regarding
missing references are more trouble than getting correct warnings
are worth, I'll remove this check.  I want the tool to be useful, not
annoying.

Regards,

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 26 Oct 2006 19:02:15 +0200

Hi Alexey,

>   - Unused Reference: 'RFC3696' is defined on line 1494, but not referenced

Yes, looking at the draft, these warnings are clearly incorrect.  I'll have
to work out why, and fix it.  The document seems well-formed, and I can't
see any obvious reason for idnits to fail on this one.

In the future, if you see things like this, send me a note, and I'll do what
I can to fix things swiftly.

Regards,

	Henrik

---

From: "Dan Wing" <[email-masked]>
Date: Thu, 26 Oct 2006 10:05:45 -0700

> writeup specifically asks:

Instead of "have you run it", how about asking:

  The PROTO shepherd should indicate which version of idnits
  was run against the document.

-d

---

From: Alexey Melnikov <[email-masked]>
Date: Thu, 26 Oct 2006 18:05:34 +0100

>see any obvious reason for idnits to fail on this one.
Yes. I was surprised because the document was generated using xml2rfc.

>I can to fix things swiftly.
Sorry, it wasn't my intention to complain publicly.

---

From: Jari Arkko <[email-masked]>
Date: Thu, 26 Oct 2006 20:23:39 +0300

> is not the same tool that the secretariat use? 
Its not the same tool. Yet.

--Jari

---

From: Vijay Devarapalli <[email-masked]>
Date: Thu, 26 Oct 2006 10:26:23 -0700

> are worth, I'll remove this check.  I want the tool to be useful, not

no, it wasn't annoying at all. they were anyway
marked experimental.

Vijay

---

From: Fred Baker <[email-masked]>
Date: Thu, 26 Oct 2006 11:21:01 -0700

this proto-shepherd includes the output of the run. That tells which  
version was run and what the result was - and if there is a flase  
positive or whatever lets him explain why it is OK.

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 26 Oct 2006 22:09:01 +0200

Hi Alexey,

> Henrik Levkowetz wrote:
...
> Yes. I was surprised because the document was generated using xml2rfc.

Right.  So here's the reason:  I switch from registering usage to registering
definitions for references when I find a "References" section.  Now,
unfortunately, this draft has this section, at the end of the draft (page 35):

7.  References

but it also has this earlier one, on page 24:

3.2.10.  References

So in this case, references occuring after page 24 are registered as potential
reference definitions, rather than reference usage...

I'm not sure how to handle this one -- I could tighten the definition of what's
a reference section to require it to be a top-level section, I guess.  Doing
this results in the following output for this draft, which on inspection seems
like a fair indication:

  Experimental warnings:
  - Missing Reference: 'FWS' is mentioned on line 1532, but not defined
  - Missing Reference: 'CFWS' is mentioned on line 1065, but not defined
  - Unused Reference: 'RFC3696' is defined on line 1494, but not referenced

I'll do some more tests, to see if this restriction has bad effects for
too many other drafts; if not, I'll make it part of the next release.

> Sorry, it wasn't my intention to complain publicly.

Oh, that's no problem.  You're perfectly welcome to complain on the wgchairs
list, on the [email-masked] list, or to me directly :-)  -- I just
want to be alerted to problems when they pop up, so things can be fixed
swiftly.

Regards,

	Henrik

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Thu, 26 Oct 2006 17:55:16 -0400

On Thursday, October 26, 2006 04:18:40 PM +0200 Lars Eggert 
<[email-masked]> wrote:

>> process, the

Note this text carefully!  The idnits tool checks most of the items that 
can be checked automatically, and is getting better every day.  However, 
the question is not "does it pass the automatic checker", but "Has the 
Document Shepherd personally verified that the document satisfies _ALL_ ID 
nits" (emphasis mine).  For example:

- Use of network byte order in diagrams
- Content of the IANA considerations section
- Proper split of references (the tool can't tell which references belong
  in which category)
- Meaningful abstract
- Meaningful security considerations
- Proper values for example addresses, names, numbers
- Proper references, particularly to non-IETF documents
- Avoid text that will be outdated after publication
- Protocol issues (ipv4 specificity, congestion, internationalization,
  proper specification of data to be checksummed, etc)

A few of these are the subjects of the new steps Lars mentioned; all of 
them are present in the ID-nits document.  These should all be checked 
before sending a document to the IESG.

-- Jeff

---

From: David Kessens <[email-masked]>
Date: Thu, 26 Oct 2006 10:57:09 -0700

Dan,

>   was run against the document.

I like this idea.

David Kessens
---

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 28 Oct 2006 20:30:32 +0200

> Stewart Bryant kirjoitti:

Hey, we can all learn Finnish :-)

> Its not the same tool. Yet.

The Secretariat is developing the future I-D submission tool
at the moment, and when that goes into beta testing we'll have
to look at any major discrepancies in the nit checking
area. The issues seem quite often to be about exact placement
and formatting of required text, and things like that.

     Brian

---

From: Marshall Eubanks <[email-masked]>
Date: Mon, 30 Oct 2006 12:38:07 -0500

Hello;

>>   was run against the document.

Is this sufficient ?

idnits 1.116

(It's what the tool spits out at the beginning.)

Regards
Marshall