Review of 28 Nov draft

On Nov 28, 2003, at 4:16 PM, Ian B. Jacobs wrote:

> The 28 November 2003 Editor's Draft of "Architecture of
> the World Wide Web" is now available at:
> Complete list of changes:

I'm relying the list of changes being correct in that I've used it to 
drive this editorial pass.

1.2.1 - Please lose the "Similarly, XML Schema" in the 2nd half of the 
2nd para; the PNG/SVG example makes the point satisfactorily.  Also, it 
is arguably not the case that XML schema's list of datatypes is 

1.2.1 bullet points: 2nd bullet point, 1st sentence is really wrong, I 
think that what HTML actually does is to allow representations to 
contain information which supplements or replaces actual HTTP headers.  
Rest of the 2nd bullet point text is OK though.  I'd lose the 3rd 
bullet point, the argument is well-established and the explanation of 
what's going on is not right and I don't think it's cost-effective to 
fix it.


Retitle it "Extensibility in General" otherwise there's no case for not 
moving it to 4.2.

1st bullet point, s/the fact/the fact that/
typo "open set Internet media types" 2nd bullet point

Too many bullet points, the argument is well-made.  I'd lose 
forward-compatible stylesheets and SOAP extensibility on the grounds 
that the fact that I personally have no understanding of either is 
evidence that they are less well-known in the field.

Arguably the definition of "subset" and "extension" could live happier 
in 4.2 but no biggie.

1.2.3, 2nd bullet point "see XXX for related information" is leaden 
language; just "also see XXX".

1.2.4 Is the 2nd sentence of the first para, about the longevity of 
messages, new in this draft?  It doesn't have anything to do, not in 
the slightest, with the actual point being made in this section.

1.2.4 I strongly suggest just losing the last paragraph on the grounds 
that it's totally opaque what it's there for.  If you know the history 
of this debate, it's obvious that we're throwing a bone to people like 
Mike Champion who argue (correctly) that APIs are actually important.  
But the basic point of this section is correct as it stands and 
couldn't reasonably be read as saying "APIs are evil."  If what we are 
actually saying is "please don't read this as 'APIs are evil'" then we 
should come out and say that, but it would be entirely unnecessary.

2. Would anyone else like to tighten up the first para by retaining 
just the first and last sentences?  It would be immensely clearer I 

2.2, 3rd para, typo "URI ownership URI"
s/consensus to abide/consensus on abiding/

2.2 last para, the sentence beginning "Of particular importance..." is 
hanging there naked, I have no idea why it's there or what it's 
actually saying.  Please remove it.

2.2 Good new section BTW!

2.3 Also well-reorganized.

2.4, 2nd-last para s/if you are designing/when designing/

2.4 last para isn't quite there, you need to reword slightly: "even if 
an agent cannot handle representation data in an unknown format, it can 
still retrieve the data, which may contain enough information to allow 
a user or..."

2.7.2 that's an "Assertion" not an "Expression", right?  The title as 
it stands is I think broken English.

3. Can you put an nbsp in the URI in the story?  It would look nicer.

3.1 first numbered step, shouldn't that be xlink:href rather than 
"XLink href"?  In particular since you use that in step 2 :)

3.2 1st para, shouldn't "metadata about the data" be "metadata about 
the resource"?  In any case "metadata about the data" is hopelessly 

3.3.2 1st para after story sentence beginning "Since different data 
formats..."; put a comma in there somewhere, it's too long, I suggest 
after "by design".  Also s/cannot represent/may not be able to 

3.3.2 towards the end s/one source of URI ambiguity/one potential 
source of URI ambiguity/

3.4 put in-doc link from first para to our nice new section on 
ownership above.

3.4.1 2nd bullet, the terminology "namespace of the root element" only 
applies in the case of XML representations, it *may* be worth 
acknowledging that

3.4.1 I agree with Ian that the trailing good practice is now pure 
fluff and should be deleted.

3.5 Why the new XForms plug?  It adds nothing to the example and 
creates confusion because people are going to wonder if this is special 
and different and couldn't have been done with old-fashioned HTML 
forms.  Must be removed.

3.6.2 First sentence hosed.

3.7.  Blecch, I hate this section but can live with it.  Except for, 
what in flaming hell is MLDonkey and how did it suddenly parachute in 

4.1 Why don't we just lose the note about "text" and "text/" here, it's 
covered below I think.

4.2.1 Moving the namespace-versioning stuff from 4.6 is OK, but I think 
you need a new section break in front of the story, you switch abruptly 
from version information to this very xml specific stuff.  Shouldn't 
cause any problems putting in.

4.2.2 "must understand".  I totally don't agree that "must understand" 
is limited to markup from another namespace.  XHTML could for example 
have applied a "must understand" policy to new XHTML elements (they may 
have, for all I know).  All you need to do is /markup from an 
unrecognized namespace/unrecognized markup/

4.3 The para beginning "Note that when content, presentation, and 
interaction are separated" is *very* fuzzy and I think could just be 
nuked.  I don't remember discussing this, is it the output of TAG 

4.4.1 s/see the "base" element in HTML and XML/see the "base" element 
in HTML and the "xml:base" element provided by XML/

BTW 4.4 is *much* better

4.5.1 s/in an in-order/in in-order/

4.5.1 clean up commas in 2nd sentence 1st clause, either 0 or 2, not 1.

4.5.2 is the TAG comfy with being this much in favor of XPointer?  I'd 
need to hear a few explicit "YESes"

4.5.5 2nd para, 2nd sentence is COMPLETELY WRONG.  Yes, you can convert 
back & forth between qunames & URI/local-part pairs.  What you can't do 
is go back & forth from qnames to URIs; which is clearly what Norm 

4.6 could be lost without loss of value

Received on Sunday, 30 November 2003 11:14:02 UTC