Subject: [TOOLS-DEVELOPMENT] Update to the idnits SoW

From: Robert Sparks <[email-masked]>
Date: Fri, 26 Jun 2015 14:18:32 -0500

During rfc-design team discussion (and development of the preptool 
draft), we identified several new things that idnits should do with 
xml2rfc v3 source documents.

I've captured them at
<http://www.nostrum.com/~rjsparks/rfced/idnits-02.pdf>

Change bars are on. Please give the new requirements careful review.

The current versions of all the SoW are in that directory.

RjS

---

From: Paul Hoffman <[email-masked]>
Date: Sat, 27 Jun 2015 08:45:36 -0700

On Jun 26, 2015, at 12:18 PM, Robert Sparks <[email-masked]> wrote:
> During rfc-design team discussion (and development of the preptool draft), we identified several new things that idnits should do with xml2rfc v3 source documents.
> 
> I've captured them at

A few notes:

- I am pretty confused about the modes. The existence of "submission" mode means that now some errors are only errors some of the time, which makes them sound like warnings when they are not errors. Further, "forgive" mode also seems to weaken some things. Why are some things be errors only some of the time? When would that be valuable? To me, idnits should clearly say "if you have X in your document, you cannot submit it as a draft" and "if the document has X in it, it cannot become an RFC", and everything else is a warning.

- The text says "Other section headings can be searched for in a <titleelement> tag with a <section> tag." but there is no <titleelement> tag; I think you mean <name>.

- The "FQDN appears (other than www.ietf.org) not meeting RFC2606/RFC6761 recommendations" has caused lots of problems in the past, where authors have felt that they had to make all names be under .example, even when that made differentiating two names difficult. I see that this is just a warning, but it would be good if the warning message said that exceptions can be made to make the document clearer.

- I don't understand "A code-block is detected, but the block does not contain a license declaration". How does idnits determine what is code? (I suspect that this rule is a tarbaby that I ignored when it was developed.)

- "if the text was really a reference it should be in an <eref> tag" seems wrong. Did you mean <xref>?

- "Document starts with PK or BM". I have no idea what those are.

- What does section 3.3.2 mean? Are these for draft submission in text-only format? If so, what are the other parts of 3.3 for?

Hope this helps.

--Paul Hoffman

---

From: Robert Sparks <[email-masked]>
Date: Sun, 28 Jun 2015 17:17:27 -0500

> - I am pretty confused about the modes. The existence of "submission" mode means that now some errors are only errors some of the time, which makes them sound like warnings when they are not errors…
The tool is used in several different contexts. The "forgive checklist" 
mode was developed for the RPC, if I recall correctly. They run the tool 
in that mode at a few points while working on an RFC and they asked for 
several things to not be errors. Alice or Henrik might be able to 
provide even more insight.

> - The text says "Other section headings can be searched for in a <titleelement> tag with a <section> tag." but there is no <titleelement> tag; I think you mean <name>.
Thanks - that's a holdover from the first version of this sow which was 
done about the time hoffman-xml2rfc was at version 09.
It would be good to look to see if there are other change we need to 
adjust to from that era.

> - I don't understand "A code-block is detected, but the block does not contain a license declaration". How does idnits determine what is code? (I suspect that this rule is a tarbaby that I ignored…
The current tool looks for <CODE BEGINS> and <CODE ENDS> in the text.
See section 4.b of http://trustee.ietf.org/license-info/IETF-TLP-5.pdf
The new tool will have new and more semantically informative things to 
look for, at least when processing xml input.
> - "if the text was really a reference it should be in an <eref> tag" seems wrong. Did you mean <xref>?
Probably.
> - "Document starts with PK or BM". I have no idea what those are.
These are the strange things that you find when you start looking under 
the rocks in an organically grown tool.
You would probably find reading through 
https://tools.ietf.org/tools/idnits/idnits-v2.13.02 helpful. In this 
particular case, you're looking for:

		if (has_pk_mark) { comment("The first octets (the first characters of the first line) of this " \
					   "draft are 'PK', which can make Internet Explorer erroneously think " \
					   "that it is a zip file.  It is recommended that you change this, for " \
					   "instance by inserting a blank line before the line starting with 'PK'.") }

		if (has_bm_mark) { comment("The first octets (the first characters of the first line) of this " \
					   "draft are 'BM', which can make the draft submission tool erroneously think " \
					   "that it is an image .bmp file.  It is recommended that you change this, for " \
					   "instance by inserting a blank line before the line starting with 'BM'.") }

You can also grep for "option_checklistwarn" for more insight into the 
forgive-checklist mode.

>
> - What does section 3.3.2 mean? Are these for draft submission in text-only format?
All of section 3.3 is for processing text-only documents.
3.3.2 is for text-only documents that are Internet Drafts, and not text 
documents that are being prepared for publication as RFCs.
(This tool could well be finished before others, and used during pre- 
transition, while we're still producing text RFCs.
And, if it all falls apart and we continue working with text for longer 
than we plan, this rewrite of idnits is still highly desirable).

>   If so, what are the other parts of 3.3 for?
>
> Hope this helps.
>
> --Paul Hoffman