hrecipe-ja

From Microformats Wiki
Revision as of 05:13, 23 April 2010 by Imagedrive (talk | contribs) (→‎概要: 概要の約完了)
Jump to navigation Jump to search

<entry-title>hRecipe-ja</entry-title>

hRecipe

この文書は microformat のドラフト仕様です。ドラフトなので開発段階においてはいくらかは完成していますが、この文書の安定性は保証できません。なので開発者は将来の発展と変化に対応できるよう準備しておく必要があります。最新の情報を得るには、この wiki ページを見るか microformats-new mailing list の議論から学んで下さい。

hRecipe.png

hRecipe はシンプル、オープン、分散されたフォーマットで、(X)HTML、Atom、RSS、そして任意の XML で料理のレシピについての情報を埋め込むのに適しています。hRecipe はオープンスタンダードな microformats の一つです。このページとマイクロフォーマットは、パブリックドメインです。

hRecipe Microformat Draft Specification

編者

作者

貢献者

Andy Mabbett, Frances Berriman, Cameron Perry, John LeMasney, Tantek Çelik, SudarshanP, Ciaran McNulty, Lee Jordan, Robert Bachmann, jeffmcneill, Manu Sporny, Ryan King, HollyMarieKoltz, Straup, Christophe Ducamp, Mercman, Yde, Ameer Dawood, Scottk, Lee Jordan, MonroAlmon, EstevaoSamuel, Brian Suda, SteveL, JohnLeMasney,

Microformats #Copyright and #Patents statements apply.


概要

マイクロフォーマットの hRecipe は食事や飲み物、食材の調理方法をマークアップするためにデザインされています。

ブラウザがウェブページに記述されているレシピについての意味的な情報を抽出するのは困難です。メタデータはレシピの著者やレシピ名と材料、調理方法、調理時間についての詳細など、レシピに関係する情報を提供します。

そのような情報をマークアップしておくことで閲覧者にいくらかの有益な情報を提供することができます。もしウェブブラウザがそれぞれのウェブページに含まれるレシピに関する固有の意味を理解できれば、豊かな相互作用を生み出すことができます。例えば、特定の検索は材料や著者のために Google や Wikipedia などの一般的な検索サービスで実行されるかもしれません。さらにクローラによる分類は、より正確になることができます。1ページで見つけられたレシピが20ほどあって、ある材料を含んでいるなら、そのページが料理だけではなく、その特定の材料についてのページと仮定することができます。

レシピの集約とシンジケーションおよび流通と共有と促進を可能にするために、作者はレシピのメタデータを分類するオープンスタンダードな hRecipe マイクロフォーマットを提案します。作者は recipe-formats についてのワイルドで初期の試みにおいて多数の recipe-examples を研究し、レシピコンテンツのためにシンプルで小さいスキーマである hRecipe を設計しました。フィードバックは hRecipe feedback ページでお願いします。

Inspiration and Acknowledgments

Many thanks to the various individuals that did research and proposed ideas and discussion related to the hRecipe-format and recipes in general.

Scope

hRecipe is a format to annotate descriptions and lists of ingredients for the preparation of food and meals. Recipes consistently share several common properties. hRecipe has been based on this minimal common subset.

Out of scope

Recipes that are not for stuff that's meant to be eaten by humans are out of scope.

書式

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

通例

The hRecipe format is based on a set of properties common to numerous recipe sites and formats in use today on the web. Where possible property names have been chosen based on those defined by related microformat standards.
Some properties are marked experimental since they exceed the minimum set of properties needed to describe a recipe but still are very commonly used on the web. It's not sure if they are relevant enough for inclusion in the format. Implementation and general uptake of these properties will be observed and inform further decisions. So their use is not at all discouraged - but use them with care and be prepared for their eventual removal from the final spec.


スキーマ

hRecipe スキーマは以下のプロパティで構成されます:

  • hrecipe
    • fn. 必須。テキスト。レシピの名前。
    • ingredient. 必須。1つ又はそれ以上の任意の妥当な (x)HTML でマークアップされたテキスト。
      • value and type. 任意。(実験的)
    • yield.任意。テキスト。
    • instructions. 任意。任意の妥当な (x)HTML でマークアップされたテキスト。
    • duration. 任意。1つ又はそれ以上のテキスト。
    • photo. 任意。1つ又はそれ以上。画像のような任意の要素を含んだ URLを使用。(実験的)
    • summary. 任意。テキスト。(実験的)
    • author. 任意。1つ又はそれ以上(実験的)
    • published. 任意。(実験的)
    • nutrition. 任意。1つ又はそれ以上(実験的)
      • value and type. 任意。(実験的)
    • tag. 任意。1つ又はそれ以上(実験的)


