hrecipe-issues

From Microformats Wiki
Revision as of 07:08, 28 January 2009 by BenWard (talk | contribs) (→‎issues: Fixed some formatting in the issues discussion that I just broke. Sorry about that. Should be clearer reading now with less neesting.)
Jump to navigation Jump to search

<entry-title>hRecipe issues</entry-title>

This page reflects issues raised about the hRecipe microformat.

Past issues captured during brainstorming towards hRecipe can be found in recipe-issues.

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.

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

If you have general feedback on hRecipe (positive/neutral/negative) please add to hrecipe-feedback rather than this document.

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.

  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.
    • btw: this is a first draft but a rather well worked out brainstorming proposal has been around for over a year, a refinement of it for another few months and the draft only builds on them. 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. TomLurge 14:05, 20 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.
      1. 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)
        • These really are different things: the examples you give are both names/titles/labels/headings, though 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" 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 ..." - whatever. these are summaries, abstracts, introductions. If "too many properties" are really a problem of hRecipe I could live without this property but I still think it makes sense. TomLurge 14:25, 20 January 2009 (UTC)
          1. Right, that's actually how I thought of it before this whole "too many properties" issue. So on second thought, I believe "title/name" and "summary" are different things. Yde 11:22, 23 January 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. TomLurge 17:52, 6 January 2009 (UTC)
      1. 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. Tantek 20:54, 15 January 2009 (UTC)
        • 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. TomLurge 15:00, 16 January 2009 (UTC)
      2. "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. Tantek 20:54, 15 January 2009 (UTC)
      3. 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. Tantek 20:54, 15 January 2009 (UTC)
      4. I'm not taking these arguments lightly, but there are counter arguments too: while hCard and hCalender are extremly large vocabularies (which mostly stems from the approach taken of converting an existing vocab 1:1) it is also not necessarily helpfull to constrain a vocab by all means. when I'm looking for a vocabulary for a certain use I'm not looking for the smallest vocab but for theeon that fits my needs, more or less. if it's much too small I feel taht it's not of much help and I look somewhere else. the 80:20 rule might be a better guide, again. a vocabulary should encompass most of the usecases, and right from the start - since otherwise, why should it start to get adopted. it's right to start prudentious since it's always easier to add properties than to remove them. but don't exegerate, neither with minimization nor with exhaustiveness. for hrecipe i visited a lot of the big sites like recipetsar, which are full of user generated content. they use a lot of properties, certainly more than we do. a very minimal, but perfectly useful set of elements would be "name", "ingredients", "instructions". just those 3. but people upload pictures, socialize by stating their authorship, need to know how long preparation will take, care for nutritional information etc. so these properties are not just superfluous spaghetti vocabulary - they serve real needs, as you can see on those massively popular sites. so where's the sweet spot? 3 properties is extremely small, the 70 or so properties of hCard is extremely big. I think with about 10 properties hRecipe is not very big. you'll certainly not get lost in a soup of properties. and for implementors it's not too hard to go from 3 to 10 properties as long as they are not complexly nested/intertwined/constrained. 10 are certainly more than absolutely necessary - as I said, 3 would be my minimum -, so there's always room for debate and optimization. but please be specific, don't just argue with just "principles" and "lessons learned". TomLurge 11:08, 22 January 2009 (UTC)
      5. 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. Tantek 20:54, 15 January 2009 (UTC)
        • 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 gathered 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 done. 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. TomLurge 14:08, 20 January 2009 (UTC)
      6. 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. Tantek 20:54, 15 January 2009 (UTC)
        • 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". TomLurge 15:00, 16 January 2009 (UTC)
      7. 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). Tantek 20:54, 15 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. TomLurge 15:00, 16 January 2009 (UTC)
          1. "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. and 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)
              1. Thanks for the clarification. "fn" is definitely not a good idea. Yde 10:00, 23 January 2009 (UTC)
              2. 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)
            • on second thought: 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)
  2. 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)
        • 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. TomLurge 15:00, 16 January 2009 (UTC)
  3. 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)
        • 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. 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)
        • While semantically correct this would leave us with one more property, since "preparation" on itself, without a "duration"-subelement, wouldn't make 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. 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. 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. Tantek 20:54, 15 January 2009 (UTC)
      • I think the example is rather contrieved. I wouldn't expect microformats to handle such complex cases. I also agree with Tantek that a concise format is more important than naïve parsability. TomLurge 14:00, 20 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. 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! Tantek 20:54, 15 January 2009 (UTC)
  4. the issue is a little long already, but before i re-edit it and tear it apart into seperate subissues, i'd like to share what i think could become the draft 0.2. I replaced "recipe-title" with the new "name" (which is defined in a way to facilitate re-use and make the distinction to "fn" clear), replaced "recipe-summary" with "summary", replaced "num" and "unit" from the umfinished 'measure' with "type" and "value" from 'hCard' (i only recently discovered them...), replaced "method" (wihch is already used by hCalendar with "instructions" (see discussion at the issue "method" below), replaced "preparation-time" with "duration", deleted two "note"s for brevity, marked "summary", "nutrition", "author", "published" and "photo" 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 ].

Please comment! TomLurge 12:47, 22 January 2009 (UTC)

  • I like this new schema. However I think 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)
    • glad you like the new schema :-) 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". then 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. the third - and actually to me the more important - reason is that these terms come from a comparably very stable vocabulary, while measure has not even draft status. although it doesn't look like that will happen it would be totally okay for measure to change attribute names, semantics or even the whole structure of the vocabulary - but it wouldn't be so totally okay for us. so i'd prefer to stay on the safe side, especially since we might even gain something semantically. TomLurge 19:43, 23 January 2009 (UTC)
  • open issue! method 2008-01-17 raised by Yde
    1. 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)

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.
      • Yikes! Corrected... TomLurge 17:52, 6 January 2009 (UTC)

closed issues

  • none currently

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

Retrieved from "http://microformats.org/wiki/index.php?title=hrecipe-issues&oldid=37783"