Subject: Re: [TOOLS-DEVELOPMENT] rfclint-03

From: Robert Sparks <[email-masked]>
Date: Mon, 11 Aug 2014 14:36:18 -0500

On 7/23/14, 10:35 AM, Sandy Ginoza wrote:
> Hi Robert,
>
> Is it possible to update the SoW to remove combining idnits from this list?  Alice and I would prefer that the tool the RFC Editor uses not include these checks at this stage in the process.  An idnits tool could include all of the RFC Editor - related checks, but we would prefer to not to have to run idnits (or suppress results) each time we’re running the checker because we run the checks throughout the editorial process.
Would having an easy command option available to turn idnits checking on 
or off be sufficient?
We could design this so that the idnits checks did not run by default, 
but did run if a command flag was added, for instance.

RjS
>
> What is bap?
>
> I don’t have an objection to including checking that XML snippets are well formed as part of an initial check, but ABNF seems a little bit tougher.  Will the tool be able to pull definitions from previously published RFCs?  Currently, when we check ABNF, we sometimes need to call on ABNF files of other RFCs; for example, the following needs ABNF from RFC 3611 to parse correctly:
>
>     xr-format =/ xr-conceal-block
>                / xr-conc-sec-block
>
>     xr-conceal-block = "loss-conceal"
>     xr-conc-sec-block = "conc-sec" ["=" thresh]
>
>     thresh      = 1*DIGIT          ; threshold for SCS (ms)
>     DIGIT =     <as defined in Section 3 of [RFC5234]>
>
> Or, is the checker intended to identify ABNF issues with format only?
>
> Thanks,
> Sandy
>
>
>
>
> On Jul 14, 2014, at 2:21 PM, Robert Sparks <[email-masked]> wrote:
>
>> Attached.
>> This should be done unless there are more nits to address.
>>
>> <rfclint-03.docx><rfclint-03.pdf>_______________________________________________
>> TOOLS-DEVELOPMENT mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/tools-development

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Aug 2014 21:49:18 +0200

Hi Robert,

> but did run if a command flag was added, for instance.

I hadn't realized that this SoW could be interpreted as re-implementing
major parts of idnits.

I'm not against that -- idnits is more than ripe for re-implementation --
but I'm not sure you realize how many fiddly little things there are which
needs to be done exactly right to re-implement it acceptably.  That means
that it's a major undertaking in itself, and I don't think it's necessarily
a good idea to make it part of the rfclint SoW ...

Best regards,

	Henrik

> _______________________________________________

---

From: Robert Sparks <[email-masked]>
Date: Mon, 11 Aug 2014 15:32:13 -0500

> I hadn't realized that this SoW could be interpreted as re-implementing
There will have to be major updates to idnits anyhow when the input is xml
and not text (a whole chunk of what it checks now would be checking that the
text publication tool did the right thing vs whether the authors 
supplied the
right thing for example)
> needs to be done exactly right to re-implement it acceptably.
How much of that fiddle gets simpler when the source is XML and not text?
What's a good example of something that's guaranteed to _not_ be simpler?
>    That means
> a good idea to make it part of the rfclint SoW
I can look at splitting it out so we can make independent progress on 
it, but I do think in the long run, its naturally part of this tool.

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 12 Aug 2014 16:58:10 +0200

Hi Robert,

> text publication tool did the right thing vs whether the authors 

Mmm.  Idnits does a rather wide range of checks -- I think that if we are
going to dive into this, we need to separate out the different kind of
checks and talk about them category by category.

New code which is adapted for xml input instead of text input is needed, of
course, but maybe we should look at which categories of tests are needed
and valuable in this tool.

Also, since it is going to be permitted to submit text-only documents for
some time still, the current idnits (or a rewrite that runs the same tests
as the current tool) will have to continue to be available.

> How much of that fiddle gets simpler when the source is XML and not text?