プロパティの詳細

fn, photo, author, valuetype のプロパティは hCard に従います。duration のプロパティは hAudio に従います。summary のプロパティは hCalendar に従います。published のプロパティは hAtom に従います。tag のプロパティは rel-tag に従います。


hRecipe スキーマのフィールドは次のように表します:

hRecipe

hRecipe はレシピの識別や値の記述、メタデータの関連付けに用いられます。 

  • hRecipe プロパティは hrecipe 名で識別されます。

fn

1つのレシピのタイトルです。概要は短いテキストで構成され関連性のあるグループ間を識別するのに使用されます。これは、食事や食材の名前に簡単な説明をします。

  • プロパティは fn で識別されます。
  • レシピは fn が必須です。
  • プロパティは hCard のルールに従う必要があります。例)プレーンテキストのみ使用

ingredient

レシピに使われているひとつまたは複数の材料を記述します。

  • プロパティは ingredient で識別されます。
  • レシピにはひとつまたは複数の ingredients を含む必要があります。
  • プロパティには(材料のリストなどを)妥当な HTML マークアップで含むことができます。
  • プロパティは hCard の規則に従った value (値)と type (型)を含むことができます。
    <p class="ingredient"><span class="value">125</span><span class="type">ml</span> milk</p>
    
    この場合、それぞれの材料は ingredient プロパティに含むかたちでマークアップしなければなりません。これらのサブプロパティは実験的で最終的な仕様から削除される可能性か、分量から"数値(num)”と"単位(unit)"に置き換えられます。

yield

このレシピで何人分の分量または数量(個数)を指定します。

  • プロパティは yield で識別されます。
  • レシピは yield を含むことができます。

instructions

レシピの方法手順。

  • プロパティは instructions で識別されます。
  • レシピは instructions を含むことができます。
  • プロパティは妥当な HTML でマークアップされた文章や手順のリストを含むことができます。

duration

調理に必要な時間を記述します。例えば生地を準備するための時間、生地の発酵に必要な時間、生地を焼く時間、ケーキ等を飾る時間など、複数の調理時間のプロパティを示すために使用することができます。

  • プロパティは duration で識別されます。
  • レシピは、ひとつもしくは複数の duration プロパティを含めることができます。
  • プロパティは value-class-pattern で略述した期間をコード化してください。調理時間が1時間30分の場合、ISO 8601 形式の"PT1H30M"に変換し、以下のようにコード化することができます:
    <span class="duration"><span class="value-title" title="PT1H30M"> </span>90 min</span>
    

photo

添付写真

  • プロパティは、photo で識別されます。
  • レシピは、ひとつもしくは複数の photo プロパティを含めることができます。
  • プロパティは、img 要素を使用してください。a 要素や object 要素など URL を含んだ他の要素を使用することができますが、推奨されていません。注釈を参照してください。
  • プロパティは、実験的で最終的な仕様から削除される可能性があります。

summary

The summary provides a short introduction to or an accompanying statement about the recipe.

  • The property is identified by the name summary.
  • A Recipe MAY include a summary.
  • The property MUST follow the conventions outlined in hCalendar. Plain text fulfills these requirements.
  • The property is considered experimental and may be removed from the final specification.

author

An author is the person who wrote the recipe.

  • The property is identified by the name author.
  • A Recipe MAY include one or more author properties.
  • The contents of the element MAY be a plain text string in which case it defaults to a "vcard fn". Anything more elaborate MUST follow the conventions outlined in hCard.
  • The element is considered experimental and may be removed from the final specification.

published

The date the recipe was published.

  • The property is identified by the name published.
  • A Recipe MAY include a published date.
  • The property MAY be encoded using the value-class-pattern, e.g.:
    <p>Published <span class="published"><span class="value-title" title="2008-10-14T10:05:37-01:00"> </span>14. Oct 2008</span></p>
    
  • The property is considered experimental and may be removed from the final specification.

nutrition

Nutritional information like calories, fat, dietary fiber etc.

  • The property is identified by name nutrition.
  • A Recipe MAY include one or more nutrition properties.
  • The property MAY include the properties value and type following the conventions outlined in hCard. In this case each nutritional information item should be marked up with it's own nutrition property. These subelement are considered experimental and may be replaced by 'num' and 'unit' from measure.
  • The property nutrition itself is also considered experimental and may be removed from the final specification.

