Difference between revisions of "projecta"

From Microformats Wiki
Jump to navigation Jump to search
 
Line 1: Line 1:
=Projecta=
 
Even though there are existing project formats, the projecta format {{must}} be developed because there is no established project format and it will enable decentralized development of projects.
 
 
 
== Format ==
 
== Format ==
 
=== In General ===
 
=== In General ===
The projecta format is based on a set of fields common to numerous project sites and formats in use today on the web.  Where possible field names have been chosen based on those defined by the related [[hcard|hCard]], [[hcalendar|hCalendar]], and [[hreview|hReview]] standards.
+
The projecta format documents practical (how-you-can-do) projects.  Where possible field names have been chosen based on those defined by the related [[hcard|hCard]], [[hatom|hAtom]], [[hcalendar|hCalendar]], and [[hrecipe|hRecipe]].
 
 
== Format ==
 
=== In General ===
 
The projecta format is based on a set of fields common to numerous project sites and formats in use today on the web.  Where possible field names have been chosen based on those defined by the related [[hcard|hCard]], [[hcalendar|hCalendar]], [[hreview|hReview]], and [[hrecipe|hRecipe]].
 
  
 
=== Schema ===
 
=== Schema ===
The projecta schema consists of the following:
+
The projecta schema consists of the following elements:
  
* projecta ('''<code>projecta</code>''')
+
* '''projecta'''
** '''version'''. optional. text.
+
** '''''fn'''''. required. text. the formatted name of the project. re-used from [[hCard]].
** '''summary'''. optional. text. one sentence.
+
** '''''summary'''''. optional. text. re-used from [[hCalendar]].
** '''type'''. optional. abstract | practical.
+
** '''''author'''''. optional. 1 or more. re-used from [[hAtom]] using [[hCard]].
** '''project''' info. required. '''<code>fn</code>''' ('''<code>url</code>''' || '''<code>photo</code>''' )
+
** ''published''. optional. re-used from [[hAtom]]. [experimental]
** '''author'''. optional. '''[[hcard|hCard]]'''.
+
** ''tag''. optional. 1 or more. re-used from [[rel-tag]]. [experimental]
** '''description'''. optional. text with optional valid HTML markup.
+
** ''photo''. optional. 1 or more. using any element containing a URL, such as IMG. re-used from [[hCard]]. [experimental]
** '''goals'''. optional. text with valid HTML '''<code>ul</code>''' ('''<code>li</code>''') elements.
+
** ''requirement''. optional. text with optional valid (x)HTML markup.
** '''instructions'''. optional. text with valid HTML '''<code>ol</code>''' ('''<code>li</code>''') elements.
+
** ''instructions''. optional. text with optional valid (x)HTML markup. re-used from [[hRecipe]].
** '''accomplishments'''. optional. text with valid HTML '''<code>ul</code>''' ('''<code>li</code>''') elements.
+
** '''''duration'''''. optional. 1 or more. text (see [[ISO-31-1]] duration brainstorming). re-used from [[hCalendar]].
** '''requirements'''. optional. text {{may}} include valid HTML markup e.g. paragraphs or a list.  
 
** '''tags'''. optional. keywords or phrases, using '''[[rel-tag]]''', each with optional rating.
 
** '''permalink'''. optional, using '''[[rel-bookmark]]''' and '''[[rel-self]]'''.
 
  
 
=== Field details ===
 
=== Field details ===
 
The fields of the projecta schema represent the following:
 
The fields of the projecta schema represent the following:
  
'''version''':: This optional field permits projecta publishers to specify a particular version of projecta that their content uses. This field is syntax compatible with, and thus reuses the semantics of "VERSION" as defined in vCard RFC2426 section "3.6.9 VERSION Type Definition". The value of this field for this specification is "0.1".
+
==== fn ====
 +
 
 +
The title of a single project. The formatted name of what the projecta documents.
 +
 
 +
* The element is identified by class name <code>fn</code>.
 +
* A projecta {{must}} include a <code> fn </code>.
 +
* The element {{must}} follow the conventions outlined in [[hCard]].
 +
 
 +
==== summary ====
 +
 
 +
The summary provides a short introduction to or an accompanying statement about the project.
 +
 
 +
* The element is identified by the class name <code>summary</code>.
 +
* A projecta {{may}} include a <code>summary</code>.
 +
* The element {{must}} follow the conventions outlined in [[hCalendar]].
 +
 
 +
==== author ====
 +
 
 +
The person who authored the project.
 +
 
 +
* The element is identified by class name <code>author</code>.
 +
* A projecta {{may}} include one or more <code>author</code> elements.
 +
* The contents of the element {{must}} follow the conventions outlined in [[hCard]].
 +
 
 +
==== published ====
 +
 
 +
The date the project was published.
 +
 
 +
* The element is identified by the class name <code>published</code>.
 +
* A projecta {{may}} include a <code>published</code> date.
 +
* The element {{must}} follow the conventions outlined in [[hAtom]].
 +
