View source for microformats2-faq

{{DISPLAYTITLE:microformats2 FAQ}}

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.
<source lang=html4strict>
<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>
</source>
Here's how: 
* [[microformats2#backward_compatible|using microformats2 and backward compatible microformats]].

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 ==
{{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:
* 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 &lt;a> 'href' or &lt;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 &lt;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|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 <code>-vendorabbr-</code> immediately after a microformats2 prefix, where "vendorabbr" is an abbreviation for the company (e.g. stock symbol) or organiztion. E.g.
* <code>h-goog-volcano</code> for a proprietary "volcano" object
* <code>p-osm-shop</code> for 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 <code>-x-</code> immediately after a microformats2 prefix, e.g.:
* <code>h-x-test-fixture</code> for an experimental "text-fixture" format (e.g. for a [[test-suite]]).
* <code>p-x-prep-time</code> - 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 [http://indiewebcamp.com/checkin 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: <code>&lt;span class="p-name">&lt;/span></code>

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 ==
<span id="does_microformats_2_split_vocabularies_and_syntax">Q: How does microformats2 separate syntax and vocabularies?</span>

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>

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:

<source lang=html4strict>
<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>
</source>

Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined):

<source lang=html4strict>
<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>
</source>

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 ==
* [[microformats2]]
* [[microformats2-brainstorming]]
* [[microformats2-experimental-properties]]
* [[microformats2-prefixes]]
* [[microformats2-faq]]