issues: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(text moved from main page)
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(69 intermediate revisions by 11 users not shown)
Line 1: Line 1:
Issues which apply to more than one microforamt.
{{DISPLAYTITLE: Microformat Issues }}


This should be a brainstorming session trying to tackle such general problems as microformats implementation, microformats efficiency and other advanced concepts.
These are externally raised issues about microformats in general.


==Bloated Format==
Some issues may be ACCEPTED and perhaps cause changes or improved explanations in one or more specifications or microformats in general. Some issues may be REJECTED for a variety of brief reasons, and others contain longer discussions.


=== The Problem ===
As this is a general microformats issues page, please only note ''concrete'' real world issues. Theoretical issues may be deleted, as will any issues raised that do not contain documentation of specific real-world examples that use real-world microformats (not just brainstorms).
Unfortunately, current microformats implementation consume a vast amount of space. The complexity will increase even more, when wanting to ''solve/add'' more complex issues. A direct consequence of this is a '''bloated format''':
* some of the markup is really bloated
** instead of a number, we end sometimes with a whole '''new paragraph''' of markup
** however, in order to be complete, the markup might need to be so
** nevertheless, having a page with 1000 data points will be a horror scenario


Therefore, I proposed to open this new brainstorming session/page on how to efficiently implement the microformats in web pages.
Please be sure that an issue applies to more than one microformat or pattern, otherwise the issue should be raised on the format/pattern specific issues page. Please check [[issues-resolved]] and [[issues-closed]] to first see if your issue has a resolution.