Specifically the parts directly related to extracting text chunks -- the
remaining code shouldn't care too much if the content comes from text in
an XML entity or from a paragraph.  This includes code which looks at
reference usage, which won't be prone to mistakes in interpreting text in
square brackets as references.

Also verification of formatting specifics related to the paginated text
format -- all of those simply go away.

Also verifification of trust text and the acceptable 2026 and 3978
provisions -- no text matching needed.

> What's a good example of something that's guaranteed to _not_ be simpler?

Oh, for example use of literal IP addresses outside of the example ranges;
checks for status of references vs. intended standard status of the document
('downref' checks); correct use of example domains in FQDNs; listing of
obsoleted and updated documents in the abstract; etc...

Basically, errors emitted in the section of code between lines 2068 and 2245,
warnings emitted in the code between lines 2326 and 2484, and the following
reference checking logic.  (Note that the code that does the inspection and
sets up the flags for the messages emitted in the mentioned ranges comes later,
between lines 2448 and 3483).  Line numbers refer to idnits 2.13.01;
http://tools.ietf.org/tools/idnits/idnits-v2.13.01

> it, but I do think in the long run, its naturally part of this tool.

Ok, but then I think we need to specify more explicitly which idnits checks
should be included.

Best regards,

	Henrik

---

From: Robert Sparks <[email-masked]>
Date: Tue, 12 Aug 2014 14:44:46 -0500

(Top-posting, and leaving the quotes below for context:)

Given that we will have a non-trivial period of time where we need to be 
able to run nits
on both text and xml source, I think we want to put pressure on having 
one reusable
implementation, and not two that can drift apart.

I also think we need to push to take advantage of the xml capabilities 
in early, and not
plan to fall back to a model where the RFC Editor (or document authors 
that are using v3)
_have_ to go all the way through processing to the point that they are 
emitting a text
document in order to check nits. The boilerplate checks are an example 
of a place where
what we should do when given an xml document is different.

If you agree with all that,d o you think adjusting the current 
implementation to split the
functionality along the lines discussed below is better, or do you think 
re-implementing
would be the right way to go? If re-implementing, would you recommend 
doing this
again in sh, or moving to something else like python?

RjS

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 13 Aug 2014 12:33:35 +0200

Hi Robert,

On 2014-08-12 21:44 Robert Sparks said the following:
> Given that we will have a non-trivial period of time where we need to
> be able to run nits on both text and xml source, I think we want to
> put pressure on having one reusable implementation, and not two that
> can drift apart.

Reasonable.

> I also think we need to push to take advantage of the xml
> capabilities in early, and not plan to fall back to a model where the
> RFC Editor (or document authors that are using v3) _have_ to go all
> the way through processing to the point that they are emitting a
> text document in order to check nits.

Ack.

> The boilerplate checks are an
> example of a place where what we should do when given an xml document
> is different.

Granted.

> implementation to split the functionality along the lines discussed
> below is better, or do you think re-implementing would be the right
> way to go? If re-implementing, would you recommend doing this again
> in sh, or moving to something else like python?

Oh, continuing to build on the current implementation is silly.  The
only reason it's awk+shell now is that back in 2003, I thought it was
absolutely silly to manually check the line length of drafts I wrote,
so I wrote (or modified?) a little quickie awk script:

--------
BEGIN {
  errs = 0;
}

/.*/ {
  if (length($0) > 72) {
    printf("Line %d too long: chars %s\n", NR, substr($0,72));
    printf("  %s\n", $0);
    errs++;
  }
}

END {
  if (errs) {
    exit 1;
  } else {
    exit 0;
  }
}
--------

I then added checks for non-ascii characters, then unreasonable spacing,
then line-break hyphenation, and then it just grew ...

Awk was perfectly reasonable for that first script.  For a re-implementation
of the current monster (which it is, considered as a shell + awk script) I'd
strongly advocate Python.

Best regards,

	Henrik