tag

A keyword indicating a subject or an important aspect of the recipe like it's main ingredient, type of meal etc.

  • The property is identified by the name tag.
  • A Recipe MAY include one or more tag's.
  • The property MUST follow the conventions outlined in rel-tag.
  • The property is considered experimental and may be removed from the final specification.

Version history

  • Version 0.22 changed the proposed formatting of time and date from the datetime-design-pattern, which has accessibility issues, to the value-class-pattern. Also corrected some errors in the example especially with regard to the correct handling of vcard properties.
  • Version 0.21 changed the status of ingredient/value and ingredient/type to experimental, mentioning that there still is discussion if they should be replaced by 'num' and 'unit' from measure (which is still in brainstorming).
  • Version 0.2: From Version 0.1 some elements have been renamed to strenghten re-use of established elements: fn for hRecipe-title, summary for hRecipe-summary, duration for preparation-time, value and type for num and unit. Also some elements have been marked experimental because of concerns of element bloat. See the hrecipe-issues page for a more thorough discussion.
    Draft 0.1 was already a result of long lasting efforts. Nonetheless after publishing of it there has been a lively debate about some properties. Since they mostly could be resolved version 0.2 is considered fairly stable now, although of course you never know ;-)


Parser Processing Notes

  • If the "author" property contains only a plain text string it should be regarded as of type "vcard fn".


Semantic XHTML Design Principles

Note: the Semantic XHTML Design Principles were written primarily within the context of developing hCard and hCalendar, thus it may be easier to understand these principles in the context of the hCard design methodology (i.e. read that first). Tantek

XHTML is built on XML, and thus XHTML based formats can be used not only for convenient display presentation, but also for general purpose data exchange. In many ways, XHTML based formats exemplify the best of both HTML and XML worlds. However, when building XHTML based formats, it helps to have a guiding set of principles.

  1. Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
    1. For types with multiple components, use nested elements with class names equivalent to the names of the components.
    2. Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.
  2. Use the most accurately precise semantic XHTML building block for each object etc.
  3. Otherwise use a generic structural element (e.g. <span> or <div>), or the appropriate contextual element (e.g. an <li> inside a <ul> or <ol>).
  4. Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.
  5. Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <abbr> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human readable equivalent into the element itself. Further informative explanation of this use of <abbr>: Human vs. ISO8601 dates problem solved


More Semantic Equivalents

For some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:

  • For "photo", use <img class="photo" src="..." alt="" />


Language

  • To explicitly convey the natural language that an recipe is written in, use the standard (X)HTML 'lang' or 'xml:lang' attribute on the element with class="hrecipe"
    • e.g. <p>I like <span class="hrecipe" lang="de"><span class="fn">Kartoffelknödel</span></span> best.</p>
  • If portions of an hRecipe (e.g. an ingredient name) are in a different language to the rest of the hRecipe, use the 'lang' or 'xml:lang' attribute on those portions.
  • hRecipe parsers which need to handle the native language of hRecipe MUST process the standard (X)HTML 'lang' or 'xml:lang' attribute as specified.
  • hRecipe parsers which need to handle native language MAY traverse up the DOM to discover the native language of the page and apply that to the hRecipe if no other language is specified on the hRecipe.


Human vs. Machine Readable

If an <abbr> element is used for a property, then its 'title' attribute is used for the value of the property, instead of the contents of the element, which can then be used to provide a user-friendly alternate presentation of the value.

If an <a> element is used for one or more properties, it MUST be treated as follows:

  1. For the 'photo' property and any other property that takes a URL as its value, the href="..." attribute provides the property value.
  2. For other properties, the element's content is the value of the property.

If an <img> element is used for the 'photo' property, it MUST use the property value provided by the src="..." attribute as property value.

If an <object> element is used for the 'photo' property, it MUST use the property value provided by the data="..." attribute as property value.


Notes

This section is informative.

  • Non so far.


XMDP Profile

