hrecipe-issues: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (Reverted edits by I MADE THOUSANDS OF ACCOUNTS IN MICROFORMATS WIKI GO TO CHECK OUT THE USER LIST ([[User talk:I MADE THOUSANDS OF ACCOUNTS IN MICROF)
 
(52 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<entry-title>hRecipe issues</entry-title>
== issues ==
<span id="Issues">Please add new issues</span> to the '''bottom''' of this section by copy and pasting the [[hrecipe-issues#template|Template]]. Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues. Duplicate issue additions will be reverted.
 
 
<div class="vevent">
* {{OpenIssue}} <span class="summary vcard"><span class="dtstart">2009-01-22</span> raised by <span class="fn">[[User:ThomasLoertsch|ThomasLoertsch]]</span></span>
<div class="description">
* '''"num" and "unit"'''.  I only recently discovered the properties "type" and "value" from 'hCard'. I'll replace "num" and "unit" from the unfinished 'measure' with them.
** The decision to replace "num", "unit", and "item" with "type" and "value" needs further explanation. Was it due to the fact that measure is unfinished? If so I think leaving "ingredient" and "nutrition" as text strings until measure is finished would be a better idea. The transition from "type"/"value" to measure will be difficult at a later point and I believe measure is more appropriate than re-using hCard. [[User:Yde|Yde]] 11:46, 23 January 2009 (UTC)
*** The proposal to replace "num", "unit", and "item" with "type" and "value" has several reasons: first, i only recently thoroughly and systematically investgated other formats and that's when i found "type" and "value". They have a semantic advantage in that they may be more suitable for cases like value:"2"/type:"eggs" or value:"1/2"/type:"spoonfull" which are rather informal ways of putting measures, at least do not lend themselves easily to formal specification. Another reason is that these terms come from a comparably very stable vocabulary, while measure has not even draft status. It would be perfectly okay for measure to change attribute names, semantics or even the whole structure of the vocabulary. Although it doesn't look like that measure will (have to) do that I'd prefer to stay on the safe side, especially since we might even gain semantic advantage. [[User:ThomasLoertsch|ThomasLoertsch]] 19:43, 23 January 2009 (UTC)
**** I'm still not sure this is the right decision. 1) I don't think the semantic meaning of hCard's "type"/"value" is exactly equivalent to measure's "num"/"unit"/"item". From the [[hcard-profile]]: "Value: This class name is used to distinguish the actual *value* of a property from any other cruft that may be in the element representing the property." So what is the actual value of an ingredient? Is it the name of the ingredient or is the quantity? 2) This is ''exactly'' what [[measure]] is for. The advantage of being able to convert measures would IMO be one of the gratest advantages of hRecipe. I don't see why value:"2"/type:"eggs" is better than num:"2"/item:"eggs"? I agree that cases like value:"1/2"/type:"spoonfull" is problematic, but that's a [[measure]] issue. 3) Many [[recipe-formats]] use quantity/unit/item.
***** Measurements are rather informal in recipes and therefor the type/value pair seems quite appropriate to me. Automatic translation is out of scope. Anyway for a good enough machine translation of a recipe the markup of the ingredients won't be the main hurdle. Standardizing the informal quantities would be a requirement for such an effort. I made some suggestions for a vocabulary of most used "units" like cups, teespoonfulls etc a few months ago but no one reacted. So I dropped it.
***** But we're moving in circles. You are making valid points too. One reason I decided this way is that it's more inline with other decisions like reusing "fn". Since not all the shortcomings of microformats can be solved within hRecipe and since there has been no interest in discussing them here I decided to go the way of  least resistance and stick with the customs of compactness, reuse and rather lax interpretation of semantic constraints. IMO hRecipe is now consistent with the genereal microformats approach and neither necessitates nor hinders a general redesign of microformats (which I think would be a good thing). --[[User:ThomasLoertsch|ThomasLoertsch]] 11:21, 18 February 2009 (UTC)
**** Proposed resolution: keep "ingredient" as a text string like "yield" - which would also benefit from a measure format - until such a format is ready. [[User:Yde|Yde]] 10:23, 15 February 2009 (UTC)
***** I opened this issue again and marked the subproperty  'value' and 'type' of ingredient as ''experimental''. This should leave enough room to discuss this issue further. --[[User:ThomasLoertsch|ThomasLoertsch]] 11:21, 18 February 2009 (UTC)
</div>
</div>
 
 
<div class="vevent">
* {{OpenIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
<div class="description discussion issues">
# '''Too many properties.''' From reviewing the [[recipe-examples]], it does not appear that the schema implied by the examples justify the number of properties in hRecipe, especially for a first draft.  microformats should start as small as possible (even smaller), and in this regard I believe several improvements could be made. There is one obvious example of recipe-title vs recipe-summary, but it looks like there may be more.  Would appreciate feedback from folks who add hRecipe to the recipes on the web regarding which properties they ended up not using.
#* It is  not necessarily helpful to constrain a vocabulary by all means. hCard and hCalender are examples for too large vocabularies (which mostly stems from the approach taken of converting an existing vocab 1:1) which are not as easily usable as one would wish. But to be useful a vocabluary should encompass 80:20 of the usecases, otherwise it may well not be worth the burden of implementation. We better try to hit that sweet spot right from the start - since otherwise, how should hRecipe get traction in the wild. All of the proposed properties are used on big recipe sites (many 'user generated content' sites among them) on the web. Please provide more arguments which properties you specifically think are superfluous. The only concrete example you give is to replace title by summary (which I think is a bad idea).  [[User:ThomasLoertsch|ThomasLoertsch]]
#* Version 0.2 (and a little more so 0.21) has marked all but the most essential properties as ''experimental''. There use is not at all discouraged but implementors are warned that these properties may be removed from later version if they aren't used in real world applications. This uptake by implementors should be observed and studied before a final descision is made. A proposed timeframe would be at least a few months, maybe  even a year or two, depending on how many implemetations surface in the meantime. --[[User:ThomasLoertsch|ThomasLoertsch]] 11:21, 18 February 2009 (UTC)
#* I checked the usage of the hRecipe format today and was delighted to see that Yahoo! searchmonkey lists 56.000 of them (search Yahoo for "searchmonkey:com.yahoo.page.uf.recipe"). The site I work for is responsible for about 12.000 of them but when i checked the first 70 results none of them was from our site :-) In fact they almost all came from personal sites, blogs and the like and this is really great! It was also very interesting to see that a lot of them came from WordPress Blogs which shows that the WordPress Plugin for hRecipe is very useful. But back to the issue: I checked the first 60 or so results and about 2/3 of them where really using hRecipe. 17 of them were from different sites(*) (**).
 
It's never bad to gather some empirical data to make an informed decision, so I took the burden to count element use. Actually this didn't take much more then an hour, so if somebody wants to check the results from 61 to ... feel free! Well, now, without futher ado, the results:
<pre>
16  fn   
17  ingredient (3 value, 3 type)
  3  yield
15  instructions 
  3  duration
  4  photo
  9  summary
  4  author
  3  published
  1  nutrition (0 value, 0 type)
  2  tag
</pre>
Of course this is not representative, but it gives a fairly good impression. If you add our site (or 20% of all published hRecipes ;) you can add +1 to all elements since we use everything...
 
 
Evaluation:
 
"fn", "ingredient" and "instructions" are no-brainers. Also "summary" is surprisingly strong and the intuition, that it's a strong part of how people communicate on recipes, seems to be right.
 
"author" and "published" probably didn't get so much used because on a blog they are provided anyway and most of the sites investigated were blogs. OTOH they aren't important for the functionality of a recipe and can be added by other means. So maybe they should be removed for the sake of terseness.
 
"photo" was definitely less used than there were photos added to recipes. And I know a lot of people who, when showed 2 recipes, one with and one without photo, almost certainly choose the one with photo. So IMHO it should stay.
 
"yield" was used surprisingly seldomly. Isn't it an essential addition to the ingredients list? Maybe the yield is often self-explanatory, maybe this reflects the fact, that also the value and type of ingredients wasn't marked up most of the time. 'Smallishness' would certainly suggest to omit all the three: "value", "type" and yield". People seem to feel that the "ingredient" field naturally holds information not only about the name of the ingredient but about type and value too and don't bother to mark these up explicitly. Again for big sites which generate their content from databases the cost-benefit ratio is totally different...


This page reflects issues raised about the [[hRecipe]] microformat.
"duration" would be a candidate for removal as well. But still, remember that this list only reflects usage of the elements. An information of duration was part of the recipe more often than it was marked up as such.


Past issues captured during brainstorming towards hRecipe can be found in [[recipe-issues]].
"tag" obviously didn't get used much and is maybe strong enough on it's own. People add tags no matter if they are part of a vocabulary, and the rel-tag pattern is certainly easy enough to grasp and straightforward to implement.
But the WordPress plugin added a tagging vocabulary on it's own (how dare they... ;-) which did get used most of the time. So tagging principally is strong. Well, I still don't have a clue on this one.


Some issues may be REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions. Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec. Please read this page (and [[recipe-issues]]) carefully ''before'' giving any feedback or raising any issues as your feedback/issues may already be resolved/answered.
"nutrition" is definitely a candidate for removal, maybe into it's own vocabulary. OTOH, big commercially backed sites very often provide nutritional information and when provided it is a much more integral part of the information context than say the author. So maybe it should stay?
The full result-set, including URLs:
<pre>
    fn  ingredient v t  yield  instructions  duration  photo  summary  author  published  nutrition v t  tag
http://nissasham.blog.com/
    x    x                        x                                          x                    x              x
http://reciperiot.blog.com/
        x                                                                    x                                    x
http://www.greenworld365.com/twice-baked-buttermilk-potatoes/
    x    x
http://peachquilting.com/2009/04/beef-with-garlic-potatoes/  (wordpress plugin)
    x    x                        x                                  x
http://fivepennynicole.com/blog/2008/10/29/world-series-caramel-corn/  (wordpress plugin)
    x    x                        x                        x        x        x        x
http://www.theslowcook.com/2009/04/23/shrimp-stir-fry/ (wordpress plugin)
    x    x                        x
http://bitten.blogs.nytimes.com/2009/01/29/addictive-mac-and-cheese/    well ... very freestyle
    x    x                x      x
http://au.food.yahoo.com/recipes/recipe/-/5346170/baked-chicken-ravioli/
    x    x                x        x
http://humblegourmand.com/recipes/grovestand-lemon-cupcakes/
    x    x                x      x              x        x        x
http://www.f00die.com/
    x    x                        x                                  x
http://www.thebarkersworld.com/  (wordpress plugin)
    x    x                        x                                  x
http://www.murraywilliams.com/cooking/souffle.html
    x    x                        x                                  x
http://cookingwithbooze.org/beer/beer-brats/
    x    x                        x                                  x
http://itsripe.com/recipes/11-kale-smoothie
    x    x          x x          x              x          x        x        x      x
http://xavierroy.com/blog/chicken-legs-in-lemon-basil-mustard-sauce
    x    x          x x          x              x          x        x                x
http://www.f00die.com/2008/06/17/hobo-potatoes-w-arugula/
    x    x          x x          x
http://www.todayonpei.com/?p=5420
    x    x                        x
</pre>
 
 
(*) well, more of them, I skipped some WordPress Blogs since they all came from the same Plugin. But as the feature set of the Plugin continues to grow it doesn't make much sense to investigate them too thoroughly now unless you want to take into account which version of the plugin was used exactly etc etc - an undertaking I'm not really up to ;-)
 
(**) I felt quite bad when I saw that a lot of them used the pre-0.2 version with "title", "method" etc but I really don't know what I could do about it now (or then, too). I guess these decisions are made and the pain will diminish over time (cough).
--[[User:ThomasLoertsch|ThomasLoertsch]] 17:36, 17 June 2009 (UTC)
</div>
</div>
 
<div class="hentry">
{{OpenIssue}} <span class="entry-summary author vcard"><span class="published">2009-07-01</span> raised by <span class="fn">[[User:BenWard|BenWard]]</span></span>
<div class="entry-content discussion issues">
* <strong class="entry-title">Reconsidering semantic of <code>published</code> over ‘<code>created</code>’</strong>. I think the reuse of <code>published</code> from [[hAtom]] may be incorrect. Given its use in hAtom, <code>published</code> represents the date and time that the content was originally published to the page. In the case of a recipe, it seems that you would instead want to represent the date that the recipe was authored/created, which is subtly different. The publication of a recipe on a web page is something that should be done with hAtom itself (publishing an <code>hEntry</code> that contains the recipe), but the recipe itself would contain the date that ''the recipe itself'' was created. e.g. <samp>I came up with this recipe for mashed potato in &lt;span class='created'>&lt;span class='value-title' title='2008-08'>last summer&lt;/span>&lt;/span></samp>. I'm totally open to ideas about this, but my feeling is that it's unnecessary to represent the publication date since that should be represented by a complete hAtom entry. Do we think that <code>created</code> as described here falls inside the 80:20?
** I agree with your interpretation of "published" versus "created". "published" is not used very often on it's own (see above) and I'm sure "created" would be used much less so - because it often is very difficult to determine when a recipe was created, when it was modified enough to count as newly created, from where (and when) it originated etc. IMO "published" MAY be out of the 80:20, but "created" certainly IS. You raise a point though that I'm thinking heavily about right now. I'm pondering if it would be wise to move most of the properties that are currently marked as "experimental" out of the draft and refer to them only (but explicitly) as possibly useful additions to a hRecipe. I would then add hReview as well and, from the 'experimental' properties, only leave "Nutrition" within the property set of hRecipe. But I need to think about that a little more. Anyway: I think your point is valid but should be part of a broader approach. --[[User:ThomasLoertsch|ThomasLoertsch]] 15:09, 2 July 2009 (UTC)
</div>
</div>


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/ Tantek]
<div class="hentry">{{OpenIssue}}
<span class="entry-summary author vcard"><span class="published">2010-04-28</span> raised by <span class="fn">[[User:Phae|Phae]]</span></span><div class="entry-content discussion issues">* <strong class="entry-title">Describing variable durations of preparation time.</strong>. 
BBC food has a problem whereby they'd like to show duration of preparation time with a minimum/maximum value.  In plain english : "This recipe takes between 10 and 30 minutes to prepare".  Google Rich Snippets provides a mechanism to show min/max in prepTime (although at the moment their visual preview is failing to accurately display these values) - how could we make it easier to specify min/max duration values in hRecipe?  Reuse of duration is available, but is that sufficient? ISO time has been recommended for use, but this kind of value is not an interval of time.
* Could you post URLs to [[recipe-examples]] of real world recipe (perhaps from BBC) that have preparation time with minimum/maximum and perhaps expected/average durations in the visible content? Having the actual content and existing markup to view/analyze would greatly help inform a better solution. [[User:Tantek|Tantek]] 18:25, 29 April 2010 (UTC)
** Pretty much all of the BBC recipes have ranges for cooking/prep times, e.g. [http://www.bbc.co.uk/food/recipes/macaronicheese_83521 Macaroni Cheese] (cook time: min 0, max 30 mins; prep time: min 10 mins, max 30 mins), [http://www.bbc.co.uk/food/recipes/roastedchickenbreast_93803 Roasted chicken breast] (cook time: min 0, max 30 mins; prep time: min 1 hrs, max 2 hrs). Currently we're just taking the max value as the time value. [[User:Ironsidevsquincy|Ironsidevsquincy]] 16:56, 3 June 2010 (UTC)
</div>
</div>


If you have general feedback on hRecipe (positive/neutral/negative) please add to [[hrecipe-feedback]] rather than this document.
== resolved issues ==
<div class="vevent">
* {{ResolvedIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
<div class="description">
*# '''author is re-used from hAtom not hCard'''. minor issue. the "author" property is actually re-used from [[hAtom]] rather than hCard - hCard has no such property.
*#* Yikes! Corrected... [[User:ThomasLoertsch|ThomasLoertsch]] 17:52, 6 January 2009 (UTC)
</div>
</div>


== issues ==
<span id="Issues">Please add new issues</span> to the '''bottom''' of this section by copy and pasting the [[hrecipe-issues#template|Template]]. Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues. Duplicate issue additions will be reverted.


<div class="vevent">
<div class="vevent">
* {{OpenIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
* {{ResolvedIssue}}<span class="summary vcard"><span class="dtstart">2008-01-17</span> raised by <span class="fn">[[User:Yde|Yde]]</span></span>
<div class="description">
<div class="description">
*# '''Too many properties.''' From reviewing the [[recipe-examples]], it does not appear that the schema implied by the examples justify the number of properties in hRecipe, especially for a first draft.  microformats should start as small as possible (even smaller), and in this regard I believe several improvements could be made. There is one obvious example of recipe-title vs recipe-summary, but it looks like there may be more.  Would appreciate feedback from folks who add hRecipe to the recipes on the web regarding which properties they ended up not using.
* '''method'''. Would it make sense to [[reuse]] [[hreview|hReview's]] "description" instead of hRecipe's "method" or is this stretching the semantics too far?
*#* btw: this is not a first draft. a first draft has been around for over a year, a second draft for a few months. you are chiming in rather late - which is not a problem, but you should consider that a lot of thought already went into this format. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
** I just discovered that hCalender uses "method", and with totally different semantics. So I guess we MUST change it. I'm not very happy with "description" though - that's a very unspecific term. Maybe "instructions", or "steps", or "preparation" , or "procedure"? They are all 'available'. I like "instructions" most, but since I'm not a native speaker I'm hesitant. Maybe the semantics are too different? Maybe "preparation" is better since we already almost have it (or had it - see the discussion about "preparation-time" -> "duration" above)? [[User:ThomasLoertsch|ThomasLoertsch]] 12:24, 21 January 2009 (UTC)
*#* proposed resolution: Drop "recipe-title". In reviewing the examples, few (if any?) include *both* a title and a summary, and in practice the semantics of usage in the context of recipes appears to be virtually indistinguishable.  Therefore we don't need both, and following in the pattern provided by [[hCalendar]] (which got it from [[RFC2445]]), we should keep the more generic concept of a "summary" and drop the concept of "title" from hRecipe.
** Since no further comments surfaced I'll change the property name to "instructions". I think it's a fairly unambiguous name which also can easily be reused in other formats. [[User:ThomasLoertsch|ThomasLoertsch]] 14:30, 2 Febuary 2009 (UTC)
*#* hRecipe certainly is not a very short format, but that stems from the complexity of the topic. Other seemingly simple issues like vCards also have a lot of properties. 'Nutrition' could be a candidate for a microformat on it's own - but then, since it can be reused anyway, why bother? If your issue leads to the proposal that we should keep this in mind and wait for implementations to prove the point then I agree - although of course I think that it's as short as reasonably possible.I disagree with the proposed resolution though - title and summary are different things and they are used differently in the real world. They are wo different elements in Dublin Core and I find no Thesaurus listing them together. Plus I personally am not aware of any recipes that don't have a title. The summary could be dropped but to what advantage since you are right with your next point and summary is already defined elsewhere? The real problem lies in the usage of 'title' in hCard and can't be solved by shoehorning other titles in something else. [[User:ThomasLoertsch|TomLurge]] 17:52, 6 January 2009 (UTC)
</div>
*#*# Several problems with the reasoning above. First, assertion of "complexity of the topic" is insufficient. Per [[recipe-examples]] and rough 80% of the semantics implied therein - it is *not* a complex topic. Arguments from such data samples trumps any argument from theoretical complexity as we are going for a rough representation of real world use, not 99+% theoretical representation. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
</div>
*#*#*# Maybe "complex" is the wrong wording, but there certainly are a lot of properties to take into account. Anyway I would find it more helpfull if you could provide more insight what properties you specifically think are too much for a first draft. The only concrete example you give is the title, but you give no convincing argument for that. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
 
*#*# "hCard has lots of properties" is an insufficient justification for breaking any principles as the principles were derived from some of the experience gained (lessons learned) from the development of the early microformats like hCard and hCalendar. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
 
*#*# The use/assertion of "wait for implementation to prove the point" is assuming the wrong burden of proof.  The burden of proof is to demonstrate the need for more complexity not less. That is, with microformats, we prefer starting smaller rather than larger. This is one of the [[principles]]. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
<div class="vevent">
*#*# Reasoning by analogy/justification of Dublin Core is insufficient, because schema should always be based on real world samples of *data* not on other formats.  Also, the properties in Dublin Core are notoriously abstract/confusing/overloaded, and thus make a particularly poor base from which to reason from.  Similarly reasoning from an abstract thesaurus definition is insufficient, as the thesaurus definition itself is not based on any sampling of real world publication data. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
* {{ResolvedIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
*#*#*# So you're suggesting that Dublin Core or a Thesaurus are not based on real world data but are made up out of the abstract while only the real world examples gahered on this site are the real deal? Well... I don't see what's so very special about the microformats process that it can singlehandedly negate all the work other people have been doing. I can add some examples to the examples page, from sites that together make up the vast majority of recipes on the (english speaking) net (both by number and by visits). You'll find all the properties mentioned in the hRecipe format (and you'll certainly find that they all have a title). And I just double-checked the [[recipe-examples]] page: 'all' the recipe examples there have a title and in all but one cases it is called "title" too. It's very helpfull to have some process but almost all your argumentation centers around the process while you provide very little concrete criticism on the properties themselves. When the arguments center around the process rather than the subject at hand that's always is a good sign of a profoundly flawed process. [[User:ThomasLoertsch|TomLurge]] 16:00, 16 January 2009 (UTC)
<div class="description discussion issues">
*#*# Reasoning by absence of negative is flawed: "am not aware of any recipes that don't have a title" - absence of a negative cannot be used to prove an assertion to be true, only the possibility of being true. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
# '''Unnecessary recipe prefixing of summary property.''' Note: this is a re-opening of an issue from [[recipe-issues]]. The usage of summary in recipes appears to be very similar to that used for events. Rephrased, insufficient (if any?) evidence has been provided that summary means anything "special" enough (distinguishing it from the generic term "summary" as used in microformats) in the context of recipes to merit prefixing and thus a new property.
*#*#*# Get your logics right: double negation is the opposite of negation. You can easily reformulate my assertion to: "Almost all recipes I'm aware of do have a title". [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
#* proposed resolution: Re-use generic "summary" property rather than introducing a recipe microformat scoped "recipe-summary" property.
*#*# Finally, the "real" problem is not the use of "title" within hCard but rather that the term "title" has been so horribly overloaded across formats, vocabularies that it is nearly meaningless and for that reason should be avoided in any/all format efforts, preferring instead something more semantically specific such as "fn" (meaning full/formatted name of an item) or "summary" (when items are labeled more often with a short description/explanation rather than a name). [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
#* I agree principally but there are different "summary"s around: The [[hReview]]-Draft specifies a summary as "This optional field serves as a title for the review itself" while the [[hCalendar]] Draft refers to RFC 2445 which defines summary as "This property defines a short summary or subject for the calendar component". I certainly agree more with the semantics from RFC 2445 but referring to either of the two doesn't make much sense right now. Since you are editor of both hReview and hCalendar maybe you can clarify the subject?  If  hReview would be aligned with RFC 2445 then I would promote  dropping the prefix.[[User:ThomasLoertsch|ThomasLoertsch]] 17:52, 6 January 2009 (UTC)
*#*#*# There's no use in lamenting about the existence of synonyms and homonyms. That's the real world - "in the wild", as you love to refer to it. Also the word "title" is not horribly overloaded, you're exaggerating here. It just happened that hCard were the first to use it, and in a way that's empirically much less important then the use of "title" as the heading of a resource. Still the real problem is that Microformats have only one namespace and no resolution mechanism for conflicts like this, beside "first come first served" - which is a very unsatisfying mechanism. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
#** Agreed, the definitions of "summary" across hCalendar and hReview could be better converged. Please add this as an issue to both [[hcalendar-issues]] and [[hreview-issues]] and I'll follow-up there accordingly.  Given that is the path forward, let's fix this immediately in hRecipe now that the issue (and resolution) has been captured. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*# '''Unnecessary recipe prefixing of summary property.''' Note: this is a re-opening of an issue from [[recipe-issues]]. The usage of summary in recipes appears to be very similar to that used for events. Rephrased, insufficient (if any?) evidence has been provided that summary means anything "special" enough (distinguishing it from the generic term "summary" as used in microformats) in the context of recipes to merit prefixing and thus a new property.
#*** Will change "recipe-summary" to "summary" as defined in hCalender/RFC2445. [[User:ThomasLoertsch|ThomasLoertsch]] 15:00, 16 January 2009 (UTC)
*#* proposed resolution: Re-use generic "summary" property rather than introducing a recipe microformat scoped "recipe-summary" property.
*#* I agree principally but there are different "summary"s around: The [[hReview]]-Draft specifies a summary as "This optional field serves as a title for the review itself" while the [[hCalendar]] Draft refers to RFC 2445 which defines summary as "This property defines a short summary or subject for the calendar component". I certainly agree more with the semantics from RFC 2445 but referring to either of the two doesn't make much sense right now. Since you are editor of both hReview and hCalendar maybe you can clarify the subject?  If  hReview would be aligned with RFC 2445 then I would promote  dropping the prefix.[[User:ThomasLoertsch|TomLurge]] 17:52, 6 January 2009 (UTC)
*#** Agreed, the definitions of "summary" across hCalendar and hReview could be better converged. Please add this as an issue to both [[hcalendar-issues]] and [[hreview-issues]] and I'll follow-up there accordingly.  Given that is the path forward, let's fix this immediately in hRecipe now that the issue (and resolution) has been captured. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*#** I always prefer to leave other people some time (like some days) to make comments but if there will be no more comments I'll change "recipe-summary" to "summary" as defined in hCalender/RFC2445 durinng the next week. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
*# '''preparation-time could re-use duration instead''' - it appears that the "preparation-time" semantic basically means the "duration" of the recipe, and thus could re-use that property from [[hCalendar]] rather than introducing a new property name.
*#* proposed resolution: change "preparation-time" to "duration" and note re-use from [[hCalendar]] - or at least document how preparation-time is a different enough semantic from "duration" to justify the introduction of a new term.
*#* One difference is that hCalendar ''duration'' is a singular property whereas hRecipe's ''preparation-time'' is plural. Also, ''preparation-time'' will often (typically) use value+note subproperties, while ''duration'' will usually be an ISO 8601 duration. [[User:TobyInk|TobyInk]] 20:32, 29 December 2008 (UTC)
*#** Plurality is a contextual aspect and does not alter the semantic of the underlying property, thus is insufficient justification for introducing a new term.  We do not duplicates of each property in a singular and plural form. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*#** Syntax differences (value+note vs ISO 8601) are also insufficient to justify the introduction of a new property for the same semantic. Rather, it is better to expand the syntax of the existing property, e.g. perhaps using the [[value-excerption-pattern]] and to note that explicitly. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*#** If that's possible than it's okay with me to reuse "duration" with the mentioned syntactic differences. But I'm not sure if it helps usability to overload properties in such a way. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
*#** The observation that preparation-time uses a nested "note" subproperty may actually reveal a problem with that approach itself, that is, perhaps instead of "preparation-time" with "value" and "note" subproperties, it may be better to refactor it as a "preparation" (an act thereof) with "duration" and "note" subproperties. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*#** While semantically correct this would leave us with one more property, since "preparation" on itself, without a "duration"-subelement, wouldn't mae sense anymore. The real content that's of interest - the timespan needed - would reside only in the subelement. See [[recipe-issues]] for more discussion on this topic. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
*#* Also, if an hRecipe is nested within an hCalendar (e.g. a ''vtodo'' containing an hRecipe within the ''description''), we probably wouldn't want naïve hCalendar parsers using an hRecipe's cooking time as the entire duration of the hCalendar component. [[User:TobyInk|TobyInk]] 20:32, 29 December 2008 (UTC)
*#** This is a duplicate of similar issue(s) raised on hAudio and should be tracked there in [[haudio-issues]]. Parser implementation confusion/naïveté is insufficient to justify a corruption/compromise of the format. Data formats far outlast implementations. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
*#** I think the example is rather contrieved. I wouldn't expect microformats to handle such complex cases. [[User:ThomasLoertsch|TomLurge]] 15:00, 16 January 2009 (UTC)
*#* Although there is no such thing as a "duration of a recipe" the semantics are close enough to justify the reuse of "duration" from [[hCalendar]]. But hCalender is just a refactoring of RFC 2445 which demands ISO style durations which are rather un-intuitive and I would be more concerend about implementors turned away by such requirements than by too many properties. RFC 2445 permits multiple duration values "if the property permits" so that should be fine. Result: I don't know... Btw: hCalender needs more love if it's really meant to be reused. "... editor's note: this list is incomplete (an incomplete list is better than no list) and is being currently edited from RFC2445 to here." imho is not good enough, especially not for a 'specification'. And RFC 2445 is not exactly an easy read. [[User:ThomasLoertsch|TomLurge]] 17:52, 6 January 2009 (UTC)
*#** Agreed with the issues raised against hCalendar but please note them in [[hcalendar-issues]] for follow-up. Thanks! [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
</div>
</div>
</div>
</div>


== resolved issues ==
 
<div class="vevent">
<div class="vevent">
* {{ResolvedIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
* {{ResolvedIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span></span>
<div class="description discussion issues">
# '''preparation-time could re-use duration instead''' - it appears that the "preparation-time" semantic basically means the "duration" of the recipe, and thus could re-use that property from [[hCalendar]] rather than introducing a new property name.
#* proposed resolution: change "preparation-time" to "duration" and note re-use from [[hCalendar]] - or at least document how preparation-time is a different enough semantic from "duration" to justify the introduction of a new term.
#* One difference is that hCalendar ''duration'' is a singular property whereas hRecipe's ''preparation-time'' is plural. Also, ''preparation-time'' will often (typically) use value+note subproperties, while ''duration'' will usually be an ISO 8601 duration. [[User:TobyInk|TobyInk]] 20:32, 29 December 2008 (UTC)
#** Plurality is a contextual aspect and does not alter the semantic of the underlying property, thus is insufficient justification for introducing a new term.  We do not use duplicates of each property in a singular and plural form. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
#** Syntax differences (value+note vs ISO 8601) are also insufficient to justify the introduction of a new property for the same semantic. Rather, it is better to expand the syntax of the existing property, e.g. perhaps using the [[value-excerption-pattern]] and to note that explicitly. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
#*** Semantically the reuse of "duration" is okay.  RFC 2445 permits multiple duration values "if the property permits" so that should be fine too. If the syntactic differences can be worked out the way Tantek suggests above than it's okay with me to re-use "duration". I'm just not sure if it helps usability to overload properties in such a way but that ay be another discussion on it's own. [[User:ThomasLoertsch|ThomasLoertsch]] 15:00, 16 January 2009 (UTC)
#** The observation that preparation-time uses a nested "note" subproperty may actually reveal a problem with that approach itself, that is, perhaps instead of "preparation-time" with "value" and "note" subproperties, it may be better to refactor it as a "preparation" (an act thereof) with "duration" and "note" subproperties. [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
#*** Removed the sub-property "note" from the v_0.2 draft format since I now agree that it looks a little overengineered. [[User:ThomasLoertsch|ThomasLoertsch]] 12:47, 22 January 2009 (UTC)
</div>
</div>
<div class="vevent">
* {{ResolvedIssue}}  '''issues too long''' <span class="summary vcard"><span class="dtstart">2009-01-22</span> raised by <span class="fn">[[User:ThomasLoertsch|ThomasLoertsch]]</span></span>
<div class="description">
As threatened 2 weeks ago I heavily re-edited this page because discussions had become a little frayed (and heated at soem points). Have a look at the [http://microformats.org/wiki/index.php?title=hrecipe-issues&oldid=37788 previous version] for the full debate and feel free to re-edit this page if you find that I axed it too much. [[User:ThomasLoertsch|ThomasLoertsch]] 14:47, 2 February 2009 (UTC)
</div>
</div>
<div class="vevent">
* {{ResolvedIssue}} '''new draft'''<span class="summary vcard"><span class="dtstart">2009-01-22</span> raised by <span class="fn">[[User:ThomasLoertsch|ThomasLoertsch]]</span></span>
<div class="description">
<div class="description">
*# '''author is re-used from hAtom not hCard'''. minor issue. the "author" property is actually re-used from [[hAtom]] rather than hCard - hCard has no such property.
* The following is a proposal for draft 0.2, reflecting the issues discussed so far. "recipe-title" is replaced with "fn" from hCard (although I'm not convinced that this is a good idea),  "recipe-summary" with "summary", "num" and "unit" from the unfinished 'measure' with "type" and "value" from 'hCard' (i only recently discovered them...), "method" (wihch is already used by [[hCalendar]] with "instructions", "preparation-time" with "duration". Two "note"s are deleted for brevity. "summary", "nutrition", "author", "published" and "photo" are marked as 'experimental', meaning that they may be removed from future drafts or the final specification, depending on experience and feedback from implementations :
*#* Yikes! Corrected... [[User:ThomasLoertsch|TomLurge]] 17:52, 6 January 2009 (UTC)
</div>
</div>
=== '''hrecipe'''. Proposal for Draft 0.2 ===
* '''fn'''. the name of the recipe. required. text. re-used from [[hCard]]
* '''ingredient''' required. 1 or more. text with optional valid (x)HTML markup.
** '''value''' and '''type'''. optional. re-used from [[hCard]].
* '''yield'''. optional. text.
* '''instructions'''. optional. text with optional valid (x)HTML markup.
* '''duration'''. optional. 1 or more. text (see [[ISO-31-1]] duration brainstorming). re-used from [[hCalendar]].
* '''''summary'''''. optional. text. re-used from [[hCalendar]]. [ ''experimental'' ]
* '''''nutrition'''''. optional. 1 or more. [ ''experimental'' ].
** '''''value''''' and '''''type'''''. optional. re-used from [[hCard]]. [ ''experimental'' ].
* '''''author'''''. optional. 1 or more. re-used from [[hAtom]] using [[hCard]]. [ ''experimental'' ].
* '''''published'''''. optional. re-used from [[hAtom]]. [ ''experimental'' ].
* '''''photo'''''. optional. 1 or more. using any element containing a URL, such as IMG. re-used from [[hCard]]. [ ''experimental'' ].
* '''''tag'''''. optional. 1 or more.  [ ''experimental'' ].
--[[User:ThomasLoertsch|ThomasLoertsch]] 11:01, 10 February 2009 (UTC)
** <strong id="issue-20100325">The above seems to use ''value'' very differently to other microformats</strong>. In other microformats it's used for [[value-class-pattern|value excerpting]] in most properties (i.e. the ''value'' class is used to indicate which text should be parsed with the rest being ignored); and in a handful of particular properties (e.g. hCard tel, email, adr, label) it's used in the ''value''+''type'' combination to indicate the main text that should be parsed while ''type'' refines the meaning of the property. In a recipe ingredient, the main idea to get across would be the ingredient itself (e.g. eggs, whisky, cardamom), so if ''value'' were to be used, you'd expect it to be more like this: <code>&lt;li class="ingredient">2 &lt;span class="value">eggs&lt;/span>, lightly whisked&lt;/li></code>. Wrapping <code>class=value</code> around the '2' is fairly at odds with how that class is used in other microformats. [[User:TobyInk|TobyInk]] 15:44, 25 March 2010 (UTC)
*** Suggestion: remove these subproperties from the ingredient and nutrition properties. [[User:TobyInk|TobyInk]] 15:44, 25 March 2010 (UTC)
</div>
</div>
**** +1 I concur with Toby's analysis and recommendation. [[User:Tantek|Tantek]] 17:30, 25 March 2010 (UTC)


== closed issues ==
== closed issues ==
* none currently
 
 
<div class="vevent">
* {{ClosedIssue}} <span class="summary vcard"><span class="dtstart">2008-12-27</span> raised by <span class="fn">[[User:Tantek|Tantek Çelik]]</span> in the context of issue '''Too many properties'''</span>
<div class="description discussion issues">
# '''Drop "recipe-title".''' In reviewing the examples, few (if any?) include *both* a title and a summary, and in practice the semantics of usage in the context of recipes appears to be virtually indistinguishable.  Therefore we don't need both, and following in the pattern provided by [[hCalendar]] (which got it from [[RFC2445]]), we should keep the more generic concept of a "summary" and drop the concept of "title" from hRecipe.
#* I tend to agree. There are definitely use cases for both "recipe-title/title/fn" and "recipe-summary/summary" - e.g. "[http://www.simonwheatley.co.uk/2006/03/26/a-moroccan-ish-casserole/ A Moroccan-ish Casserole]" sounds more like a summary while "[http://blog.bumblepuppy.org.uk/2006/10/05/spaghetti-primavera/ Spaghetti primavera]" is the full name or the title of the recipe. But the problem is, they would serve the same purpose. [[User:Yde|Yde]] 10:07, 17 January 2009 (UTC)
#** Title and summary are different things and they are used differently in the real world. The examples you give are both names/titles/labels/headings, although more or less descriptive. They are short, memorable and make the thing adressable by humans. A summary can be (and mostly is) much longer and serves a different purpose: it describes essential properties of the object at hand, eg: "this is easy and fast to prepare, but still looks impressive", "easy, tasty, fast, vegan, good on cold days" or "the kids loved this last summer, but the ingredients can be hard to get" or "whenever i cook this i start to dream of ..." [[User:ThomasLoertsch|ThomasLoertsch]] 14:25, 20 January 2009 (UTC)
#*** Right, on second thought, I believe "title/name" and "summary" are different things. [[User:Yde|Yde]] 11:22, 23 January 2009 (UTC)
#* The term "title" has been so horribly overloaded across formats, vocabularies that it is nearly meaningless and for that reason should be avoided in any/all format efforts, preferring instead something more semantically specific such as "fn" (meaning full/formatted name of an item) or "summary" (when items are labeled more often with a short description/explanation rather than a name). [[User:Tantek|Tantek]] 20:54, 15 January 2009 (UTC)
#** Synonyms and homonyms are part of the real world - we have to cope with them. Also the word "title" is not horribly overloaded, you're exaggerating here. It just happened that hCard were the first to use it, and in a way that's empirically much less important then the use of "title" as the heading of a resource. Still the real problem is that Microformats have only one namespace and no resolution mechanism for conflicts like this, beside "first come first served". [[User:ThomasLoertsch|ThomasLoertsch]] 15:00, 16 January 2009 (UTC)
#** Maybe it would be better to make a clear cut with some of the sins of the past and deprecate some terms in hCard / hCalendar[[User:ThomasLoertsch|ThomasLoertsch]] 15:30, 3 February 2009 (UTC)
#* "fn" is [[existing-classes|defined]] as "the name of the object" which is pretty much what "recipe-title" means right now. So, whether we chose to keep this property, summary, or both, renaming "recipe-title" to "fn" would make sense. [[User:Yde|Yde]] 23:03, 16 January 2009 (UTC)
#** the definition of "fn" in [[existing-classes|existing classes]] is maybe a little too short. "fn" is defined in hCard which is a reformulation of RFC 2462, which says: "Type name:FN - Type purpose: To specify the formatted text corresponding to the name of the object the vCard represents. -Type special notes: This type is based on the semantics of the X.520 Common Name attribute. The property MUST be present in the vCard object. - Type example:  'FN:Mr. John Q. Public\, Esq.'" (http://www.ietf.org/rfc/rfc2426.txt, on page 8). That clearly means a name of a person or an institution. Institution equals a juristical person, so "fn" semantically boils down to 'name of a person'. I wouldn't use that for every object.  [[User:ThomasLoertsch|ThomasLoertsch]] 14:03, 20 January 2009 (UTC)
#*** Thanks for the clarification. "fn" is definitely not a good idea. [[User:Yde|Yde]] 10:00, 23 January 2009 (UTC)
#*** <code>fn</code> is already reused more generically in hAudio, hReview and hListing (for items). The definition of use within microformats has already been adapted from the strict vcard interpretation in prior work. --[[User:BenWard|BenWard]] 23:04, 27 January 2009 (UTC)
#**** I see. I can't help but thinking: what a mess... What's the family name of a recipe, audio-recording or list-entry? What's the point of re-using a semantically totally void two-letter-acronym, when it doesn't even fit very well? What's the point of reusing an element when I have to lookup the meaning of it every time anyway? [[User:ThomasLoertsch|ThomasLoertsch]] 00:48, 28 January 2009 (UTC)
#***** <code>fn</code> is ''formatted''-name, not ‘family’. ‘Name as presented’, ‘display name’. I agree that <code>fn</code> takes a double glance when you're learning, but it's there and the reuse in other specs is consistent; there's a much stronger author benefit in building on common equivalent-semantic vocabulary than introducing synonyms, which I think will cause more confusion. Better to have a strong spec with common vocabulary than introduce duplication. I'll keep in mind that we should better emphasise the expansion of <code>fn</code> in all specs for benefit of new authors. I can see how ‘family name’ is a muddle too easily made in hCard. --[[User:BenWard|BenWard]] 07:01, 28 January 2009 (UTC)
#****** I was referring to the fact that a name of a natural or juridical person is semantically quite different to the name of an object. Other things like the opacity of the two-letter-code "fn" are indeed problematic too but not my main issue here. That vCard-legacy seems to be lurking around every corner. Why not make a clear cut and deprecate the problematic parts like "title" and "fn"? The approach to rather overload the semantics (and the property-constraints) just to keep element-count low only takes that far. In the end it hinders usability instead of improving it. I think [[reuse]] and [[naming-principles]] don't strike the right balance in that respect. [[User:ThomasLoertsch|ThomasLoertsch]] 11:45, 28 January 2009 (UTC)
#* why not define a property "name"?! From my understanding of the english language (I'm not a native speaker)  "name" is semantically generic enough to  serve as a substitute for "title". Defining it rather broadly as "designation or title or denominator or heading of an item" would make it easily reusable. Plus we would have to explicitely discourage it's use for naming real or juristical persons and point to "fn" instead. [[User:ThomasLoertsch|ThomasLoertsch]] 12:21, 21 January 2009 (UTC)
#** Hmmm. I would really like to get feedback on this... Again my argumentation:
#*** <code>title</code> would be the best solution but is already "taken". Depercating some of hCalenders sins would be the best solution but seems out of reach so far.
#*** <code>heading</code> would be a possible solution either but seems more suited for prose
#*** <code>name</code> gets the semantics quite well, especially in the case of recipes which are more a "thing" or abstract conceptualization than a work of literature/science/prose
#*** <code>fn</code> with it's subproperties is geared towards natural and juristical persons, which are quite different from things and concepts. Also semantics of the term "fn" are rather opaque, even misleading, which hinder it's usability.
#** Therefor I'd love "title", could live very well with "name", could live still well with "heading" and would sleep bad (but sleep) with "fn". [[User:ThomasLoertsch|ThomasLoertsch]] 16:30, 2 Febuary 2009 (UTC)
#** Okay, since there's no response I bow my head to "fn". But it speaks for itself that it's the only tag that has to be explained in the schema.  [[User:ThomasLoertsch|ThomasLoertsch]] 11:15, 10 February 2009 (UTC)
</div>
</div>
 
 
 
 


===template===
===template===
{{issues-format}}
{{issues-format}}


== related pages ==
==related pages==
* [[hRecipe]]
* [[hRecipe]]
* [[hrecipe-feedback|hRecipe feedback]] for general feedback on hRecipe.
* [[hrecipe-feedback|hRecipe feedback]] - general feedback regarding hRecipe
* [[recipe]] microformat effort development
 
* [[recipe-issues]] past issues raised and resolved during [[recipe-brainstorming]] towards the development of hRecipe.
Per the microformats [[process]], the [[recipe]] effort developed
* [[recipe-examples]]
* [[recipe-formats]]
* [[recipe-brainstorming]] (see also [[recipe-brainstorming-archive]])
* [[recipe-issues]]
towards the development of this draft.

Latest revision as of 11:09, 22 September 2013

issues

Please add new issues to the bottom of this section by copy and pasting the Template. Please follow-up to resolved/rejected issues with new information rather than resubmitting such issues. Duplicate issue additions will be reverted.


  • "num" and "unit". I only recently discovered the properties "type" and "value" from 'hCard'. I'll replace "num" and "unit" from the unfinished 'measure' with them.
    • The decision to replace "num", "unit", and "item" with "type" and "value" needs further explanation. Was it due to the fact that measure is unfinished? If so I think leaving "ingredient" and "nutrition" as text strings until measure is finished would be a better idea. The transition from "type"/"value" to measure will be difficult at a later point and I believe measure is more appropriate than re-using hCard. Yde 11:46, 23 January 2009 (UTC)
      • The proposal to replace "num", "unit", and "item" with "type" and "value" has several reasons: first, i only recently thoroughly and systematically investgated other formats and that's when i found "type" and "value". They have a semantic advantage in that they may be more suitable for cases like value:"2"/type:"eggs" or value:"1/2"/type:"spoonfull" which are rather informal ways of putting measures, at least do not lend themselves easily to formal specification. Another reason is that these terms come from a comparably very stable vocabulary, while measure has not even draft status. It would be perfectly okay for measure to change attribute names, semantics or even the whole structure of the vocabulary. Although it doesn't look like that measure will (have to) do that I'd prefer to stay on the safe side, especially since we might even gain semantic advantage. ThomasLoertsch 19:43, 23 January 2009 (UTC)
        • I'm still not sure this is the right decision. 1) I don't think the semantic meaning of hCard's "type"/"value" is exactly equivalent to measure's "num"/"unit"/"item". From the hcard-profile: "Value: This class name is used to distinguish the actual *value* of a property from any other cruft that may be in the element representing the property." So what is the actual value of an ingredient? Is it the name of the ingredient or is the quantity? 2) This is exactly what measure is for. The advantage of being able to convert measures would IMO be one of the gratest advantages of hRecipe. I don't see why value:"2"/type:"eggs" is better than num:"2"/item:"eggs"? I agree that cases like value:"1/2"/type:"spoonfull" is problematic, but that's a measure issue. 3) Many recipe-formats use quantity/unit/item.
          • Measurements are rather informal in recipes and therefor the type/value pair seems quite appropriate to me. Automatic translation is out of scope. Anyway for a good enough machine translation of a recipe the markup of the ingredients won't be the main hurdle. Standardizing the informal quantities would be a requirement for such an effort. I made some suggestions for a vocabulary of most used "units" like cups, teespoonfulls etc a few months ago but no one reacted. So I dropped it.
          • But we're moving in circles. You are making valid points too. One reason I decided this way is that it's more inline with other decisions like reusing "fn". Since not all the shortcomings of microformats can be solved within hRecipe and since there has been no interest in discussing them here I decided to go the way of least resistance and stick with the customs of compactness, reuse and rather lax interpretation of semantic constraints. IMO hRecipe is now consistent with the genereal microformats approach and neither necessitates nor hinders a general redesign of microformats (which I think would be a good thing). --ThomasLoertsch 11:21, 18 February 2009 (UTC)
        • Proposed resolution: keep "ingredient" as a text string like "yield" - which would also benefit from a measure format - until such a format is ready. Yde 10:23, 15 February 2009 (UTC)
          • I opened this issue again and marked the subproperty 'value' and 'type' of ingredient as experimental. This should leave enough room to discuss this issue further. --ThomasLoertsch 11:21, 18 February 2009 (UTC)


  1. Too many properties. From reviewing the recipe-examples, it does not appear that the schema implied by the examples justify the number of properties in hRecipe, especially for a first draft. microformats should start as small as possible (even smaller), and in this regard I believe several improvements could be made. There is one obvious example of recipe-title vs recipe-summary, but it looks like there may be more. Would appreciate feedback from folks who add hRecipe to the recipes on the web regarding which properties they ended up not using.
    • It is not necessarily helpful to constrain a vocabulary by all means. hCard and hCalender are examples for too large vocabularies (which mostly stems from the approach taken of converting an existing vocab 1:1) which are not as easily usable as one would wish. But to be useful a vocabluary should encompass 80:20 of the usecases, otherwise it may well not be worth the burden of implementation. We better try to hit that sweet spot right from the start - since otherwise, how should hRecipe get traction in the wild. All of the proposed properties are used on big recipe sites (many 'user generated content' sites among them) on the web. Please provide more arguments which properties you specifically think are superfluous. The only concrete example you give is to replace title by summary (which I think is a bad idea). ThomasLoertsch
    • Version 0.2 (and a little more so 0.21) has marked all but the most essential properties as experimental. There use is not at all discouraged but implementors are warned that these properties may be removed from later version if they aren't used in real world applications. This uptake by implementors should be observed and studied before a final descision is made. A proposed timeframe would be at least a few months, maybe even a year or two, depending on how many implemetations surface in the meantime. --ThomasLoertsch 11:21, 18 February 2009 (UTC)
    • I checked the usage of the hRecipe format today and was delighted to see that Yahoo! searchmonkey lists 56.000 of them (search Yahoo for "searchmonkey:com.yahoo.page.uf.recipe"). The site I work for is responsible for about 12.000 of them but when i checked the first 70 results none of them was from our site :-) In fact they almost all came from personal sites, blogs and the like and this is really great! It was also very interesting to see that a lot of them came from WordPress Blogs which shows that the WordPress Plugin for hRecipe is very useful. But back to the issue: I checked the first 60 or so results and about 2/3 of them where really using hRecipe. 17 of them were from different sites(*) (**).

It's never bad to gather some empirical data to make an informed decision, so I took the burden to count element use. Actually this didn't take much more then an hour, so if somebody wants to check the results from 61 to ... feel free! Well, now, without futher ado, the results:

 16   fn    
 17   ingredient (3 value, 3 type)
  3   yield 
 15   instructions  
  3   duration 
  4   photo
  9   summary
  4   author
  3   published
  1   nutrition (0 value, 0 type)
  2   tag

Of course this is not representative, but it gives a fairly good impression. If you add our site (or 20% of all published hRecipes ;) you can add +1 to all elements since we use everything...


Evaluation:

"fn", "ingredient" and "instructions" are no-brainers. Also "summary" is surprisingly strong and the intuition, that it's a strong part of how people communicate on recipes, seems to be right.

"author" and "published" probably didn't get so much used because on a blog they are provided anyway and most of the sites investigated were blogs. OTOH they aren't important for the functionality of a recipe and can be added by other means. So maybe they should be removed for the sake of terseness.

"photo" was definitely less used than there were photos added to recipes. And I know a lot of people who, when showed 2 recipes, one with and one without photo, almost certainly choose the one with photo. So IMHO it should stay.

"yield" was used surprisingly seldomly. Isn't it an essential addition to the ingredients list? Maybe the yield is often self-explanatory, maybe this reflects the fact, that also the value and type of ingredients wasn't marked up most of the time. 'Smallishness' would certainly suggest to omit all the three: "value", "type" and yield". People seem to feel that the "ingredient" field naturally holds information not only about the name of the ingredient but about type and value too and don't bother to mark these up explicitly. Again for big sites which generate their content from databases the cost-benefit ratio is totally different...

"duration" would be a candidate for removal as well. But still, remember that this list only reflects usage of the elements. An information of duration was part of the recipe more often than it was marked up as such.

"tag" obviously didn't get used much and is maybe strong enough on it's own. People add tags no matter if they are part of a vocabulary, and the rel-tag pattern is certainly easy enough to grasp and straightforward to implement. But the WordPress plugin added a tagging vocabulary on it's own (how dare they... ;-) which did get used most of the time. So tagging principally is strong. Well, I still don't have a clue on this one.

"nutrition" is definitely a candidate for removal, maybe into it's own vocabulary. OTOH, big commercially backed sites very often provide nutritional information and when provided it is a much more integral part of the information context than say the author. So maybe it should stay? The full result-set, including URLs:

    fn   ingredient v t   yield   instructions   duration   photo   summary   author   published   nutrition v t   tag
http://nissasham.blog.com/
    x    x                        x                                           x                    x               x
http://reciperiot.blog.com/
        x                                                                     x                                    x
http://www.greenworld365.com/twice-baked-buttermilk-potatoes/
    x    x
http://peachquilting.com/2009/04/beef-with-garlic-potatoes/  (wordpress plugin)
    x    x                        x                                  x
http://fivepennynicole.com/blog/2008/10/29/world-series-caramel-corn/  (wordpress plugin)
    x    x                        x                         x        x        x        x
http://www.theslowcook.com/2009/04/23/shrimp-stir-fry/ (wordpress plugin)
    x    x                        x
http://bitten.blogs.nytimes.com/2009/01/29/addictive-mac-and-cheese/    well ... very freestyle
    x    x                x       x
http://au.food.yahoo.com/recipes/recipe/-/5346170/baked-chicken-ravioli/
    x    x                x        x
http://humblegourmand.com/recipes/grovestand-lemon-cupcakes/
    x    x                x       x               x         x        x
http://www.f00die.com/
    x    x                        x                                  x
http://www.thebarkersworld.com/  (wordpress plugin)
    x    x                        x                                  x
http://www.murraywilliams.com/cooking/souffle.html
    x    x                        x                                  x
http://cookingwithbooze.org/beer/beer-brats/
    x    x                        x                                  x
http://itsripe.com/recipes/11-kale-smoothie
    x    x           x x          x              x          x        x        x       x
http://xavierroy.com/blog/chicken-legs-in-lemon-basil-mustard-sauce
    x    x           x x          x              x          x        x                x
http://www.f00die.com/2008/06/17/hobo-potatoes-w-arugula/
    x    x           x x          x
http://www.todayonpei.com/?p=5420
    x    x                        x


(*) well, more of them, I skipped some WordPress Blogs since they all came from the same Plugin. But as the feature set of the Plugin continues to grow it doesn't make much sense to investigate them too thoroughly now unless you want to take into account which version of the plugin was used exactly etc etc - an undertaking I'm not really up to ;-)

(**) I felt quite bad when I saw that a lot of them used the pre-0.2 version with "title", "method" etc but I really don't know what I could do about it now (or then, too). I guess these decisions are made and the pain will diminish over time (cough). --ThomasLoertsch 17:36, 17 June 2009 (UTC)

open issue! 2009-07-01 raised by BenWard

  • Reconsidering semantic of published over ‘created. I think the reuse of published from hAtom may be incorrect. Given its use in hAtom, published represents the date and time that the content was originally published to the page. In the case of a recipe, it seems that you would instead want to represent the date that the recipe was authored/created, which is subtly different. The publication of a recipe on a web page is something that should be done with hAtom itself (publishing an hEntry that contains the recipe), but the recipe itself would contain the date that the recipe itself was created. e.g. I came up with this recipe for mashed potato in <span class='created'><span class='value-title' title='2008-08'>last summer</span></span>. I'm totally open to ideas about this, but my feeling is that it's unnecessary to represent the publication date since that should be represented by a complete hAtom entry. Do we think that created as described here falls inside the 80:20?
    • I agree with your interpretation of "published" versus "created". "published" is not used very often on it's own (see above) and I'm sure "created" would be used much less so - because it often is very difficult to determine when a recipe was created, when it was modified enough to count as newly created, from where (and when) it originated etc. IMO "published" MAY be out of the 80:20, but "created" certainly IS. You raise a point though that I'm thinking heavily about right now. I'm pondering if it would be wise to move most of the properties that are currently marked as "experimental" out of the draft and refer to them only (but explicitly) as possibly useful additions to a hRecipe. I would then add hReview as well and, from the 'experimental' properties, only leave "Nutrition" within the property set of hRecipe. But I need to think about that a little more. Anyway: I think your point is valid but should be part of a broader approach. --ThomasLoertsch 15:09, 2 July 2009 (UTC)
open issue! 2010-04-28 raised by Phae
* Describing variable durations of preparation time..

BBC food has a problem whereby they'd like to show duration of preparation time with a minimum/maximum value. In plain english : "This recipe takes between 10 and 30 minutes to prepare". Google Rich Snippets provides a mechanism to show min/max in prepTime (although at the moment their visual preview is failing to accurately display these values) - how could we make it easier to specify min/max duration values in hRecipe? Reuse of duration is available, but is that sufficient? ISO time has been recommended for use, but this kind of value is not an interval of time.

  • Could you post URLs to recipe-examples of real world recipe (perhaps from BBC) that have preparation time with minimum/maximum and perhaps expected/average durations in the visible content? Having the actual content and existing markup to view/analyze would greatly help inform a better solution. Tantek 18:25, 29 April 2010 (UTC)
    • Pretty much all of the BBC recipes have ranges for cooking/prep times, e.g. Macaroni Cheese (cook time: min 0, max 30 mins; prep time: min 10 mins, max 30 mins), Roasted chicken breast (cook time: min 0, max 30 mins; prep time: min 1 hrs, max 2 hrs). Currently we're just taking the max value as the time value. Ironsidevsquincy 16:56, 3 June 2010 (UTC)

resolved issues

    1. author is re-used from hAtom not hCard. minor issue. the "author" property is actually re-used from hAtom rather than hCard - hCard has no such property.


  • resolved issue2008-01-17 raised by Yde
  • method. Would it make sense to reuse hReview's "description" instead of hRecipe's "method" or is this stretching the semantics too far?
    • I just discovered that hCalender uses "method", and with totally different semantics. So I guess we MUST change it. I'm not very happy with "description" though - that's a very unspecific term. Maybe "instructions", or "steps", or "preparation" , or "procedure"? They are all 'available'. I like "instructions" most, but since I'm not a native speaker I'm hesitant. Maybe the semantics are too different? Maybe "preparation" is better since we already almost have it (or had it - see the discussion about "preparation-time" -> "duration" above)? ThomasLoertsch 12:24, 21 January 2009 (UTC)
    • Since no further comments surfaced I'll change the property name to "instructions". I think it's a fairly unambiguous name which also can easily be reused in other formats. ThomasLoertsch 14:30, 2 Febuary 2009 (UTC)


  1. Unnecessary recipe prefixing of summary property. Note: this is a re-opening of an issue from recipe-issues. The usage of summary in recipes appears to be very similar to that used for events. Rephrased, insufficient (if any?) evidence has been provided that summary means anything "special" enough (distinguishing it from the generic term "summary" as used in microformats) in the context of recipes to merit prefixing and thus a new property.
    • proposed resolution: Re-use generic "summary" property rather than introducing a recipe microformat scoped "recipe-summary" property.
    • I agree principally but there are different "summary"s around: The hReview-Draft specifies a summary as "This optional field serves as a title for the review itself" while the hCalendar Draft refers to RFC 2445 which defines summary as "This property defines a short summary or subject for the calendar component". I certainly agree more with the semantics from RFC 2445 but referring to either of the two doesn't make much sense right now. Since you are editor of both hReview and hCalendar maybe you can clarify the subject? If hReview would be aligned with RFC 2445 then I would promote dropping the prefix.ThomasLoertsch 17:52, 6 January 2009 (UTC)
      • Agreed, the definitions of "summary" across hCalendar and hReview could be better converged. Please add this as an issue to both hcalendar-issues and hreview-issues and I'll follow-up there accordingly. Given that is the path forward, let's fix this immediately in hRecipe now that the issue (and resolution) has been captured. Tantek 20:54, 15 January 2009 (UTC)
        • Will change "recipe-summary" to "summary" as defined in hCalender/RFC2445. ThomasLoertsch 15:00, 16 January 2009 (UTC)


  1. preparation-time could re-use duration instead - it appears that the "preparation-time" semantic basically means the "duration" of the recipe, and thus could re-use that property from hCalendar rather than introducing a new property name.
    • proposed resolution: change "preparation-time" to "duration" and note re-use from hCalendar - or at least document how preparation-time is a different enough semantic from "duration" to justify the introduction of a new term.
    • One difference is that hCalendar duration is a singular property whereas hRecipe's preparation-time is plural. Also, preparation-time will often (typically) use value+note subproperties, while duration will usually be an ISO 8601 duration. TobyInk 20:32, 29 December 2008 (UTC)
      • Plurality is a contextual aspect and does not alter the semantic of the underlying property, thus is insufficient justification for introducing a new term. We do not use duplicates of each property in a singular and plural form. Tantek 20:54, 15 January 2009 (UTC)
      • Syntax differences (value+note vs ISO 8601) are also insufficient to justify the introduction of a new property for the same semantic. Rather, it is better to expand the syntax of the existing property, e.g. perhaps using the value-excerption-pattern and to note that explicitly. Tantek 20:54, 15 January 2009 (UTC)
        • Semantically the reuse of "duration" is okay. RFC 2445 permits multiple duration values "if the property permits" so that should be fine too. If the syntactic differences can be worked out the way Tantek suggests above than it's okay with me to re-use "duration". I'm just not sure if it helps usability to overload properties in such a way but that ay be another discussion on it's own. ThomasLoertsch 15:00, 16 January 2009 (UTC)
      • The observation that preparation-time uses a nested "note" subproperty may actually reveal a problem with that approach itself, that is, perhaps instead of "preparation-time" with "value" and "note" subproperties, it may be better to refactor it as a "preparation" (an act thereof) with "duration" and "note" subproperties. Tantek 20:54, 15 January 2009 (UTC)
        • Removed the sub-property "note" from the v_0.2 draft format since I now agree that it looks a little overengineered. ThomasLoertsch 12:47, 22 January 2009 (UTC)


As threatened 2 weeks ago I heavily re-edited this page because discussions had become a little frayed (and heated at soem points). Have a look at the previous version for the full debate and feel free to re-edit this page if you find that I axed it too much. ThomasLoertsch 14:47, 2 February 2009 (UTC)


  • The following is a proposal for draft 0.2, reflecting the issues discussed so far. "recipe-title" is replaced with "fn" from hCard (although I'm not convinced that this is a good idea), "recipe-summary" with "summary", "num" and "unit" from the unfinished 'measure' with "type" and "value" from 'hCard' (i only recently discovered them...), "method" (wihch is already used by hCalendar with "instructions", "preparation-time" with "duration". Two "note"s are deleted for brevity. "summary", "nutrition", "author", "published" and "photo" are marked as 'experimental', meaning that they may be removed from future drafts or the final specification, depending on experience and feedback from implementations :

hrecipe. Proposal for Draft 0.2

  • fn. the name of the recipe. required. text. re-used from hCard
  • ingredient required. 1 or more. text with optional valid (x)HTML markup.
    • value and type. optional. re-used from hCard.
  • yield. optional. text.
  • instructions. optional. text with optional valid (x)HTML markup.
  • duration. optional. 1 or more. text (see ISO-31-1 duration brainstorming). re-used from hCalendar.
  • summary. optional. text. re-used from hCalendar. [ experimental ]
  • nutrition. optional. 1 or more. [ experimental ].
    • value and type. optional. re-used from hCard. [ experimental ].
  • author. optional. 1 or more. re-used from hAtom using hCard. [ experimental ].
  • published. optional. re-used from hAtom. [ experimental ].
  • photo. optional. 1 or more. using any element containing a URL, such as IMG. re-used from hCard. [ experimental ].
  • tag. optional. 1 or more. [ experimental ].

--ThomasLoertsch 11:01, 10 February 2009 (UTC)

    • The above seems to use value very differently to other microformats. In other microformats it's used for value excerpting in most properties (i.e. the value class is used to indicate which text should be parsed with the rest being ignored); and in a handful of particular properties (e.g. hCard tel, email, adr, label) it's used in the value+type combination to indicate the main text that should be parsed while type refines the meaning of the property. In a recipe ingredient, the main idea to get across would be the ingredient itself (e.g. eggs, whisky, cardamom), so if value were to be used, you'd expect it to be more like this: <li class="ingredient">2 <span class="value">eggs</span>, lightly whisked</li>. Wrapping class=value around the '2' is fairly at odds with how that class is used in other microformats. TobyInk 15:44, 25 March 2010 (UTC)
      • Suggestion: remove these subproperties from the ingredient and nutrition properties. TobyInk 15:44, 25 March 2010 (UTC)
        • +1 I concur with Toby's analysis and recommendation. Tantek 17:30, 25 March 2010 (UTC)

closed issues

  • closed issue 2008-12-27 raised by Tantek Çelik in the context of issue Too many properties
  1. Drop "recipe-title". In reviewing the examples, few (if any?) include *both* a title and a summary, and in practice the semantics of usage in the context of recipes appears to be virtually indistinguishable. Therefore we don't need both, and following in the pattern provided by hCalendar (which got it from RFC2445), we should keep the more generic concept of a "summary" and drop the concept of "title" from hRecipe.
    • I tend to agree. There are definitely use cases for both "recipe-title/title/fn" and "recipe-summary/summary" - e.g. "A Moroccan-ish Casserole" sounds more like a summary while "Spaghetti primavera" is the full name or the title of the recipe. But the problem is, they would serve the same purpose. Yde 10:07, 17 January 2009 (UTC)
      • Title and summary are different things and they are used differently in the real world. The examples you give are both names/titles/labels/headings, although more or less descriptive. They are short, memorable and make the thing adressable by humans. A summary can be (and mostly is) much longer and serves a different purpose: it describes essential properties of the object at hand, eg: "this is easy and fast to prepare, but still looks impressive", "easy, tasty, fast, vegan, good on cold days" or "the kids loved this last summer, but the ingredients can be hard to get" or "whenever i cook this i start to dream of ..." ThomasLoertsch 14:25, 20 January 2009 (UTC)
        • Right, on second thought, I believe "title/name" and "summary" are different things. Yde 11:22, 23 January 2009 (UTC)
    • The term "title" has been so horribly overloaded across formats, vocabularies that it is nearly meaningless and for that reason should be avoided in any/all format efforts, preferring instead something more semantically specific such as "fn" (meaning full/formatted name of an item) or "summary" (when items are labeled more often with a short description/explanation rather than a name). Tantek 20:54, 15 January 2009 (UTC)
      • Synonyms and homonyms are part of the real world - we have to cope with them. Also the word "title" is not horribly overloaded, you're exaggerating here. It just happened that hCard were the first to use it, and in a way that's empirically much less important then the use of "title" as the heading of a resource. Still the real problem is that Microformats have only one namespace and no resolution mechanism for conflicts like this, beside "first come first served". ThomasLoertsch 15:00, 16 January 2009 (UTC)
      • Maybe it would be better to make a clear cut with some of the sins of the past and deprecate some terms in hCard / hCalendarThomasLoertsch 15:30, 3 February 2009 (UTC)
    • "fn" is defined as "the name of the object" which is pretty much what "recipe-title" means right now. So, whether we chose to keep this property, summary, or both, renaming "recipe-title" to "fn" would make sense. Yde 23:03, 16 January 2009 (UTC)
      • the definition of "fn" in existing classes is maybe a little too short. "fn" is defined in hCard which is a reformulation of RFC 2462, which says: "Type name:FN - Type purpose: To specify the formatted text corresponding to the name of the object the vCard represents. -Type special notes: This type is based on the semantics of the X.520 Common Name attribute. The property MUST be present in the vCard object. - Type example: 'FN:Mr. John Q. Public\, Esq.'" (http://www.ietf.org/rfc/rfc2426.txt, on page 8). That clearly means a name of a person or an institution. Institution equals a juristical person, so "fn" semantically boils down to 'name of a person'. I wouldn't use that for every object. ThomasLoertsch 14:03, 20 January 2009 (UTC)
        • Thanks for the clarification. "fn" is definitely not a good idea. Yde 10:00, 23 January 2009 (UTC)
        • fn is already reused more generically in hAudio, hReview and hListing (for items). The definition of use within microformats has already been adapted from the strict vcard interpretation in prior work. --BenWard 23:04, 27 January 2009 (UTC)
          • I see. I can't help but thinking: what a mess... What's the family name of a recipe, audio-recording or list-entry? What's the point of re-using a semantically totally void two-letter-acronym, when it doesn't even fit very well? What's the point of reusing an element when I have to lookup the meaning of it every time anyway? ThomasLoertsch 00:48, 28 January 2009 (UTC)
            • fn is formatted-name, not ‘family’. ‘Name as presented’, ‘display name’. I agree that fn takes a double glance when you're learning, but it's there and the reuse in other specs is consistent; there's a much stronger author benefit in building on common equivalent-semantic vocabulary than introducing synonyms, which I think will cause more confusion. Better to have a strong spec with common vocabulary than introduce duplication. I'll keep in mind that we should better emphasise the expansion of fn in all specs for benefit of new authors. I can see how ‘family name’ is a muddle too easily made in hCard. --BenWard 07:01, 28 January 2009 (UTC)
              • I was referring to the fact that a name of a natural or juridical person is semantically quite different to the name of an object. Other things like the opacity of the two-letter-code "fn" are indeed problematic too but not my main issue here. That vCard-legacy seems to be lurking around every corner. Why not make a clear cut and deprecate the problematic parts like "title" and "fn"? The approach to rather overload the semantics (and the property-constraints) just to keep element-count low only takes that far. In the end it hinders usability instead of improving it. I think reuse and naming-principles don't strike the right balance in that respect. ThomasLoertsch 11:45, 28 January 2009 (UTC)
    • why not define a property "name"?! From my understanding of the english language (I'm not a native speaker) "name" is semantically generic enough to serve as a substitute for "title". Defining it rather broadly as "designation or title or denominator or heading of an item" would make it easily reusable. Plus we would have to explicitely discourage it's use for naming real or juristical persons and point to "fn" instead. ThomasLoertsch 12:21, 21 January 2009 (UTC)
      • Hmmm. I would really like to get feedback on this... Again my argumentation:
        • title would be the best solution but is already "taken". Depercating some of hCalenders sins would be the best solution but seems out of reach so far.
        • heading would be a possible solution either but seems more suited for prose
        • name gets the semantics quite well, especially in the case of recipes which are more a "thing" or abstract conceptualization than a work of literature/science/prose
        • fn with it's subproperties is geared towards natural and juristical persons, which are quite different from things and concepts. Also semantics of the term "fn" are rather opaque, even misleading, which hinder it's usability.
      • Therefor I'd love "title", could live very well with "name", could live still well with "heading" and would sleep bad (but sleep) with "fn". ThomasLoertsch 16:30, 2 Febuary 2009 (UTC)
      • Okay, since there's no response I bow my head to "fn". But it speaks for itself that it's the only tag that has to be explained in the schema. ThomasLoertsch 11:15, 10 February 2009 (UTC)



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>

related pages

Per the microformats process, the recipe effort developed

towards the development of this draft.