[apps-discuss] Full review of draft-ietf-appsawg-xml-mediatypes (was: Re: Getting 3023bis, a.k.a. draft-ietf-appsawg-xml-mediatypes, moving)

["Martin J. Dürst" <[e-mail]>]

I have finally completed a full review of 
draft-ietf-appsawg-xml-mediatypes-00. Here are my findings:

Technically, this document is in good shape. It describes actual 
practice that's widely established.

But I'm sorry to say that this document is pretty much unreadable, in 
particular for those who we want to read it. The reason for this is that 
it contains a huge amount of historical ballast and (for most readers) 
unnecessary justifications.

I think it should not be too difficult to remedy this problem, and it 
will help the average reader, which which I mean somebody who wants to 
publish or consume an XML document, or define a Mime type with a +xml 
suffix.

I'll try to point out the main changes that I'd start with below; I may 
be able to give more help, but next week looks busy.

On 2013/05/01 21:13, "Martin J. Dürst" wrote:
> On 2013/05/01 19:13, Henry S. Thompson wrote:
>> Rushforth, Peter writes:

>>> Suggest to remove reference to Appendix A. Remove Appendix A,
>>> also. All of that stuff is not the business of this RFC, but is the
>>> responsibility of the registration procedure, in my opinion.
>>
>> What do people think? Appendix A [3] is "Why Use the '+xml' Suffix
>> for XML-Based MIME Types?" and is carried over nearly unchanged from
>> RFC3023 [4]. Maybe it was needed 12 years ago but is no longer
>> relevant/necessary/useful?
>
> Yes. Please remove Appendix A, then add RFC 3023 as an informational
> reference and point to its Appendix A as "historical reading".
>
> More comments hopefully coming soon.

Removing the current Appendix A and pointing to it in RFC 3023 is the 
first and biggest step. I didn't realize this, but currently, RFC 3023 
is listed as normative, which is really strange.

Next, let's start from the start. The abstract says:

                                                         XML MIME
    entities are currently exchanged via the HyperText Transfer Protocol
    on the World Wide Web, are an integral part of the WebDAV protocol
    for remote web authoring, and are expected to have utility in many
    domains.

This sounds like text from 1997 (XML was finalized in 1998). I don't 
think there is any need in this document to explain how widely XML is used.

In the Intro, paragraphs can either be shortened or just removed. In 
particular, the paragraphs starting with "Although XML is a subset of 
the Standard Generalized Markup Language" and "Since XML is an integral 
part of the WebDAV Distributed Authoring Protocol" can just be cut. 
These were important for RFC 3023, in order to convince people who might 
not have heard about XML, or may not have known that the IETF was 
already using XML (in WebDAV), or confused it with SGML, but these days, 
that's not a problem at all.

In section 3 (XML Media Types), a lot of work is needed to disentangle 
what readers need to know (think about readers in 5 or 10 years) on the 
one hand, and rationale and historical background on the other hand 
(which becomes less and less important when moving to the future). The 
paragraph starting with "Within the XML specification", for example, 
several times switches between actual spec text (MAY/MUST/...) and notes.

Section 3.1, application/xml Registration: The text about the optional 
charset parameter is way too long to stay in this registration, and is 
referenced from many other places. I'd separate it out into a separate 
section, and just put a pointer to that section from the template. 
Again, as elsewhere, sort out the normative stuff from the 
rationale/history.

Section 3.6: A Summary is a good idea in a descriptive text, but putting 
additional MUSTs there is a bad idea. This probably just shows that the 
text up to here wasn't able to capture some essentials, which should be 
fixed at the source, not cleaned up afterwards with a summary.

Section 8: Same problems all over again. There is a lot of justification 
for why "+xml" may be needed. This may have been appropriate when the 
idea of a +xml suffix was first introduced, but that was 10 or more 
years ago.

8.1: It would be great if this document provided a template for +xml 
registrations, with the usual pointers already filled in (and lots of 
[add/change as appropriate] or so notices).

Similar problems in the security section, for example this piece of text:
    Use of XML is expected to be varied, and widespread.  XML is under
    scrutiny by a wide range of communities for use as a common syntax
    for community-specific metadata.
That was 10 or 15 years ago. Please let's rewrite this.

I have more comments on details, but I first wanted to get out this 
appeal for a general rewrite to move away from a historic/justificatory 
writing style to a simple and short spec that answers the direct 
questions of readers and stays readable in the future. I'm happy to 
contribute if help is needed.

Regards,   Martin.