<dl class="profile">
 <dt>class</dt>
 <dd><p>
  <a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class">
   HTML4 definition of the 'class' attribute.</a>
  This meta data profile defines some 'class' attribute values (class names) 
  and their meanings as suggested by a 
  <a href="http://www.w3.org/TR/WD-htmllink-970328#profile">
   draft of "Hypertext Links in HTML"</a>.</p>
  <dl>
   <dt>hrecipe</dt>
   <dd>
    Used to identify and describe metadata associated with instructions for creating meals, drinks or food-based items.
   </dd>
   <dt>fn</dt>
   <dd>
    The title of the recipe.
   </dd>
   <dt>ingredient</dt>
   <dd>
    Describes the ingredient(s) used in the recipe.
   </dd>
   <dt>yield</dt>
   <dd>
    Specifies the quantity produced by the recipe.
   </dd>
   <dt>instructions</dt>
   <dd>
    The method of the recipe.
   </dd>
   <dt>duration</dt>
   <dd>
    The time it takes to prepare the meal described by the recipe.
   </dd>
   <dt>photo</dt>
   <dd>
    Accompanying image.
   </dd>
   <dt>summary</dt>
   <dd>
    The summary provides a short introduction or an accompanying statement about the recipe.
   </dd>
   <dt>author</dt>
   <dd>
   The person who authored the recipe..
   </dd>
   <dt>published</dt>
   <dd>
    The date that the recipe was made available to the public.
   </dd>
   <dt>nutrition</dt>
   <dd>
    Nutritional information like calories, fat, dietary fiber etc.
   </dd>
   <dt>tag</dt>
   <dd>
    Keyword(s) describing the recipe.
   </dd>
  </dl>
 </dd>
</dl>


Examples

This section is informative.

Here will be a few examples of recipes, from real web sites, showing how they could be easily enhanced to use hRecipe. In the meantime the following contrieved example will have to do.

<div class="hrecipe">
    <h1 class="fn">Pommes Frites</h1>
    <p class="summary">
        Pommes frites originate in outer space. They are served hot.<br />
        This recipe is only an example. Don't try this at home!
    </p>
    <p>
        Contributed by <span class="author">CJ Tom</span> and the
        <span class="author vcard"><a class="url fn" href="http://example.com">Cooky Gang</a></span>.
    </p>
     <p>Published <span class="published"><span class="value-title" title="2008-10-14T10:05:37-01:00"> </span>14. Oct 2008</span></p>
    <img src="/img/pommes.png" class="photo" width="100" height="100" alt="Pommes Frites"/>
    <h2>Ingredients</h2>
    <ul>
        <li class="ingredient">
            <span class="value">500</span> 
            <span class="type">gramme</span> potatoes, hard cooking.
        </li>
        <li class="ingredient">
            <span class="value">1</span> <span class="type">spoonful</span> of salt
        </li>
        <li>
            You may want to provide some 
            <span class="ingredient">Ketchup and Mayonnaise</span>
            as well.
        </li>
    </ul>
    <h2>Instructions</h2>
    <ul class="instructions">
        <li>First wash the potatoes.</li>
        <li>Then slice and dice them and put them in boiling fat.</li>
        <li>After a few minutes take them out again.</li>
    </ul>
    <h2>Further details</h2>
    <p>Enough for <span class="yield">12 children</span>.</p>
    <p>Preparation time is approximately 
        <span class="duration"><span class="value-title" title="PT1H30M"> </span>90 min</span>
    </p>
    <p>Add <span  class="duration"><span class="value-title" title="PT30M"></span>half an hour</span> to prepare your homemade Ketchup.</p>
    <p>This recipe is <a href="http://www.example.com/tags/difficulty/easy" rel="tag">easy</a> and <a href="http://www.example.com/tags/tastyness/delicious" rel="tag">delicious</a>.</p>
    <p>
        <span class="nutrition">
        Pommes Frites have more than 
        <span class="value">1000</span> 
        <span class="type">Joule</span>
        Energy</span>, 
        while Ketchup and Mayonnaise have 
        <span class="nutrition">0 vitamins</span>.
    </p>
</div>

Examples in the wild

This section is informative.

Sites and pages that publish hRecipes. When it gets too big we can move it to a separate page like hrecipe-examples-in-wild.


Implementations

This section is informative.

Tools for generating and consuming hRecipes. When it gets too big we can move it to a separate page like hrecipe-implementations.


References

Normative References

Informative References

Copyright

Per Microformats_Wiki:Copyrights, hRecipe was placed into the public domain on 2008-11-14 by the authors. There are no usage, distribution, re-printing, or any other restrictions of any kind with regards to the text or content of this specification.

Patents

This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.

Public Domain Release

The authors and editors of this page due hereby relinquish their copyright on the document and release the text of this page into the public domain.


Work in progress

This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

derivative works

  • hRecipe in RDF - mapping of hRecipe into a RDF vocabulary called "aRecipe"

related pages

Per the microformats process, the recipe effort developed

towards the development of this draft.