Subject: Re: [Xml-sg-cmt] Regression test over existing RFCs

From: Alice Russo <[email-masked]>
Date: Fri, 24 Sep 2021 13:37:20 -0700

Hi Robert,

On Sep 21, 2021, you wrote:
> The output for the current code produces no errors, but it produces a _lot_ of warnings. I'm wondering if those have changed since publication per-rfc or if we're throwing warnings that the RPC is deciding to not make changes around (which means they are likely noise and need to be adjusted).

Sometimes the warnings need a review to determine how to proceed. Details below.
> 
> There is an inflation factor of 3-ish on some of these numbers because the current test runs the text, html, and pdf generation separately, but the data is still usable.
> 
> 99 : Found tab on line

To summarize: RPC typically removes tab in <artwork> and <sourcecode>. However, we were told that in v3, tabs in <artwork> and <sourcecode> are converted to spaces as part of the rendering, and there should not be unexpected output. (Will forward you two mails from 2019 on this topic.)

Currently, if I insert tabs into <artwork> or <sourcecode>, there's no warning when running xml2rfc, so I'm curious for an example of this warning.

> 33 : Unused reference: There seems to be no reference to

In some cases, this warning is expected because the citation is hardcoded as "[RFCNNNN]" (rather than xref) within <artwork> or <sourcecode>, so we know there is no <xref> that matches the <reference>.

Suggest keeping this warning in place; it requires review, and in some cases it's OK to proceed.

> 30 : Artwork too wide, reducing indentation from

Suggest keeping this warning in place; it requires review, and in some cases it's OK to proceed.

Example: artwork with a width of 70, 71, or 72 chars can be intentionally left that way because the 3-char left margin will be reduced in the text output.

> 30 : Postal address part filled in, but not used

Suggest keeping this warning in place; it requires review, and in some cases it's OK to proceed.

In <postal>, there are some specifics to what elements are used for specific countries. Occasionally the misuse of an element within <postal> doesn't have a detrimental effect on the output. 

Example:  rfc8781.original aka draft-ietf-6man-ra-pref64-09
The original had "Shibuya" in two places. The XML had it in <street> and <city>.

Warning: Postal address part filled in, but not used: <city>: Shibuya

Q: Should we remove <city> to not get this warning?
(Either way, the second "Shibuya" does not appear in the output.)

HL> The warning is only advisory.  If you don't want to see it, then yes,
HL> remove 'city'.  The right postal element for Japan is 'country-area'
HL> which translates to the <region> element.

> 30 : Available elements for <whatever> are

Please point me to an example.

> 30 : Expected a title or title abbreviation of not more than 40 character

Suggest keeping this warning in place; it requires review, and in some cases it's OK to proceed.

Example: the long abbrev title fits in the PDF output even though it's over 40 chars. Example: https://www.rfc-editor.org/rfc/rfc8868.pdf

> 17 : Figure too wide, reducing indentation from

Seems the same as "artwork too wide" above.

> 4 : Too long line found

Please point me to an example.

> 
> Should we change how we are warning on any of those things?

Not to my knowledge.

> Were the ones reporting tabs and width violations intentional exceptions?

Mostly, yes, I think so.

Thanks,
Alice