Subject: [apps-discuss] RFC 6839 (media type suffixes) formatting error?

From: Bjoern Hoehrmann <[email-masked]>
Date: Fri, 08 Feb 2013 22:59:06 +0100

Hi,

  In http://tools.ietf.org/html/rfc6839#section-3.1 there seems to be a
formatting error (also present in the ordinary plain text version):

      The syntax and semantics for fragment identifiers for a specific
      "xxx/yyy+json" SHOULD be processed as follows:

      For cases defined in +json, where the fragment identifier resolves
      per the +json rules, then process as specified in +json.

         For cases defined in +json, where the fragment identifier does
         not resolve per the +json rules, then process as specified in
         "xxx/yyy+json".

         For cases not defined in +json, then process as specified in
         "xxx/yyy+json".

The second paragraph apparently should be indented like the following
ones. Am I missing something? Should I file this as errata item?

regards,
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: SM <[email-masked]>
Date: Fri, 08 Feb 2013 15:43:53 -0800

Hi Bjoern,
>formatting error (also present in the ordinary plain text version):

[snip]

>ones. Am I missing something? Should I file this as errata item?

It's a formatting issue.  The bug was introduced during RFC Editor 
processing.  I am copying the message to the authors as they can 
decide what to do about this.

Regards,
-sm

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Feb 2013 19:29:11 -0500

> ones. Am I missing something? Should I file this as errata item?

Most definitely not.  This isn't something we (your ADs) would judge
as an error that could cause confusion and incorrect implementations.
That would mean we'd have to deal with the erratum report and mark it
"held for document update".  If the document is ever updated, it will
certainly be fixed anyway, without the report.  Might as well save us
the time.

Please limit errata reports to things that might actually confuse
someone, and not to obvious typos or minor formatting glitches.  If
someone leaves out a "not", that's probably going to be a valid report
that you should file.  If someone spells "not" as "noy" by accident,
chuckle and don't worry about it.

Barry

(And thanks for asking.)

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Sat, 09 Feb 2013 02:56:06 +0100

>chuckle and don't worry about it.

The "Fragment identifier considerations" are fairly indigestable and the
formatting error on top of that certainly confused me enough to spend a
couple of minutes to read through other parts of the document to guess
what might be going on. The text for some of the other suffixes follows
the same schema, so one can reasonably conclude it is a formatting error
after some research, and people who do get confused by this as I have
are unlikely to be helped much by an entry in the errata tracker, but as
this is text people are likely to read out of context because they only
want to know what to put in their registration template for +json types,
I do not think your ridicule is justified. That aside, I think "errata"
ought to list all known errors, and it's not clear to me that there is a
net gain in omitting errors that people bother to mention for reasons
other than making a point.

A practical problem for me, as someone who has provided feedback on many
dozens of media type proposals over the last decade, and I encountered
this problem doing just that, is that I don't like pointing people try-
ing to register a +json media type but getting their Fragment Identifier
field wrong to the relevant section in this RFC, knowing that the error
has confused me in the past, without pointing the problem out. But I
also do not like telling people something is a "known error" when there
is no proper documentation that this is in fact a "known" "error".

A good solution here might be to make a "quick guide to media type re-
gistration", perhaps on the Applications Area Working Group wiki, and
pointing people to that instead of the RFCs. One reason I have not made
one in the past is that reviewers are reluctant to assert "everything
okay", so when registrations are too good, there would be no feedback,
but people would not know why there was no feedback...
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Feb 2013 21:20:18 -0500

> but as
> I do not think your ridicule is justified.

Oh, my!
Please accept my fullest apology; I never meant what I said to be
ridicule, and I'm truly sorry it came out that way.  No, of course
ridicule is not justified, nor was it intended.

> That aside, I think "errata"
> net gain in omitting errors that people bother to mention

I'm of a mixed mind on this -- many errata reports really are
unnecessary to record, though they were made with the best of
intentions, but I understand that the dividing line is a matter of
judgment.  The direction I described comes from the 2008 IESG and is
recorded here: http://www.ietf.org/iesg/statement/errata-processing.html

If the community thinks the current IESG should revisit this, we can
certainly do that; if you'd like to start a discussion of that, please
do, and please take it to <[email-masked]>.  We will pay attention to
the conversation.

> but people would not know why there was no feedback...

We can certainly encourage active reviewers to make sure that at least
one "looks good, and thanks for posting it for review" message is
always made in those cases.

But I think your idea of having a good summary of what's needed, with
a pointer to the formal documentation (and a note about the formatting
error) is an excellent one.  I encourage you and your fellow reviewers
to craft such a wiki page, please.

Barry

---

From: Eric Burger <[email-masked]>
Date: Sat, 9 Feb 2013 07:50:36 -0500

The errata system is just fine.  One can enter formatting errors as an editorial error.  Presuming the error is valid, the responsible reviewer should mark the error as Hold for Update.

I am a bit worried about this particular case.  If the document, for whatever reason, is so unclear that we are compelled to create a wiki to document how something really works so people can build interoperable implementations, then we have prima face evidence the RFC is not clear enough and should be updated.  What is situational is whether the update is via an errata, refresh of the document, or perhaps an Informational RFC.

On Feb 8, 2013, at 9:20 PM, Barry Leiba <[email-masked]> wrote:

> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Tony Hansen <[email-masked]>
Date: Sat, 09 Feb 2013 13:40:42 -0500

A list like that could be formatted as:

___The syntax ...
___For cases ...
___For cases ...
___For cases ...

or

___The syntax ...
______For cases ...
______For cases ...
______For cases ...

or

___The syntax ...
___For cases ...
______For cases ...
_________For cases ...

or

___The syntax ...
______For cases ...
_________For cases ...
____________For cases ...

or, as in the RFC,

___The syntax ...
___For cases ...
______For cases ...
______For cases ...

None of these change the meaning of the text

For consistency with the other sections, it would have been better if 
they all used the same indentation. But there's no technical issue with 
the document.

The indentation glitch happened extremely late in the editing process 
and was overlooked. The reason for it happening is a story itself, but 
it should be discussed on the RFC Editor Interest list, or the xml2rfc 
interest list. (In short, there's an issue with the xml2rfc 
nroff-writing code.)

As for writing an erratum, since the registrations in this RFC are meant 
to be held up as examples for other people to copy in the future, I 
think writing a non-technical erratum is perfectly reasonable to capture 
the issue. But it's only because other people might copy it and for no 
other reason. If they copy it and keep the bad indentation, and defend 
themselves with pointing at RFC 6839, we can point at the erratum as a 
counter argument. Which is sort of a tenuous reason to do so.

HOWEVER, the current review process for non-technical errata is 
exceedingly heavy weight. For example, it invokes AD responsibility to 
ensure that the non-technical erratum is reviewed. I feel that that 
level of AD involvement is totally inappropriate for non-technical 
issues, and the errata processing guidelines need to be updated. But 
that, again, is an argument for another list.

     Tony Hansen