* The [[datetime-design-pattern]] {{should}} be used to encode the published datetime.
 +
* The element is considered ''experimental'' and may be removed from the final specification.
 +
 
 +
==== tag ====
 +
 
 +
A keyword indicating a subject or an important aspect of the project like it's main requirement, type of project etc.
 +
 
 +
* The element is identified by class name <code>tag</code>.
 +
* A projecta {{may}} include one or more <code>tag</code> elements.
 +
* The element {{must}} follow the conventions outlined in [[rel-tag]].
  
'''summary''':: This optional field serves as a one sentence summary of the project.
+
==== photo ====
  
'''type''':: This optional field "type" provides the type of project, one of the following: abstract, practical.  If omitted, then in some cases the project type may be inferred. For projects of type "abstract" {{should}} have "goals" and/or "accomplishments" fields completed.  For projects of type "practical" {{should}} have "instructions" field completed.
+
Accompanying image.
  
'''project''':: This required field {{must}} have at a minimum the name ("fn" - the formatted text corresponding to the name) of ''the'' project (a projecta describes only one project), {{may}} provide at least one URI ("url") for the project, and {{may}} provide at least one URL to a photo or depiction ("photo") of the project. However, when using item info subproperties ("fn", "url", "photo"), they {{must}} be nested <em>inside</em> the project element.
+
* The element is identified by the class name <code>photo</code>.
 +
* A projecta {{may}} include one or more photo elements.
 +
* The element {{should}} use an &lt;img&gt; element.
 +
* The element {{may}} use any other element that contains a URL, such as &lt;a&gt; or &lt;object&gt;, but it is not recommended.
 +
* The contents of the element {{must}} follow the conventions outlined in [[hCard]].
  
'''author''':: This optional field specifies the person who authored the project.  If the author is specified, an hCard representing the author {{must}} be provided.
+
==== requirement ====
  
'''description''':: This optional field contains the full text representing the input of the author.  The field {{may}}  include valid HTML markup (e.g. paragraphs).  User agents {{should}} preserve any markup.
+
Describes one or more requirements of the project.
  
'''goals''':: This optional field documents the project's goals.
+
* The element is identified by the class name <code>requirement</code>.
 +
* A projecta {{must}} include one or more <code>requirement</code>s.
 +
* The field {{may}} include valid HTML markup (e.g. a list of requirements).
  
'''instructions''':: This optional field documents the instructions required to complete the project. Re-used from [[hrecipe|hRecipe]].
+
==== instructions ====
  
'''accomplishments''':: This optional field documents the project's accomplishments.
+
Documents the instructions required to complete the project.
  
'''requirements''':: This optional field contains the requirements of the project. The field {{may}} include links to products or other projects.
+
* The element is identified by the class name <code>instructions</code>.
 +
* A projecta {{may}} include a <code>instructions</code> element.  
 +
* The field {{may}} include valid HTML markup e.g. paragraphs or a list of steps.
  
'''tags''':: Tags are represented using a list of keywords or phrases (using the [[rel-tag]] microformat for each individual keyword or phrase tag) that the author associates with the project.
+
==== duration ====
  
'''permalink''':: This optional field is a URL for the projecta. In addition to using the <code><a href></code> tag for this field, the attribute <code>rel="self bookmark"</code> {{must}} be used to indicate that the hyperlink is a permalink for the project itself.  If the hyperlink already contains a <code>rel</code> attribute, then the values <code>self</code> and <code>bookmark</code> {{must}} be included among the space-separated set of values in the attribute.  Indexers {{may}} treat the permalink of a project as a unique ID in order to identify and collate the same project from multiple sources (such as indexing a page multiple times).  The permalink {{may}} also be used to indicate or imply the origin of the project. Authors {{may}} use the classname of "permalink" on the element representing the permalink.
+
The time it takes to complete the project described by the projecta. Multiple duration fields can be used to denote time taken per instruction.
 +
* The element is identified by the class name <code>duration</code>.
 +
* A projecta {{may}} include one or more <code>duration</code>s.
 +
* The element {{must}} follow the conventions outlined in [[hCalendar]].
  
The following field names have been reused from the [[hcard|hCard]], [[hcalendar|hCalendar]], [[hreview|hReview]], and [[hrecipe|hRecipe]] microformats: <code>version, summary, url, photo, description, instructions, tags, permalink</code>. In addition, items and authors described by hCards {{may}} contain any hCard field. The rel value "self" has been reused from the [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html Atom 1.0 specification].
+
<pre><nowiki>
 +
<div class="projecta">
 +
<h3 class="fn">Germinating Seeds</h3>
 +
<p class="summary">
 +
How to germinate seeds in potting mix.<br />
 +
</p>
 +
<p class="vcard fn">Derek Lewis</p>
 +
<p>Published <abbr class="published" title="2009-03-28T09:30-11:00">28. Mar 2009</abbr></p>
 +
<img src="/img/seed.png" class="photo" width="100" height="100" alt="Seed"/>
 +
<h4>Requirements</h4>
 +
