microformats / microformats2-parsing

For collecting and handling issues with the microformats2 parsing specification: http://microformats.org/wiki/microformats2-parsing
14 stars 6 forks source link

Specify the authoritative list of backcompat classes within parsing spec. #13

Open Zegnat opened 6 years ago

Zegnat commented 6 years ago

The microformats2 parsing specification page should link to v2 vocabularies as an authoritative list of backcompat root and property classes. Right now only the FAQ makes this clear.

Currently you cannot build a valid microformats2 parser by reading only the microformats2 parsing specification page, I feel that is wrong. Implementers should not have to go looking through a FAQ for things that are a must to be implemented.

The page currently does link to external implementations of the spec as examples for backcompat mappings. These are important enough to exist on the wiki.

Background (why it is important for parsers to know):

Without an official list, nested properties might be added to the wrong microformat by a parser. Consider:

<div class="h-feed">
  <p>Part of the implied name.</p>
  <article class="hentry">
    <h1 class="p-name">Explicit name!</h1>
  </article>
</div>

A parser that does not know hentry is a backcompat root class thinks p-name is directly under the h-feed microformat and output:

{
    "type": [ "h-feed" ],
    "properties": { "name": [ "Explicit name!" ] }
}

While a parser that does know it is a backcompat root class will drop p-name completely:

{
    "type": [ "h-feed" ],
    "properties": { "name": [ "Part of the implied name.\n  \n    Explicit name!" ] },
    "children": [
        {
            "type": [ "h-entry" ],
            "properties": { }
        }
    ]
}

Related issues

Note that #11 has an effect on the examples used here to show the problem. But no matter how that one is decided, I still think it is important to point implementers to an official list or root classes.

sknebel commented 6 years ago

Seems like it would make sense to add this list above http://microformats.org/wiki/microformats2-parsing#note_backward_compatibility_details