hrecipe-issues

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.

• open issue! 2008-12-27 raised by Tantek Çelik

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). TomLurge
   • The following properties IMO are useful but surely not essential for recipes:
     • "nutrition" - but probably a very welcome addition to a lot of people. Could maybe become a microformat on it's own?
     • "summary" - but people seem to love to associate recipes with little stories and/or need a place to add additional 'unstructured' information.
     • "photo" - but probably a welcome addition in most cases.
     • "published" - but seems like a non brainer either.
     • "author" - although popular on community sites.
     • "tag" - but like "author" very popular with community sites, and useful for finding recipes.
   • My suggestion would be to mark these properties as experimental and follow closely if implementations actually use them. All those properties may be removed later on with not too much strong feelings while the others are considered already quite stable. TomLurge 12:47, 22 January 2009 (UTC)

• open 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 ..." TomLurge 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". TomLurge 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 / hCalendarTomLurge 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. TomLurge 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? TomLurge 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. TomLurge 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. TomLurge 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". TomLurge 16:30, 2 Febuary 2009 (UTC)

• open issue! 2008-12-27 raised by Tantek Çelik

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.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. Tantek 20:54, 15 January 2009 (UTC)
       • Will change "recipe-summary" to "summary" as defined in hCalender/RFC2445. TomLurge 15:00, 16 January 2009 (UTC)

• open issue! 2008-12-27 raised by Tantek Çelik

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 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. 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. 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. TomLurge 12:47, 22 January 2009 (UTC)

• open issue!2008-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)? TomLurge 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. TomLurge 14:30, 2 Febuary 2009 (UTC)

• open issue! 2009-01-22 raised by TomLurge

• "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. TomLurge 19:43, 23 January 2009 (UTC)

• open issue! new draft2009-01-22 raised by TomLurge

• The following is a proposal for draft 0.2, reflecting the issues discussed above. "recipe-title" is replaced with the new "name" (which is defined in a way to facilitate re-use and make the distinction to "fn" clear), "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

• name required. text. [ comment for re-use: only for objects. use "fn" for persons and institutions. ]
• 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 ].

TomLurge 12:47, 22 January 2009 (UTC)

• open issue! issues too long 2009-01-22 raised by TomLurge

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. TomLurge 14:47, 2 February 2009 (UTC)