<ul class="requirement">
 +
<li>Container(s) (With drain holes)</li>
 +
<li>Seed(s)</li>
 +
<li>Potting Mix</li>
 +
<li>Fresh Water</li>
 +
<li>A Light Source</li>
 +
</ul>
 +
<h4>Instructions</h4>
 +
<ol class="instructions">
 +
<li>Loosen and dampen the potting mix.</li>
 +
<li>Fill 2/3 of each container(s) with potting mix.</li>
 +
<li>Put seed(s) in container with potting mix.</li>
 +
<li>Sprinkle a few drops of water over of the seed(s). (Remember to repeat this once potting mix becomes dry.)</li>
 +
<li>Place container under light source.</li>
 +
</ol>
 +
</div>
 +
</nowiki></pre>

Latest revision as of 07:38, 29 March 2009

Format

In General

The projecta format documents practical (how-you-can-do) projects. Where possible field names have been chosen based on those defined by the related hCard, hAtom, hCalendar, and hRecipe.

Schema

The projecta schema consists of the following elements:

  • projecta
    • fn. required. text. the formatted name of the project. re-used from hCard 1.0.
    • summary. optional. text. re-used from hCalendar 1.0.
    • author. optional. 1 or more. re-used from hAtom 0.1 using hCard 1.0.
    • published. optional. re-used from hAtom 0.1. [experimental]
    • tag. optional. 1 or more. re-used from rel="tag". [experimental]
    • photo. optional. 1 or more. using any element containing a URL, such as IMG. re-used from hCard 1.0. [experimental]
    • requirement. optional. text with optional valid (x)HTML markup.
    • instructions. optional. text with optional valid (x)HTML markup. re-used from hRecipe 0.22.
    • duration. optional. 1 or more. text (see ISO-31-1 duration brainstorming). re-used from hCalendar 1.0.

Field details

The fields of the projecta schema represent the following:

fn

The title of a single project. The formatted name of what the projecta documents.

  • The element is identified by class name fn.
  • A projecta MUST include a fn .
  • The element MUST follow the conventions outlined in hCard 1.0.

summary

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

  • The element is identified by the class name summary.
  • A projecta MAY include a summary.
  • The element MUST follow the conventions outlined in hCalendar 1.0.

author

The person who authored the project.

  • The element is identified by class name author.
  • A projecta MAY include one or more author elements.
  • The contents of the element MUST follow the conventions outlined in hCard 1.0.

published

The date the project was published.

  • The element is identified by the class name published.
  • A projecta MAY include a published date.
  • The element MUST follow the conventions outlined in hAtom 0.1.
  • The Datetime Design Pattern SHOULD be used to encode the published datetime.
  • The element is considered experimental and may be removed from the final specification.

tag

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

  • The element is identified by class name tag.
  • A projecta MAY include one or more tag elements.
  • The element MUST follow the conventions outlined in rel="tag".

photo

Accompanying image.

  • The element is identified by the class name photo.
  • A projecta MAY include one or more photo elements.
  • The element SHOULD use an <img> element.
  • The element MAY use any other element that contains a URL, such as <a> or <object>, but it is not recommended.
  • The contents of the element MUST follow the conventions outlined in hCard 1.0.

requirement

Describes one or more requirements of the project.

  • The element is identified by the class name requirement.
  • A projecta MUST include one or more requirements.
  • The field MAY include valid HTML markup (e.g. a list of requirements).

instructions

Documents the instructions required to complete the project.

  • The element is identified by the class name instructions.
  • A projecta MAY include a instructions element.
  • The field MAY include valid HTML markup e.g. paragraphs or a list of steps.

duration

The time it takes to complete the project described by the projecta. Multiple duration fields can be used to denote time taken per instruction.

  • The element is identified by the class name duration.
  • A projecta MAY include one or more durations.
  • The element MUST follow the conventions outlined in hCalendar 1.0.
<div class="projecta">
	<h3 class="fn">Germinating Seeds</h3>
	<p class="summary">
		How to germinate seeds in potting mix.<br />
	</p>
	<p class="vcard fn">Derek Lewis</p>
	<p>Published <abbr class="published" title="2009-03-28T09:30-11:00">28. Mar 2009</abbr></p>
	<img src="/img/seed.png" class="photo" width="100" height="100" alt="Seed"/>
	<h4>Requirements</h4>
	<ul class="requirement">
		<li>Container(s) (With drain holes)</li>
		<li>Seed(s)</li>
		<li>Potting Mix</li>
		<li>Fresh Water</li>
		<li>A Light Source</li>
	</ul>
	<h4>Instructions</h4>
	<ol class="instructions">
		<li>Loosen and dampen the potting mix.</li>
		<li>Fill 2/3 of each container(s) with potting mix.</li>
		<li>Put seed(s) in container with potting mix.</li>
		<li>Sprinkle a few drops of water over of the seed(s). (Remember to repeat this once potting mix becomes dry.)</li>
		<li>Place container under light source.</li>
	</ol>
</div>