Microdata is also not a component of HTML, which was one of the underlying reason for removing the Microdata section from the HTML5 specification in the first place. This makes for an additional reason to remove the Microdata references from the HTML5: The Markup Language Reference document.

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.234&r2=1.235&f=h

(In reply to comment #2)
> http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.234&r2=1.235&f=h

I'd prefer that at least the HTML WG keeps the terminology precise.

We have a WG decision to remove Microdata from HTML5, thus another spec pretending it is part of it isn't helpful.

Please be precise on scope (so, for now, make clear it's HTML5 *plus* Microdata). We can then make a decision whether we actually agree on this scope extension.

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.235&r2=1.236&f=h

(In reply to comment #0)
> Recent additions to the The Markup Language Reference have added references to
> Microdata Property Values. Yet this document is a non-normative guide specific
> to the HTML5 specification, only:

Actually, it was never my intention that it necessarily be restricted to only information from the HTML5 spec. The Abstract never explicitly stated that it was only restricted to that, and it already also includes information from at least one other third-party source, which is the default UA stylesheet from the WebKit source-code repo.

To clarify, I have updated the relevant part of the Abstract to read: "It is intended to complement the normative conformance criteria defined in the HTML5: A vocabulary and associated APIs for HTML and XHTML specification [HTML5], as well as information in related deliverables published by the HTML Working Group and from other sources."

(In reply to comment #3)
> (In reply to comment #2)
> We have a WG decision to remove Microdata from HTML5, thus another spec
> pretending it is part of it isn't helpful.

It's not pretending that Microdata is part of HTML5. It's intended instead to just be useful for people who do want to use Microdata in HTML documents, and who would benefit from having relevant reference information at point-of-use.

> Please be precise on scope (so, for now, make clear it's HTML5 *plus*
> Microdata). We can then make a decision whether we actually agree on this scope
> extension.

There has been no scope extension. I never intended the scope of the document to be restricted in such a way that I could not include relevant information from other HTML WG deliverables or even from third-party sources. If I had, I never would have included, for example, the fragments from the WebKit default UA stylesheet.

EDITOR'S RESPONSE: This is an Editor's Response to your comment. If you are
satisfied with this response, please change the state of this bug to CLOSED. If
you have additional information and would like the editor to reconsider, please
reopen this bug. If you would like to escalate the issue to the full HTML
Working Group, please add the TrackerRequest keyword to this bug, and suggest
title and text for the tracker issue; or you may create a tracker issue
yourself, if you are able to do so. For more details, see this document:

   http://dev.w3.org/html5/decision-policy/decision-policy.html

Status: Made change based on comment.
Change Description: Added clarification to Abstract section.
Rationale: The change makes it more clear that the htmlr doc is not intended to be restricted in scope to only providing information that corresponds just to the HTML5 spec and not to other documents.

(In reply to comment #5)
> (In reply to comment #0)
> > Recent additions to the The Markup Language Reference have added references to
> > Microdata Property Values. Yet this document is a non-normative guide specific
> > to the HTML5 specification, only:
> 
> Actually, it was never my intention that it necessarily be restricted to only
> information from the HTML5 spec. The Abstract never explicitly stated that it
> was only restricted to that, and it already also includes information from at
> least one other third-party source, which is the default UA stylesheet from the
> WebKit source-code repo.
> 
> To clarify, I have updated the relevant part of the Abstract to read: "It is
> intended to complement the normative conformance criteria defined in the HTML5:
> A vocabulary and associated APIs for HTML and XHTML specification [HTML5], as
> well as information in related deliverables published by the HTML Working Group
> and from other sources."

If you're redefining the scope of this document, you should discuss it in the group, first.

The whole point for this document was to supposedly strip away much of the information about the APIs and other peripheral information that has made its way into HTML5 and focus purely on the syntax. Microdata is not part of the syntax. 

To reference it is to begin the process in your document that has happened within the HTML5 document--bloat it by introducing irrelevant material. Your introducing this material seems more of a political decision than a technical one: trying to re-introduce Microdata as a part of HTML5, when the group has made a decision that it is _not_ part of HTML5.

And why Microdata? Why not RDFa, too? After all, it's also a document of the HTML WG. Again, singling out one and not the other is a political decision, not a technical one--and again, one that is significant enough to have been discussed in the group before making such a unilateral change. 

If you refuse to remove references to Microdata, this item will need to be escalated to an issue. Your "fix" is not a fix.

(In reply to comment #8)
> If you're redefining the scope of this document, you should discuss it in the
> group, first.

I'm not redefining the scope of the document. The scope of the document has not changed. Before I made the recent addition to the Abstract, the scope was not explicitly limited to only providing information strictly about the HTML5 spec. The text I added in response to your comment does not change the scope -- it simply adds some words to the Abstract in an attempt to provide more clarity about what the scope actually is.

> The whole point for this document was to supposedly strip away much of the
> information about the APIs and other peripheral information that has made its
> way into HTML5 and focus purely on the syntax.

That is a big part of the point of this document, for sure. But it is not the whole point nor has it ever been the whole point -- the document is not meant to focus purely on just the syntax.

> Microdata is not part of the syntax. 
> 
> To reference it is to begin the process in your document that has happened
> within the HTML5 document--bloat it by introducing irrelevant material.

I think it should go without saying that judgments about what amounts to bloat and introduction of irrelevant material are always subjective. I will say that I'm sensitive to the bloat argument, because one of my design goals for this document has always been too keep it minimal. (And I guess what amounts to being minimal is also subjective.) But that said, I think the particular addition of this Microdata property-value info is, relatively, a very small addition, and not bloat. It amounts to being a single sentence in each element page.

About whether what it's introducing is irrelevant, that seems to me to be something that reasonable people can disagree about. I don't personally find it irrelevant and I believe there are users of the document who will find it highly relevant.

From the very beginning when I wrote the first editor's draft of this doc and announced it, people were requesting that I add things to it. One thing that several people requested early on was that I add the DOM IDLs to it -- because they wanted them at point of use in the same document. So I added those -- even though it was not information that was necessary for determining document conformance. I also figured it would be useful to have some info in the same doc that provided details about UA rendering behavior. So I added the 'Typical default display properties" section -- again, even though that was necessary for determining document conformance.

> Your
> introducing this material seems more of a political decision than a technical
> one: trying to re-introduce Microdata as a part of HTML5, when the group has
> made a decision that it is _not_ part of HTML5.

My decision to add it was not a political one. I hope you can take my word on that and we won't need to spend time discussing it further.

> And why Microdata? Why not RDFa, too?

Because I don't know what content I could add to that doc as a per-element section that would provide similar information about RDFa. If you have specific suggestions about what I could add, please let me know.

> After all, it's also a document of the
> HTML WG. Again, singling out one and not the other is a political decision, not
> a technical one

My decision to add it was not a political one. Now that I have said that clearly, I hope I won't need to repeat it again and we can move on. To be very clear: My intent for the change was simply to add some information that some users of the document might find useful, and might be glad to have at point of use in this doc. That's it.

> --and again, one that is significant enough to have been
> discussed in the group before making such a unilateral change. 

I don't think it's any more of a unilateral change than the change I made that added the DOM IDLs, or the change I made that added the "Typical default display properties". 
 
> If you refuse to remove references to Microdata, this item will need to be
> escalated to an issue. Your "fix" is not a fix.

I'm not refusing. I'm responding to one request you made as a spec comment by providing, in good faith, an initial disposition (per the HTML WG decision policy) that I personally believe is the correct disposition for the comment.

I'm not at all claiming that it has been "fixed" to your satisfaction. Clearly it has not been. The "fixed" state is just what we are limited to in bugzilla for representing that particular condition I just describe. I don't know what other state to put it in at this point other than that -- because I don't think the description of the intended scope that you provided in your initial comment is accurate, and I think it would be a mistake for me to make a change based on a rationale drawn from something that I don't think is accurate, and that I cannot agree with.

If there is some part of your request that I have missed or ignored, or if you have more to add as rationale for the change you requested, than the right thing to do is to re-open it here, rather than prematurely escalating it.

(In reply to comment #9)
> (In reply to comment #8)
> > If you're redefining the scope of this document, you should discuss it in the
> > group, first.
> 
> I'm not redefining the scope of the document. The scope of the document has not
> changed. Before I made the recent addition to the Abstract, the scope was not
> explicitly limited to only providing information strictly about the HTML5 spec.
> The text I added in response to your comment does not change the scope -- it
> simply adds some words to the Abstract in an attempt to provide more clarity
> about what the scope actually is.

In other words, you redefined the scope of the document. 

> 
> > The whole point for this document was to supposedly strip away much of the
> > information about the APIs and other peripheral information that has made its
> > way into HTML5 and focus purely on the syntax.
> 
> That is a big part of the point of this document, for sure. But it is not the
> whole point nor has it ever been the whole point -- the document is not meant
> to focus purely on just the syntax.
> 
> > Microdata is not part of the syntax. 
> > 
> > To reference it is to begin the process in your document that has happened
> > within the HTML5 document--bloat it by introducing irrelevant material.
> 
> I think it should go without saying that judgments about what amounts to bloat
> and introduction of irrelevant material are always subjective. I will say that
> I'm sensitive to the bloat argument, because one of my design goals for this
> document has always been too keep it minimal. (And I guess what amounts to
> being minimal is also subjective.) But that said, I think the particular
> addition of this Microdata property-value info is, relatively, a very small
> addition, and not bloat. It amounts to being a single sentence in each element
> page.
> 
> About whether what it's introducing is irrelevant, that seems to me to be
> something that reasonable people can disagree about. I don't personally find it
> irrelevant and I believe there are users of the document who will find it
> highly relevant.
> 
> From the very beginning when I wrote the first editor's draft of this doc and
> announced it, people were requesting that I add things to it. One thing that
> several people requested early on was that I add the DOM IDLs to it -- because
> they wanted them at point of use in the same document. So I added those -- even
> though it was not information that was necessary for determining document
> conformance. I also figured it would be useful to have some info in the same
> doc that provided details about UA rendering behavior. So I added the 'Typical
> default display properties" section -- again, even though that was necessary
> for determining document conformance.
> 
> > Your
> > introducing this material seems more of a political decision than a technical
> > one: trying to re-introduce Microdata as a part of HTML5, when the group has
> > made a decision that it is _not_ part of HTML5.
> 
> My decision to add it was not a political one. I hope you can take my word on
> that and we won't need to spend time discussing it further.
> 
> > And why Microdata? Why not RDFa, too?
> 
> Because I don't know what content I could add to that doc as a per-element
> section that would provide similar information about RDFa. If you have specific
> suggestions about what I could add, please let me know.
> 
> > After all, it's also a document of the
> > HTML WG. Again, singling out one and not the other is a political decision, not
> > a technical one
> 
> My decision to add it was not a political one. Now that I have said that
> clearly, I hope I won't need to repeat it again and we can move on. To be very
> clear: My intent for the change was simply to add some information that some
> users of the document might find useful, and might be glad to have at point of
> use in this doc. That's it.

It is not helpful -- if one looks at the HTML5 spec, and then looks at your document, the references to Microdata come from out of nowhere. Even now, I can't figure out why you felt you had to include this information. Separate from the context of Microdata, and what it is, and how it should be used, the information is confusing, at best. 


> 
> > --and again, one that is significant enough to have been
> > discussed in the group before making such a unilateral change. 
> 
> I don't think it's any more of a unilateral change than the change I made that
> added the DOM IDLs, or the change I made that added the "Typical default
> display properties". 
> 
> > If you refuse to remove references to Microdata, this item will need to be
> > escalated to an issue. Your "fix" is not a fix.
> 
> I'm not refusing. I'm responding to one request you made as a spec comment by
> providing, in good faith, an initial disposition (per the HTML WG decision
> policy) that I personally believe is the correct disposition for the comment.
> 
> I'm not at all claiming that it has been "fixed" to your satisfaction. Clearly
> it has not been. The "fixed" state is just what we are limited to in bugzilla
> for representing that particular condition I just describe. I don't know what
> other state to put it in at this point other than that -- because I don't think
> the description of the intended scope that you provided in your initial comment
> is accurate, and I think it would be a mistake for me to make a change based on
> a rationale drawn from something that I don't think is accurate, and that I
> cannot agree with.
> 
> If there is some part of your request that I have missed or ignored, or if you
> have more to add as rationale for the change you requested, than the right
> thing to do is to re-open it here, rather than prematurely escalating it.

I do not believe you have provided an adequate rationale for making this change.

You've said that you changed the abstract, so that makes the change OK. You've said that this is supposedly to help people, yet these oddly bizarre references to Microdata, separate from the Microdata spec, make no sense at all.

So your rationale is, in my opinion, inadequate. 

My response has been that you have changed the scope of the document, as witness your change in the abstract. In addition, you're attempting to integrate Microdata back into HTML5, when the group has already made a decision that the two are separate. And your rationale for making this choice is, in my opinion, weak.

Yes, this needs to be escalated to an issue.

(In reply to comment #10)
> > I'm not redefining the scope of the document. The scope of the document has not
> > changed. Before I made the recent addition to the Abstract, the scope was not
> > explicitly limited to only providing information strictly about the HTML5 spec.
> > The text I added in response to your comment does not change the scope -- it
> > simply adds some words to the Abstract in an attempt to provide more clarity
> > about what the scope actually is.
> 
> In other words, you redefined the scope of the document. 

No, not in other words. I don't think that characterization is accurate. If you are going to continue to assert that, please look at the specific changes I made and then look back at what I had there before I made those changes and tell me how what I added changed the scope.

This is what I previously had in the Abstract, in full:

[[
This non-normative reference describes the HTML markup language and provides details to help producers of HTML content create documents that conform to the language. It is intended to complement the normative conformance criteria defined in the HTML5: A vocabulary and associated APIs for HTML and XHTML specification [HTML5]. By design, this reference does not describe related APIs in detail, nor attempt to explain how implementations that are consumers of HTML content are meant to process documents (those areas are covered by the HTML5 specification itself), nor attempt to also be a tutorial or “how to” authoring guide.
]]

Note that by design it very intentionally did not include language saying, for example, that it "only provides details to help producers of HTML content create documents that conform to the language" or even something like "primarily provides details". Similarly, it did not say that it is "only intended to complement the normative conformance criteria defined in" the HTML spec, nor "exclusively intended" nor again even "primarily" or whatever.

The omission of "only" or any such other qualifying language in that Abstract was not an accident or an oversight. It was intentional. I omitted it because it was in fact intended for the scope to be restricted in the way you are asserting that it is.

Here in full and for the record is what I changed in to in an attempt to address your comment:

[[
This non-normative reference describes the HTML markup language and provides details to help producers of HTML content create documents that conform to the language. It is intended to complement the normative conformance criteria defined in the HTML5: A vocabulary and associated APIs for HTML and XHTML specification [HTML5], as well as information in related deliverables published by the HTML Working Group and from other sources. By design, this reference does not describe related APIs in detail, nor attempt to explain how implementations that are consumers of HTML content are meant to process documents (those areas are covered by the HTML5 specification itself), nor attempt to also be a tutorial or “how to” authoring guide.
]]

That is, I added the part, "as well as information in related deliverables published by the HTML Working Group and from other sources". As I noted in previous comments, the "other sources" part is there because I had already information in the document from other sources; specifically, information taken from the WebKit default UA stylesheet. So I guess I could have changed it to read just, "as well as information from other sources" and it would have been accurate. But I added "in related deliverables published by the HTML Working Group" for the sake of trying to be more precise as well. (I suppose I will eventually add an explicit listing somewhere of what other sources it does have information from -- though I don't think the Abstract will be the appropriate place to go into those details.)

Anyway, I don't agree that the addition I made constitutes a change to the scope of the document. And my intent in making that addition was certainly not to change the scope. And I think what I quoted verbatim does not support the assertion that I changed the scope.

> > My decision to add it was not a political one. Now that I have said that
> > clearly, I hope I won't need to repeat it again and we can move on. To be very
> > clear: My intent for the change was simply to add some information that some
> > users of the document might find useful, and might be glad to have at point of
> > use in this doc. That's it.
> 
> It is not helpful -- if one looks at the HTML5 spec, and then looks at your
> document, the references to Microdata come from out of nowhere.

I will fully concede that'd be the case if you *only* looked at the HTML5 spec and not at the Microdata spec as well. But again, this document is not intended to only provide information that only corresponds to content in just the HTML5 spec.

> Even now, I
> can't figure out why you felt you had to include this information.

I said in previous comments that I added it because I think it can be useful for people who want to use Microdata in HTML documents, and who would benefit from having relevant reference information at point-of-use.

> Separate
> from the context of Microdata, and what it is, and how it should be used, the
> information is confusing, at best. 

I don't agree that as it currently stands it's confusing at best. Not by a long shot. I believe that people who know something about Microdata already and are doing something with it are going to find that section not confusing at all. And people who don't have use for the information can just skip over it.

And there is a other information in the document that requires context provided elsewhere and that is not meant to be immediately clear or useful to all reader. The DOM interface sections, for example, or not going to mean much to somebody who doesn't yet know anything about DOM scripting, and who only wants to write Web documents with no scripting. I will concede that they might be confused by those DOM interfaces parts of the document. But its a reference document, not a tutorial, so again, they can just skip over those parts and just use the parts they need.

> > If there is some part of your request that I have missed or ignored, or if you
> > have more to add as rationale for the change you requested, than the right
> > thing to do is to re-open it here, rather than prematurely escalating it.
> 
> I do not believe you have provided an adequate rationale for making this
> change.

For the record here, the exact rationale I gave is: "I think it can be useful for people who want to use Microdata in HTML documents, and who would benefit from having relevant reference information at point-of-use."

I've also made it clear that I very intentionally never restricted the scope of the document in such a way that would limit it to only providing information from the HTML5 and not from other sources (and pointed out that it already included information from other sources.)

> You've said that you changed the abstract, so that makes the change OK.

No, that is not what I said. The change was OK before I added words to the abstract.

I added text to the abstract not to make the change OK but instead as a good-faith attempt to address your comment.

> You've
> said that this is supposedly to help people, yet these oddly bizarre references
> to Microdata, separate from the Microdata spec, make no sense at all.

"oddly bizarre"?

As I pointed out earlier in this comment, I don't think the DOM interfaces make much sense at all to somebody who's not familiar with DOM scripting. And the "Typical default display properties" section is not going to make any sense at all to somebody who doesn't know anything about CSS.

> So your rationale is, in my opinion, inadequate.

I respect that opinion, but I don't think the assertions you've made above strongly support a conclusion that my "be useful for people who want to use Microdata in HTML documents, and who would benefit from having relevant reference information at point-of-use" rationale is inadequate.
 
> My response has been that you have changed the scope of the document, as
> witness your change in the abstract.

The text I added to the abstract does not change the scope. I added it in an attempt to address your comment. I don't think the added text is strictly necessary, but I do think it's an improvement to the abstract, so I would like to keep it rather than, say, feeling like I know need to remove it because of a claim that I added in order to change the scope (instead of for the actual reason I have given here).

> In addition, you're attempting to
> integrate Microdata back into HTML5, when the group has already made a decision
> that the two are separate.

I'm not attempting to integrate Microdata back into HTML5, any more than I'm attempting to integrate CSS in HTML by including the "Typical default display properties" section. 

> And your rationale for making this choice is, in my
> opinion, weak.

Again, I respect your opinion about it, but I don't agree that my "be useful for people who want to use Microdata in HTML documents, and who would benefit from having relevant reference information at point-of-use" rationale is weak.

(In reply to comment #11)
> The omission of "only" or any such other qualifying language in that Abstract
> was not an accident or an oversight. It was intentional. I omitted it because
> it was in fact intended for the scope to be restricted in the way you are
> asserting that it is.

Missed a "not" there. The last sentence should instead read, "I omitted it because it was in fact *not* intended for the scope to be restricted in the way you are asserting that it is."

(In reply to comment #11)
> (In reply to comment #10)
> > > I'm not redefining the scope of the document. The scope of the document has not
> > > changed. Before I made the recent addition to the Abstract, the scope was not
> > > explicitly limited to only providing information strictly about the HTML5 spec.
> > > The text I added in response to your comment does not change the scope -- it
> > > simply adds some words to the Abstract in an attempt to provide more clarity
> > > about what the scope actually is.
> > 
> > In other words, you redefined the scope of the document. 
> 
> No, not in other words. I don't think that characterization is accurate. If you
> are going to continue to assert that, please look at the specific changes I
> made and then look back at what I had there before I made those changes and
> tell me how what I added changed the scope.
> 
> This is what I previously had in the Abstract, in full:
> 
> [[
> This non-normative reference describes the HTML markup language and provides
> details to help producers of HTML content create documents that conform to the
> language. It is intended to complement the normative conformance criteria
> defined in the HTML5: A vocabulary and associated APIs for HTML and XHTML
> specification [HTML5]. By design, this reference does not describe related APIs
> in detail, nor attempt to explain how implementations that are consumers of
> HTML content are meant to process documents (those areas are covered by the
> HTML5 specification itself), nor attempt to also be a tutorial or “how to”
> authoring guide.
> ]]
> 
> Note that by design it very intentionally did not include language saying, for
> example, that it "only provides details to help producers of HTML content
> create documents that conform to the language" or even something like
> "primarily provides details". Similarly, it did not say that it is "only
> intended to complement the normative conformance criteria defined in" the HTML
> spec, nor "exclusively intended" nor again even "primarily" or whatever.
> 
> The omission of "only" or any such other qualifying language in that Abstract
> was not an accident or an oversight. It was intentional. I omitted it because
> it was in fact intended for the scope to be restricted in the way you are
> asserting that it is.
> 
> Here in full and for the record is what I changed in to in an attempt to
> address your comment:
> 
> [[
> This non-normative reference describes the HTML markup language and provides
> details to help producers of HTML content create documents that conform to the
> language. It is intended to complement the normative conformance criteria
> defined in the HTML5: A vocabulary and associated APIs for HTML and XHTML
> specification [HTML5], as well as information in related deliverables published
> by the HTML Working Group and from other sources. By design, this reference
> does not describe related APIs in detail, nor attempt to explain how
> implementations that are consumers of HTML content are meant to process
> documents (those areas are covered by the HTML5 specification itself), nor
> attempt to also be a tutorial or “how to” authoring guide.
> ]]
> 
> That is, I added the part, "as well as information in related deliverables
> published by the HTML Working Group and from other sources". As I noted in
> previous comments, the "other sources" part is there because I had already
> information in the document from other sources; specifically, information taken
> from the WebKit default UA stylesheet. So I guess I could have changed it to
> read just, "as well as information from other sources" and it would have been
> accurate. But I added "in related deliverables published by the HTML Working
> Group" for the sake of trying to be more precise as well. (I suppose I will
> eventually add an explicit listing somewhere of what other sources it does have
> information from -- though I don't think the Abstract will be the appropriate
> place to go into those details.)

But you have changed the scope of the document. It is no longer about HTML, which is the title of the document. It is HTML+Microdata, as Julian stated earlier. 

The Microdata material doesn't fit the document, Michael. Microdata is only important for those people wanting to take this approach for metadata. The data that you documented would be better within the Microdata document, then in your reference. 

I would suggest you work with Ian and add this information to the Microdata document. Then the data is more closely collected to the syntax relevant to it. 

> 
> Anyway, I don't agree that the addition I made constitutes a change to the
> scope of the document. And my intent in making that addition was certainly not
> to change the scope. And I think what I quoted verbatim does not support the
> assertion that I changed the scope.
> 
> > > My decision to add it was not a political one. Now that I have said that
> > > clearly, I hope I won't need to repeat it again and we can move on. To be very
> > > clear: My intent for the change was simply to add some information that some
> > > users of the document might find useful, and might be glad to have at point of
> > > use in this doc. That's it.
> > 
> > It is not helpful -- if one looks at the HTML5 spec, and then looks at your
> > document, the references to Microdata come from out of nowhere.
> 
> I will fully concede that'd be the case if you *only* looked at the HTML5 spec
> and not at the Microdata spec as well. But again, this document is not intended
> to only provide information that only corresponds to content in just the HTML5
> spec.
>

Again, this is counter to my understanding, and I believe it is counter to other people's understanding, too. 

 
> > Even now, I
> > can't figure out why you felt you had to include this information.
> 
> I said in previous comments that I added it because I think it can be useful
> for people who want to use Microdata in HTML documents, and who would benefit
> from having relevant reference information at point-of-use.
>

Then it is more appropriate to include this information in the Microdata document. Then you would have a self-contained document with all of the information. Now, all you have is this odd fragments in your document that make no sense at all. 

 
> > Separate
> > from the context of Microdata, and what it is, and how it should be used, the
> > information is confusing, at best. 
> 
> I don't agree that as it currently stands it's confusing at best. Not by a long
> shot. I believe that people who know something about Microdata already and are
> doing something with it are going to find that section not confusing at all.
> And people who don't have use for the information can just skip over it.
>

In other words, you're forcing people into having to access the Microdata document, when all they're interested in is HTML5, the markup language. Because without knowing what Microdata is, they have no idea if they need the information or not. 

Your microdata sections are just hanging there, with no relevance to the other material in the document. 

 
> And there is a other information in the document that requires context provided
> elsewhere and that is not meant to be immediately clear or useful to all
> reader. The DOM interface sections, for example, or not going to mean much to
> somebody who doesn't yet know anything about DOM scripting, and who only wants
> to write Web documents with no scripting. I will concede that they might be
> confused by those DOM interfaces parts of the document. But its a reference
> document, not a tutorial, so again, they can just skip over those parts and
> just use the parts they need.
>

But a person can't even know if they want to skip the info, because they'll not have the foggiest what the Microdata is for.
 
> > > If there is some part of your request that I have missed or ignored, or if you
> > > have more to add as rationale for the change you requested, than the right
> > > thing to do is to re-open it here, rather than prematurely escalating it.
> > 
> > I do not believe you have provided an adequate rationale for making this
> > change.
> 
> For the record here, the exact rationale I gave is: "I think it can be useful
> for people who want to use Microdata in HTML documents, and who would benefit
> from having relevant reference information at point-of-use."
>

Then point-of-use would be to include this information in the Microdata document, correct? That way Microdata is self-contained.

Again, I'm sure that you could work something out with Ian to include this information in the Microdata document. Perhaps you could be a co-editor for the spec?

 
> I've also made it clear that I very intentionally never restricted the scope of
> the document in such a way that would limit it to only providing information
> from the HTML5 and not from other sources (and pointed out that it already
> included information from other sources.)
> 
> > You've said that you changed the abstract, so that makes the change OK.
> 
> No, that is not what I said. The change was OK before I added words to the
> abstract.
> 
> I added text to the abstract not to make the change OK but instead as a
> good-faith attempt to address your comment.
> 
> > You've
> > said that this is supposedly to help people, yet these oddly bizarre references
> > to Microdata, separate from the Microdata spec, make no sense at all.
> 
> "oddly bizarre"?
> 
> As I pointed out earlier in this comment, I don't think the DOM interfaces make
> much sense at all to somebody who's not familiar with DOM scripting. And the
> "Typical default display properties" section is not going to make any sense at
> all to somebody who doesn't know anything about CSS.
> 
> > So your rationale is, in my opinion, inadequate.
> 
> I respect that opinion, but I don't think the assertions you've made above
> strongly support a conclusion that my "be useful for people who want to use
> Microdata in HTML documents, and who would benefit from having relevant
> reference information at point-of-use" rationale is inadequate.
> 
> > My response has been that you have changed the scope of the document, as
> > witness your change in the abstract.
> 
> The text I added to the abstract does not change the scope. I added it in an
> attempt to address your comment. I don't think the added text is strictly
> necessary, but I do think it's an improvement to the abstract, so I would like
> to keep it rather than, say, feeling like I know need to remove it because of a
> claim that I added in order to change the scope (instead of for the actual
> reason I have given here).
> 
> > In addition, you're attempting to
> > integrate Microdata back into HTML5, when the group has already made a decision
> > that the two are separate.
> 
> I'm not attempting to integrate Microdata back into HTML5, any more than I'm
> attempting to integrate CSS in HTML by including the "Typical default display
> properties" section. 
> 
> > And your rationale for making this choice is, in my
> > opinion, weak.
> 
> Again, I respect your opinion about it, but I don't agree that my "be useful
> for people who want to use Microdata in HTML documents, and who would benefit
> from having relevant reference information at point-of-use" rationale is weak.

We have to disagree. And I think we're going in circles here.

Actually, never mind on the Tracker Issue, unless someone else wants to pursue.

I don't have any faith in the HTML WG Decision Process system. Note, though, that I will most likely formally object to the inclusion of Microdata in your document when you progress to the next stage of publication. That is the only option I have now.

Michael, may I suggest you not make a bad situation worse, by tossing in RDFa references willy nilly all throughout your document?

These are just as inappropriate as the Microdata references. There's a term that should be branded across the forehead of every spec writer: Less, is more. 

Your document is an HTML Language Reference. At least, that's what your title says. Neither Microdata, nor RDFa, are part of the HTML language. That's why neither is part of the HTML5 spec. 

Your document is useful because it provides a simple to read and access overview of the HTML language -- the syntax, the requirements, the relationships between the elements. It does so cleanly, without all of the DOM and other material in the HTML5 spec. (The DOM interface pushes this, but at least it's presence is understandable). 

The more you add, the less useful the document will be.

here for the record are some related changes made to the editor's draft -

commit message: 'added "RDFa evaluation context" subsection for <base>, <html>, and
<body> elements; not sure that is the best title for the section, but
could not think of a better one...'

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.236&r2=1.237&f=h

that change was superseded by this one:

commit description: 'drop the "Microdata property value" subsection and "RDFa evaluation context" subsection and replace them with a "Linked-data semantics" subsection that appears only for elements that do in fact have special semantics in the context of linked data/semantic-web use.'

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.238&r2=1.239&f=h

I also made this small but related change:

'added RDFa usage note to descriptions of the lang and xml:lang
attributes'

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.237&r2=1.238&f=h

I plan to make some further refinements to the "Linked-data semantics" subsection when I have more time (hopefully later today). If anybody has suggestions for a better title for that subsection, lemme know.

Shelly, I do also plan to respond to your comments (the one's I've not responded to yet, I mean). Just wanted to let you know that I'm not ignoring them. (Most of my time yesterday was spent in telcons, and what time I had left over in between I used to unwind some borkedness I had recently introduced in the build for the generated "HTML5 (Edition for Web Authors)" subset of the HTML5 draft, and adding a few features to try to make that doc more useful as well).

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.239&r2=1.240&f=h

The elements that have a "Linked-data semantics" subsection are: a, area, audio, base, body, embed, head, iframe, img, link, meta/@name, object, source, time, and video.

For elements that have a src, href, or data attribute, that section reads, for example:

[[
Linked-data semantics

The a element, through its href attribute in combination with other linked-data/metadata markup mechanisms, provides a ready means for expressing semantic associations with external content.

For example, in the Microdata metadata-markup mechanism, specifying one or more named properties using the Microdata itemprop attribute on the a element associates those named properties with the external content represented by the value of the href attribute (if any).
]]

The section for the meta/@name element reads:

[[
For embedding non-visible metadata, the meta element—through use of its content attribute in combination with its name attribute, or in combination with other linked-data/metadata markup mechanisms—provides a ready means.

For example, in the Microdata metadata-markup mechanism, specifying one or more named properties using the Microdata itemprop attribute on the meta element associates those named properties with the text provided by the value of the content attribute (if any).
]]

The section for the time element reads:

[[
The time element, in combination with other linked-data/metadata markup mechanisms, provides a ready means for expressing semantic associations with specific times.

For example, in the Microdata metadata-markup mechanism, specifying one or more named properties using the Microdata itemprop attribute on the time element associates those named properties either with the time represented by the value of the datetime, attribute, if any; or, if there is no datetime attribute, with the text provided by the text content of the element.
]]

In each case, the intent of the first paragraph is to make the point that the element has inherent semantics that make it useful for marking up certain cases of metadata (regardless of any particular metadata mechanism that might be used).

The intent of the second paragraph is to illustrate that point by giving the example of the element's function in Microdata -- while mentioning Microdata in the context of it being one mechanism that makes use of the inherent metadata-amenable characteristics of the element (with no implication that Microdata is a part of HTML5 proper).

(In reply to comment #9)
> 
> > And why Microdata? Why not RDFa, too?
> 
> Because I don't know what content I could add to that doc as a per-element
> section that would provide similar information about RDFa. If you have specific
> suggestions about what I could add, please let me know.

I suggest that he look at adding both data-* and RDFa to section 7 (Core Attributes):

http://dev.w3.org/html5/markup/common-attributes.html#common-attributes

The meta concern is usage and abuse of the standards process as a means to "anoint" and advocate preferred extensions at the expense of others.  If there is a selection criteria for what markup is to be included, that criteria needs to be stated clearly up front.  It also would be helpful to clearly mark in the document where the element or attribute in question is defined in cases where this definition is not the HTML5 specification itself.

http://dev.w3.org/cvsweb/html5/markup/spec.html?r1=1.242&r2=1.243&f=h

I've removed all the "Linked-data semantics" sections. We seem to have disagreement about whether they are actually useful at all.

EDITOR'S RESPONSE: This is an Editor's Response to your comment. If you are
satisfied with this response, please change the state of this bug to CLOSED. If
you have additional information and would like the editor to reconsider, please
reopen this bug. If you would like to escalate the issue to the full HTML
Working Group, please add the TrackerRequest keyword to this bug, and suggest
title and text for the tracker issue; or you may create a tracker issue
yourself, if you are able to do so. For more details, see this document:

   http://dev.w3.org/html5/decision-policy/decision-policy.html

Status: Accepted.

Change Description: Removed all information about semantic-web/linked-data relevance of particular elements -- including all information about Microdata.

Rationale: Lack of agreement about whether the removed information is useful or not.

Removed TrackerRequest because it seems like Mike addressed the original request after TrackerRequest was added. Re-add if that resolution was not satisfactory.