Subject: [xml2rfc] #385 (Version_3_cli_txt): misleading warning for sparse postal information

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 20:48:51 -0000

#385: misleading warning for sparse postal information

 In the attached example, one author has only city and country specified.
 The warning is:

 {{{
 foo.xml(28): Warning: Address check failed for author Πυθαγόρας ὁ Σάμιος.
 foo.xml(28):    Unexpected address info: <code>: (empty)
 foo.xml(28):    Unexpected address info: <street>: (empty)
 foo.xml(28): Note: Recognized address elements for Greece are: <extaddr>,
 <street>, <code>, <city>, <country>
 }}}

 So something seems to insert the empty elements causing the warning
 message.

-- 
-----------------------------------+--------------------
 Reporter:  [email-masked]  |      Owner:
     Type:  enhancement            |     Status:  new
 Priority:  minor                  |  Milestone:
Component:  Version_3_cli_txt      |    Version:  2.10.x
 Keywords:                         |
-----------------------------------+--------------------

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 20:52:11 -0000

Changes (by [email-masked]):

 * version:  2.10.x => 2.13.x

-- 
------------------------------------+--------------------
  Reporter:  [email-masked]  |      Owner:
      Type:  enhancement            |     Status:  new
  Priority:  minor                  |  Milestone:
 Component:  Version_3_cli_txt      |    Version:  2.13.x
Resolution:                         |   Keywords:
------------------------------------+--------------------

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:1>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 20:58:56 -0000

Comment (by [email-masked]):

 No; I may need to tweak the error message to be clearer.  What it tries to
 say is that a complete address would include <code> and <street> but there
 are no such elements.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:2>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 21:01:42 -0000

Comment (by [email-masked]):

 That would make the warning more logical, but I don't see why this should
 be a warning at all. There's nothing in the specs requiring address
 information to be complete.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:3>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 21:03:42 -0000

And this is not an error.

 Are you really trying to say that no warnings may be issued unless the
 specs explicitly say they must be given?

 There are a lot of informative warnings which will disappear in that case.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:4>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 21:10:16 -0000

You are right that there are reasons for warnings, even when the spec does
 not ask for them.

 I just don't understand why this is a warning; there's nothing wrong with
 having sparse postal information.

 At the end of the day we may want to ask the RSE for feedback on what kind
 of postal information should be included by an author.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:5>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Mon, 26 Nov 2018 21:12:32 -0000

Sure.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:6>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Tue, 27 Nov 2018 04:19:00 -0000

Comment (by [email-masked]):

 Relative to what the purpose of the message is, the wording is very
 strange:  It asserts that <code> and <street> are empty (when actually
 they are absent), then describes that they are "recognized" for Greece
 (when actually they are (quasi-)mandatory).

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:7>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 27 Nov 2018 08:35:05 +0100

> You are right that there are reasons for warnings, even when the spec does

Gratuitous warnings need a way to silence them.  
If I already get 10 warnings on a document where I know those are spurious, I’ll miss number 11 when it pops up.
(Not just a comment on the postal issues, also about the SVG warning being discussed etc.)

Grüße, Carsten

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 27 Nov 2018 13:32:02 +0100

> Gratuitous warnings need a way to silence them.

Agreed.

> (Not just a comment on the postal issues, also about the SVG warning being discussed etc.)

So here's what I think I'll do:

For the next release, I'll change the postal address warnings to notes,
and make it so they can be silenced with --quiet.  I'll also add the
possibility to use xml2rfc-specific PIs <?xml2rfc silence="{warning text}" ?>
to silence specific warnings and notes (but not errors) for a document.

Best regards,

	Henrik

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Wed, 28 Nov 2018 13:28:17 +0000

On 11/27/18, 7:32 AM, "xml2rfc on behalf of Henrik Levkowetz" <[email-masked] on behalf of [email-masked]> wrote:

    Agreed.

    

I know we're trying to get away from Processing Instructions, but this is the type of thing that PI were invented for: to turn on/off particular application options. Generating that warning is application-specific functionality; having a PI that says not to generate a warning seems reasonable.

Is "{warning text}" a code? A pattern? The entire note? Pylint uses unique codes for each warning so that they can be silenced easily without having to know what text was used for that code, or even what language was used.

	Tony

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 28 Nov 2018 15:37:13 +0100

On 2018-11-28 14:28, HANSEN, TONY L wrote:
> I know we're trying to get away from Processing Instructions, but
> this is the type of thing that PI were invented for: to turn on/off
> particular application options. Generating that warning is
> application-specific functionality; having a PI that says not to
> generate a warning seems reasonable.
> 
> Is "{warning text}" a code? A pattern? The entire note? Pylint uses
> unique codes for each warning so that they can be silenced easily
> without having to know what text was used for that code, or even what
> language was used.

In my current implementation, it uses {warning text} as a regex string
prefix, which means that just a string matching the start of the error
message may be used, or a regular expression for the start of the message.

In some of my test files, which use fixed dates, I now have this in front
of the <date> element:

  <?v3xml2rfc silence="The document date .* is more than 3 days away from" ?>

but could also have used

  <?v3xml2rfc silence="The document date" ?>

(I changed the PI target from 'xml2rfc' to 'v3xml2rfc' since PI target
names starting with 'xml' seem to be reserved.)

I've used linters and lint-like applications which turns warnings on
and off using numbers, and systems (like the python library 'warnings'[1]
used to turn python's own warnings on and off) that uses string matches
or prefixes, and find the string-prefix method easier to read in cases
like this, where the switch occurs inline in code or in a document.

Best regards,

	Henrik

[1] https://docs.python.org/2.7/library/warnings.html

---

From: "xml2rfc issue tracker" <[email-masked]>
Date: Wed, 28 Nov 2018 16:15:52 -0000

Comment (by [email-masked]):

 I work from home and don't want to include a street address for privacy
 reasons. In order to get rid of the warnings in v2, I use an empty
 <street></street> object. I would have preferred to just not have one
 since it is empty.

Ticket URL: <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/385#comment:8>
xml2rfc <http://tools.ietf.org/tools/xml2rfc/>