microformats2-faq: Difference between revisions
(→how do you use experimental microformats and property names: see vendor-prefixes\) |
GRegorLove (talk | contribs) m (s/<source>/<syntaxhighlight>/) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:microformats2 FAQ}} | |||
Frequently asked questions about [[microformats2]]. | Frequently asked questions about [[microformats2]]. | ||
| Line 8: | Line 8: | ||
A: '''Use the microformats2 class names first,''' and in equivalent pairs when marking up more than one property. E.g. | A: '''Use the microformats2 class names first,''' and in equivalent pairs when marking up more than one property. E.g. | ||
< | <syntaxhighlight lang="html"> | ||
<span class="h-card vcard"> | <span class="h-card vcard"> | ||
<a class="p-name fn p-org org u-url url" | <a class="p-name fn p-org org u-url url" | ||
| Line 19: | Line 19: | ||
<time class="dt-start dtstart">2012-11-14 18:00</time> | <time class="dt-start dtstart">2012-11-14 18:00</time> | ||
</span> | </span> | ||
</ | </syntaxhighlight> | ||
Here's how: | Here's how: | ||
* [[microformats2#backward_compatible|using microformats2 and backward compatible microformats]]. | * [[microformats2#backward_compatible|using microformats2 and backward compatible microformats]]. | ||
| Line 26: | Line 26: | ||
* The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition (as class names ''for'' microformats), and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is moved or maintained over time. | * The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition (as class names ''for'' microformats), and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is moved or maintained over time. | ||
== why are | == why are microformats2 properties prefixed == | ||
Q: Why do | {{main|prefixes}} | ||
<span id="why_are_microformats_2_properties_prefixed">Q: Why do microformats2 property class names have prefixes like 'p-', 'u-', 'dt-', 'e-' ?</span> | |||
A: For the benefit of both web authors and developers of parsers/consumers. By using class names with a small handful of short easily recognizable prefixes, it's easier to see which class names belong to microformats, and which may serve other purposes on the page. This helps web designers better recognize and maintain support for microformats across site redesigns for example. In particular: | A: For the benefit of both web authors and developers of parsers/consumers. By using class names with a small handful of short easily recognizable prefixes, it's easier to see which class names belong to microformats, and which may serve other purposes on the page. This helps web designers better recognize and maintain support for microformats across site redesigns for example. In particular: | ||
| Line 34: | Line 35: | ||
* 'dt-' is for date and time related properties that have a particular format themselves, and ideally should make good use of the HTML5 <time> element, though for backward compatibility they work on any element. | * 'dt-' is for date and time related properties that have a particular format themselves, and ideally should make good use of the HTML5 <time> element, though for backward compatibility they work on any element. | ||
* Finally, 'e-' is for properties whose value is the entirety of the text and HTML inside an element, as represented by the element's DOM. The 'e-entry-content' property from hAtom for example permits marking up and parsing/extracting an entire post from an HTML blog post page to an Atom feed entry with full markup/DOM fidelity of the original post. | * Finally, 'e-' is for properties whose value is the entirety of the text and HTML inside an element, as represented by the element's DOM. The 'e-entry-content' property from hAtom for example permits marking up and parsing/extracting an entire post from an HTML blog post page to an Atom feed entry with full markup/DOM fidelity of the original post. | ||
Since prefixes determine specific parsing rules, parser developers are able to write simple and efficient generic | Since prefixes determine specific parsing rules, parser developers are able to write simple and efficient generic microformats2 parsers without needing to know any specific vocabularies, either currently or in the future. These are both advantages of microformats2 over original microformats. For more details, including why and how microformats2 class name prefixes were developed, see: [[microformats2-prefixes]]. | ||
== how do you use experimental microformats and property names == | == how do you use experimental microformats and property names == | ||
| Line 77: | Line 78: | ||
In practice this has yet to be seen, thus for now, any concerns about awkward or confusing implied names for things like h-adr or h-geo are categorized as a "theoretical issue". If someone finds a real world example where the implied "name" causes a bad user experience in some actual use-case, then we can re-explore this topic. | In practice this has yet to be seen, thus for now, any concerns about awkward or confusing implied names for things like h-adr or h-geo are categorized as a "theoretical issue". If someone finds a real world example where the implied "name" causes a bad user experience in some actual use-case, then we can re-explore this topic. | ||
== does | == how does microformats2 separate syntax and vocabularies == | ||
Q: | <span id="does_microformats_2_split_vocabularies_and_syntax">Q: How does microformats2 separate syntax and vocabularies?</span> | ||
A: | A: microformats2 [[microformats2-parsing|specifies a syntax for parsing microformats]] which is independent of any specific vocabulary such as [[h-card]], [[h-entry]], or [[h-event]], each of which themselves defines vocabularies and backward compatibility handling for their classic microformats equivalents. Thus microformats2 separates specific vocabularies and syntax, whereas classic microformats combined the rules for parsing and specific vocabularies. There are three common property names (name, url, photo) determined from common markup patterns that the generic parsing algorithm is specified to imply. These apply across all vocabularies and thus are not dependent on any specific vocabulary. | ||
= | <span id="does_microformats_2_combine_vocabularies_and_syntax">Q: Does microformats2 combine vocabularies and syntax?</span> | ||
Q: Does | |||
A: | A: No. From a parsing perspective, microformats2 syntax is independent of any particular vocabulary. | ||
== are microformats2 vocabularies available to other languages == | |||
<span id="are_microformats_2_vocabularies_available_to_other_languages">Q: Are microformats2 vocabularies available to other languages?</span> | |||
A: ''Existing'' microformats vocabularies have [http://microformats.org/profile profiles] which are already available to other languages. Each term is defined by a URL ending in a hash and the term. This is due to the design of [[XMDP]] which deliberately produces such URLs which are compatible with microdata, RDF, and any other LinkedData system. microformats2 vocabularies will use the same profile format and thus also be available to other languages. | |||
== how do you convert a microformats2 example to RDFa syntax == | |||
<span id="how_do_you_convert_a_microformats_2_example_to_RDFa_syntax">Q: How do you convert a microformats2 example to RDFa 1.1 syntax?</span> | |||
A: In short you may use the 'typeof' attribute for the microformats2 root class name, and use the 'property' attribute for microformats2 properties. | |||
< | E.g. this from the microformats2 page: | ||
<syntaxhighlight lang="html"> | |||
<h1 class="h-card"> | <h1 class="h-card"> | ||
<span class="p-name"> | <span class="p-name"> | ||
| Line 107: | Line 108: | ||
</span> | </span> | ||
</h1> | </h1> | ||
</ | </syntaxhighlight> | ||
Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined): | Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined): | ||
< | <syntaxhighlight lang="html"> | ||
<h1 typeof="h-card"> | <h1 typeof="h-card"> | ||
<span property="p-name"> | <span property="p-name"> | ||
| Line 119: | Line 120: | ||
</span> | </span> | ||
</h1> | </h1> | ||
</ | </syntaxhighlight> | ||
The similarity of these two markup examples implies that it may be possible to extend RDFa 1.1 compliant parsers to become compliant | The similarity of these two markup examples implies that it may be possible to extend RDFa 1.1 compliant parsers to become compliant microformats2 parsers. | ||
== see also == | == see also == | ||
Latest revision as of 21:32, 26 July 2023
Frequently asked questions about microformats2.
when using both h-card and vcard which should be first and why
Q: When using both microformats2 and traditional microformats for backwards compatibility, which class name should go first and why? Another example: should "h-event" be first (before the "vevent") in the class attribute?
A: Use the microformats2 class names first, and in equivalent pairs when marking up more than one property. E.g.
<span class="h-card vcard">
<a class="p-name fn p-org org u-url url"
href="http://microformats.org/">microformats.org</a>
</span>
<span class="h-event vevent">
<a class="p-name summary u-url url"
href="http://plancast.com/p/e83d">microformats meetup SF</a>,
<time class="dt-start dtstart">2012-11-14 18:00</time>
</span>
Here's how:
And why:
- The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition (as class names for microformats), and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is moved or maintained over time.
why are microformats2 properties prefixed
Q: Why do microformats2 property class names have prefixes like 'p-', 'u-', 'dt-', 'e-' ?
A: For the benefit of both web authors and developers of parsers/consumers. By using class names with a small handful of short easily recognizable prefixes, it's easier to see which class names belong to microformats, and which may serve other purposes on the page. This helps web designers better recognize and maintain support for microformats across site redesigns for example. In particular:
- The 'p-' prefix is for typical string properties and parsing thereof.
- 'u-' is for URL-like properties whose values often come from another attribute such as the <a> 'href' or <img> 'src'.
- 'dt-' is for date and time related properties that have a particular format themselves, and ideally should make good use of the HTML5 <time> element, though for backward compatibility they work on any element.
- Finally, 'e-' is for properties whose value is the entirety of the text and HTML inside an element, as represented by the element's DOM. The 'e-entry-content' property from hAtom for example permits marking up and parsing/extracting an entire post from an HTML blog post page to an Atom feed entry with full markup/DOM fidelity of the original post.
Since prefixes determine specific parsing rules, parser developers are able to write simple and efficient generic microformats2 parsers without needing to know any specific vocabularies, either currently or in the future. These are both advantages of microformats2 over original microformats. For more details, including why and how microformats2 class name prefixes were developed, see: microformats2-prefixes.
how do you use experimental microformats and property names
I.e. what is the correct way to start using experimental microformats and property names in microformats2?
Documented primarily as microformats2 vendor extensions, here's a quick summary:
There are two cases:
1. Vendor-specific - extensions that either only make sense in or have a very specific detailed or other meaning (e.g. a shibboleth) in a particular company or organizational context.
Use -vendorabbr- immediately after a microformats2 prefix, where "vendorabbr" is an abbreviation for the company (e.g. stock symbol) or organiztion. E.g.
h-goog-volcanofor a proprietary "volcano" objectp-osm-shopfor an OSM-site specific "shop" property
See vendor-prefixes for currently used and proposed vendor-prefixes (in case there already is one for the vendor-specific stuff you want to publish or consume, re-use instead of reinvent etc.).
2. Experimental - ideas that authors/developers want to experiment with in the wild without going through the microformats process to craft well-researched microformats and property names. Or for experimental formats that you're not even sure would be worth trying to standardize, may apply to a narrow / small community etc. (which might still grow as a result of experimentation, and thus eventually merit a format).
Use -x- immediately after a microformats2 prefix, e.g.:
h-x-test-fixturefor an experimental "text-fixture" format (e.g. for a test-suite).p-x-prep-time- a possible experimental preparation time property to be added to h-recipe upon consideration/documentation of real-world usage/uptake.
how do h-adr and h-geo work with an implied name property
Q: Some microformats like h-adr and h-geo are usually used as just collections of properties and typically lack explicit names or "p-name" properties. How does the implied "name" property work with such microformats?
A: First, there is the use-case of named locations which aren't necessarily full h-card venues in and of themselves. For named locations, the name is published in visible text and should be marked up with e.g. class="p-name".
Other h-adr and h-geo microformats which lack an explicit name will have a name implied for them (e.g. from the full text of the element including all such visible property values in document order).
While at first it may seem silly to create a name for something which is merely an address or a latitude+longitude geolocation, there are some good reasons to imply a name even for such collections of properties.
Locations are often shown in a list (e.g. by Checkin interfaces and applications). Lists showing all the locations on a page (e.g. all its h-card, h-adr, h-geo microformats) need labels for each item. The name of a location (whether explicit or implied) serves as the presentational label/title for that location in such lists.
Checkin location lists are just one use-case, there are many more. Any kind of page summarization tool (e.g. validators, linters) or anything which presents an interface to summaries of a page (e.g. web search results) benefits from having an explicit automatic way to determine how to label each and every microformat data item on a page.
Every such list of data items needs to label the items, and rather than just calling them "untitled item 1" etc., using the actual visible content of the item provides a nice clear connection to the specific item. Since the implied name comes directly from a snippet of text authored by a human, in the order that the human authored it as they intended it to be read (listened to), it will make sense as a label as well.
If an author explicitly wants an empty label for their microformat, while not recommended, they can explicitly specify as such: <span class="p-name"></span>
In practice this has yet to be seen, thus for now, any concerns about awkward or confusing implied names for things like h-adr or h-geo are categorized as a "theoretical issue". If someone finds a real world example where the implied "name" causes a bad user experience in some actual use-case, then we can re-explore this topic.
how does microformats2 separate syntax and vocabularies
Q: How does microformats2 separate syntax and vocabularies?
A: microformats2 specifies a syntax for parsing microformats which is independent of any specific vocabulary such as h-card, h-entry, or h-event, each of which themselves defines vocabularies and backward compatibility handling for their classic microformats equivalents. Thus microformats2 separates specific vocabularies and syntax, whereas classic microformats combined the rules for parsing and specific vocabularies. There are three common property names (name, url, photo) determined from common markup patterns that the generic parsing algorithm is specified to imply. These apply across all vocabularies and thus are not dependent on any specific vocabulary.
Q: Does microformats2 combine vocabularies and syntax?
A: No. From a parsing perspective, microformats2 syntax is independent of any particular vocabulary.
are microformats2 vocabularies available to other languages
Q: Are microformats2 vocabularies available to other languages?
A: Existing microformats vocabularies have profiles which are already available to other languages. Each term is defined by a URL ending in a hash and the term. This is due to the design of XMDP which deliberately produces such URLs which are compatible with microdata, RDF, and any other LinkedData system. microformats2 vocabularies will use the same profile format and thus also be available to other languages.
how do you convert a microformats2 example to RDFa syntax
Q: How do you convert a microformats2 example to RDFa 1.1 syntax?
A: In short you may use the 'typeof' attribute for the microformats2 root class name, and use the 'property' attribute for microformats2 properties.
E.g. this from the microformats2 page:
<h1 class="h-card">
<span class="p-name">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined):
<h1 typeof="h-card">
<span property="p-name">
<span property="p-given-name">Chris</span>
<abbr property="p-additional-name">R.</abbr>
<span property="p-family-name">Messina</span>
</span>
</h1>
The similarity of these two markup examples implies that it may be possible to extend RDFa 1.1 compliant parsers to become compliant microformats2 parsers.