=== Ideas/ Solutions ===
Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — [http://tantek.com/log/ Tantek]


If we think a little bit back about '''css''', one of the main reasons of its development was:
== Closed Issues ==
* to separate content from style
Resolved issues that have no further actions to take.
** page code becomes more easy to '''understand'''
* See [[issues-closed]]
** and to '''maintain'''
** and often the '''size''' shrinks significantly


We must learn this lesson when dealing with microformats. Specifically, the following issues are important:
== Resolved Issues ==
* extensive microformat markup inside the page code will significantly reduce the readability of the code
Resolved issues that have outstanding [[to-do]] items.
* repeating the markup will increase page size
* See [[issues-resolved]]
* it will become more difficult to maintain/change the page


'''Solution'''
== Issues ==
* '''define microformat classes'''
=== opened 2006 ===
** e.g. in the page header, or
** in a separate file (see later)
* define '''abbreviations''' to those classes
** use actually only the abbrevioations inside the web page, instead of the '''whole paragraph''' of markup


* define the microformat classes inside a '''separate file''' (similarly to the css)
<div class="hentry" id="hcard-vs-vcard-name">
** this file needs NOT to be downloaded automatically
{{OpenIssue}}
*** you do NOT need it for displaying the data
<span class="entry-summary author vcard">
*** it is only needed when wanting to import the data somewhere
<span class="published">2006-05-11</span>
*** most viewers, however, only view the data
[http://microformats.org/wiki/index.php?title=hcard-faq&diff=6324&oldid=6323 FAQ by <span class="fn">Brian Suda</span>], expanded/reraised by [[User:Tantek|Tantek]]
** let the browser automatically download this file, only IF:
</span>
*** there is enough bandwidth
<div class="entry-content discussion issues">
*** the user wants to copy that data
* <strong class="entry-title">why does hCard use "vcard" as the root class or hCalendar use "vevent"?</strong>
*** the user wants to explicitly save the whole page
** Originally partly [[hcard-faq#Why_does_hCard_use_vcard_as_the_root_class_name|an FAQ written by Brian Suda]], this slight inconsistency between the name of the format and the name of the root class name consistently causes confusion in a large percentage of newcomers to microformats. - [[User:Tantek|Tantek]]
** when the user wants to copy an item
*** Looks like a typo (just one letter difference)
*** the web browser should acces that ''microformats'' additional page and
*** Cognitive dissonance: saying "use hCard" but implying use "vcard" class name, or the implication causing one to just say "use vcard", e.g. [https://twitter.com/cssquirrel/status/129602573635289088 Kyle Weems]: <blockquote>I always end up saying "vcard" instead of "hcard" because I never write "hcard" in the code. It's weird having "two" formats that are 1:1.</blockquote>
*** download only the relevant class (NO need to actually download the whole page)
*** Ambiguity in discussions, e.g. put "vcard" in your HTML - meaning, class name, or a link to a .vcf file?
*** '''EXTEND html protocol to be able to download ''web-file/class-defined-inside-file'' '''without beeing necessary to download the whole file
*** Cognitive load: extra bit of information to remember when marking up a microformat
*** in contrast to [[hReview]], [[hListing]], [[hRecipe]], etc. which all have root class name same as name of microformat (albeit lowercased, however some publishers have used the 2nd-letter-uppercase version as the root class name, e.g. class="hReview", enough for Google's rich snippet parsers to liberally accept it, so those could be improved as well.).
** Though in microformats we believe very strongly in the [[principle]] of [[reuse]], we have to admit that in this case experience/evidence has shown that this may be a case where we re-used something too far beyond it's original meaning. Or perhaps we errantly called two slightly different things by the same name.
*** '''ACCEPTED PROPOSED RESOLUTION.''' In [[microformats-2]], all vocabularies are named the same as their root class names, e.g. "h-card", "h-event", "h-entry" etc. - [[User:Tantek|Tantek]]
</div>
</div>


=== Requirements ===
=== opened 2010 ===
Issues opened/raised in 2010.


New Tags:
<div class="hentry" id="class-collisions">
* '''<struct> ... </struct>''': like the C/C++ struct, will define the microformats structure
{{OpenIssue}}
* '''<v> ... </v>''': this will define the variable inside the ''struct'' that should be replaced
<span class="entry-summary author vcard">
* '''<v ... />''': similarly to above, but this will NOT be displayed by the browser
<span class="published">2010-08-24</span>
** '''<v>''' is a shorthand for '''var''', to further reduce file size
[http://html5doctor.com/microformats/#comment-10241 raised by <span class="fn">Wim</span>], expanded by [[User:Tantek|Tantek]]
</span>
<div class="entry-content discussion issues">
* <strong class="entry-title">microformats classes like 'url' or 'region' already in use</strong>. "Using class for the microformat markup is clearly a problem, in part because it’s so easy to overlap with other markup. Authors use classes like “url” or “region” all the time, and might not be aware of the hCard format. All sorts of markup might look like a microformat."
** There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly. - [[User:Tantek|Tantek]]
** ACCEPTED. Pretty sure this was raised before, in IRC/lists elsewhere, but this URL was the earliest one I could find to capture it. - [[User:Tantek|Tantek]]
** 2011-10-26 [https://twitter.com/richardtvaughan/status/129235473414631424 confirmed by Richard Vaughan]:
*** "... Microformats can screw with existing CSS rules. ..."
** [https://twitter.com/richardtvaughan/status/129236380873261057 and follow-up same day also]:
*** "microformats are the easiest as it's just CSS classes, but may be a pain to implement if those class names are already used."
** See also '''Beware of microformats/CSS naming collisions''' section in http://knol.google.com/k/google-rich-snippets-tips-and-tricks (no edit history, date unknown, found 2011-350)
** '''ACCEPTED. PROPOSED RESOLUTION.''' We are fixing this with [[microformats-2]], all property names have prefixes to avoid such collisions. E.g. 'url' becomes 'u-url' and 'region' becomes 'p-region'. See [[microformats-2#h-card|microformats 2: h-card properties]] for more. - [[User:Tantek|Tantek]]
</div>
</div>


=== Examples ===
=== opened 2011 ===
Issues opened/raised in 2011.


Lets take this code:
* ...
<pre><nowiki>
<div class="hcite">
  <div class="book">
  <span class="fn">Book Title</span>
  <div class="chapter">
      <span class="fn">Chapter Title</span>
  </div>
  </div>
</div>
</nowiki></pre>


We would define this in the header like this:
=== Template ===
<pre><nowiki>
{{issues-format}}
<struct>
MyName{
  <div class="hcite">
  <div class="book">
    <span class="fn"><v /></span>
    <div class="chapter">
      <span class="fn"><v /></span>
    </div>
  </div>
  </div>
}
</struct>
</nowiki></pre>


or in a separate microformats file (NO struct needed):
=== Format Specific Issues ===
<pre><nowiki>
Please raise format specific issues on their respective page(s):
MyName{
  <div class="hcite">
  <div class="book">
    <span class="fn"><v /></span>
    <div class="chapter">
      <span class="fn"><v /></span>
    </div>
  </div>
  </div>
}
</nowiki></pre>


Inside the web page we use:
* [[hatom-issues]]
<pre><nowiki>
* [[hcard-issues]]
<struct class="MyName">
** [[representative-hcard-issues]]
  <v>1st variable</v>
* [[hcalendar-issues]]
  <v>2nd variable</v>
* [[hlisting-issues]]
</struct>
* [[hresume-issues]]
</nowiki></pre>
* [[hreview-issues]]
* [[rel-values-issues]]
** [[rel-home-issues]]
** [[rel-license-issues]]
* [[vote-links-issues]]
* [[xfn-issues]]
* [[xfolk-issues]]
* [[xmdp-issues]]
* [[xoxo-issues]]
** [[xoxo-opml-issues]]


Issues regarding microformats in progress (brainstorms etc.) are documented on their respective pages.


IF, one variable should NOT be displayed by the browser, we would use <v val="..." /> instead (the ''val='' could be omitted), e.g.:
=== Pattern Specific Issues ===
<pre><nowiki>
Please raise pattern specific issues on the respective page:
<div class="geo">
  <abbr class="latitude" title="37.408183">N 37° 24.491</abbr>
  <abbr class="longitude" title="-122.13855">W 122° 08.313</abbr>
</div>
</nowiki></pre>


Would become:
*[[abbr-design-pattern-issues]]
* inside the microformats definition page write:
** [[accessibility-issues#abbr-design-pattern]].
<pre><nowiki>
*[[include-pattern-issues]]
MyGeoStructure{
* etc.
  <div class="geo">
  <abbr class="latitude" title=v><v /></abbr>
  <abbr class="longitude" title=v><v /></abbr>
  </div>
}
</nowiki></pre>


* the code inside the web page:
=== Domain Specific Issues ===
<pre><nowiki>
*[[accessibility-issues]]
<struct class="MyGeoStructure">
*[[code-issues]]
  <v "37.408183" /><v>N 37° 24.491</v>
*[[external-issues]]
  <v "-122.13855" /><v>W 122° 08.313</v>
*[[tests-issues]]
</struct>
</nowiki></pre>


 
==See also==
- discussion opened by [[discoleo|Leonard Mada]]
*[[accessibility]]
*[[criticism]]
*[[wiki-feedback]]
*The [[faq|microformats FAQ]], which answers many general criticisms/ issues that have been raised with microformats.

Latest revision as of 16:28, 18 July 2020


These are externally raised issues about microformats in general.

Some issues may be ACCEPTED and perhaps cause changes or improved explanations in one or more specifications or microformats in general. Some issues may be REJECTED for a variety of brief reasons, and others contain longer discussions.

As this is a general microformats issues page, please only note concrete real world issues. Theoretical issues may be deleted, as will any issues raised that do not contain documentation of specific real-world examples that use real-world microformats (not just brainstorms).

Please be sure that an issue applies to more than one microformat or pattern, otherwise the issue should be raised on the format/pattern specific issues page. Please check issues-resolved and issues-closed to first see if your issue has a resolution.

Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — Tantek

Closed Issues

Resolved issues that have no further actions to take.

Resolved Issues

Resolved issues that have outstanding to-do items.

Issues

opened 2006

open issue! 2006-05-11 FAQ by Brian Suda, expanded/reraised by Tantek

  • why does hCard use "vcard" as the root class or hCalendar use "vevent"?
    • Originally partly an FAQ written by Brian Suda, this slight inconsistency between the name of the format and the name of the root class name consistently causes confusion in a large percentage of newcomers to microformats. - Tantek
      • Looks like a typo (just one letter difference)
      • Cognitive dissonance: saying "use hCard" but implying use "vcard" class name, or the implication causing one to just say "use vcard", e.g. Kyle Weems:

        I always end up saying "vcard" instead of "hcard" because I never write "hcard" in the code. It's weird having "two" formats that are 1:1.

      • Ambiguity in discussions, e.g. put "vcard" in your HTML - meaning, class name, or a link to a .vcf file?
      • Cognitive load: extra bit of information to remember when marking up a microformat
      • in contrast to hReview, hListing, hRecipe, etc. which all have root class name same as name of microformat (albeit lowercased, however some publishers have used the 2nd-letter-uppercase version as the root class name, e.g. class="hReview", enough for Google's rich snippet parsers to liberally accept it, so those could be improved as well.).
    • Though in microformats we believe very strongly in the principle of reuse, we have to admit that in this case experience/evidence has shown that this may be a case where we re-used something too far beyond it's original meaning. Or perhaps we errantly called two slightly different things by the same name.
      • ACCEPTED PROPOSED RESOLUTION. In microformats-2, all vocabularies are named the same as their root class names, e.g. "h-card", "h-event", "h-entry" etc. - Tantek

opened 2010

Issues opened/raised in 2010.

open issue! 2010-08-24 raised by Wim, expanded by Tantek

  • microformats classes like 'url' or 'region' already in use. "Using class for the microformat markup is clearly a problem, in part because it’s so easy to overlap with other markup. Authors use classes like “url” or “region” all the time, and might not be aware of the hCard format. All sorts of markup might look like a microformat."
    • There has also been an anecdotal report of a design firm who was not (yet) familiar with microformats seeing the "extra" classes that "that don't seem to be used" (without corresponding CSS rules) and asking if they "can remove them". By making microformats class names different from generic words, authors unfamiliar with microformats may at least notice such distinction and infer special functionality accordingly. - Tantek
    • ACCEPTED. Pretty sure this was raised before, in IRC/lists elsewhere, but this URL was the earliest one I could find to capture it. - Tantek
    • 2011-10-26 confirmed by Richard Vaughan:
      • "... Microformats can screw with existing CSS rules. ..."
    • and follow-up same day also:
      • "microformats are the easiest as it's just CSS classes, but may be a pain to implement if those class names are already used."
    • See also Beware of microformats/CSS naming collisions section in http://knol.google.com/k/google-rich-snippets-tips-and-tricks (no edit history, date unknown, found 2011-350)
    • ACCEPTED. PROPOSED RESOLUTION. We are fixing this with microformats-2, all property names have prefixes to avoid such collisions. E.g. 'url' becomes 'u-url' and 'region' becomes 'p-region'. See microformats 2: h-card properties for more. - Tantek

opened 2011

Issues opened/raised in 2011.

  • ...

Template

Consider using this format (copy and paste this to the end of the list to add your issues; replace ~~~ with an external link if preferred) to report issues or feedback, so that issues can show up in hAtom subscriptions of this issues page. If open issues lack this markup, please add it.

Please post one issue per entry, to make them easier to manage. Avoid combining multiple issues into single reports, as this can confuse or muddle feedback, and puts a burden of separating the discrete issues onto someone else who 1. may not have the time, and 2. may not understand the issue in the same way as the original reporter.

<div class="hentry">
{{OpenIssue}} 
<span class="entry-summary author vcard">
 <span class="published">2011-MM-DD</span> 
 raised by <span class="fn">~~~</span>
</span>
<div class="entry-content discussion issues">
* <strong class="entry-title">«Short title of issue»</strong>. «Description of Issue»
** Follow-up comment #1
** Follow-up comment #2
</div>
</div>

Format Specific Issues

Please raise format specific issues on their respective page(s):

Issues regarding microformats in progress (brainstorms etc.) are documented on their respective pages.

Pattern Specific Issues

Please raise pattern specific issues on the respective page:

Domain Specific Issues

See also