--- a/farol/templates/document/edit_tracking.j2	Mon Oct 06 14:24:25 2014 +0200
+++ b/farol/templates/document/edit_tracking.j2	Mon Oct 06 14:44:33 2014 +0200
@@ -24,23 +24,52 @@
 -#}
 
 {% extends "base.j2" %}
-{% from "macros.j2" import textinput, textarea, selectinput, panel %}
+{% from "macros.j2" import textinput, textarea, selectinput, panel, examples %}
 {% block title %}Edit the type{% endblock %}
 
 {% block content %}
 <form role="form" method="POST">
 
-{{ textinput("id", "ID", value=tracking._identification._id, required=True) }}
-{{ textinput("id_aliases", "Aliases", value=', '.join(tracking._identification._aliases),
-             help="Multiple aliases should be separated by commas.") }}
-{{ selectinput("status", "Status", statuses, tracking._status) }}
-{{ textinput("version", "Version", value=version, required=True) }}
-{{ textinput("initial", "Initial Release Date", value=tracking._initialDate.isoformat(), required=True, type="datetime") }}
-{{ textinput("current", "Current Release Date", value=tracking._currentDate.isoformat(), required=True, type="datetime") }}
+{% call textinput("id", "ID", value=tracking._identification._id, required=True) %}
+<p><strong>ID</strong> is a short, unique identifier used to refer to the document unambiguously in any context. The ID is a simple label. It is a string data type to provide for a wide range of numbering values, types, and schemes. Typically, the ID should be assigned and maintained by the original document issuing authority. It is recommended that the ID be a monotonically increasing value, or increasing in such a predictable manner that it does not contribute toward confusion or misnumbering. Careful consideration is required to ensure that construction of the ID does not contribute to confusion or collision with other labels.</p>
+{{ examples(['01', '29834841', '0xABCDEF', '100-200-301']) }}
+{% endcall %}
+{% call textinput("id_aliases", "Aliases", value=', '.join(tracking._identification._aliases),
+             help="Multiple aliases should be separated by commas.") %}
+<p><strong>Alias</strong> is an optional alternative ID used to refer to the document. Many vendors have one or more alternative or secondary IDs for documents and the <strong>Alias</strong> presents an interface to publish those alongside the primary ID.</p>
+{% endcall %}
+{% call selectinput("status", "Status", statuses, tracking._status) %}
+<p><strong>Status</strong> refers to the condition of the document with regard to completeness and the likelihood of future editions.</p>
+<p>Status types are:</p>
+<ul>
+  <li><strong>Draft</strong>: Pre-release, intended for issuing party’s internal use only, or possibly used externally when the party is seeking feedback or indicating its intentions regarding a specific issue.</li>
+  <li><strong>Interim</strong>: The issuing party believes the content is subject to change.</li>
+  <li><strong>Final</strong>: The issuing party asserts the content is unlikely to change. “Final” status is an indication only, and does not preclude updates.</li>
+</ul>
+<p>Issuing parties are strongly recommended to set <strong>Status</strong> to <samp>Draft</samp> when initiating a new document and to implement procedures to ensure that the status is changed to the appropriate value before the document is released.</p>
+{% endcall %}
+{% call textinput("version", "Version", value=version, required=True) %}
+<p>Version is a simple counter to track the version of the document. This is a numeric tokenized field of the format “nn” – “nn.nn.nn.nn”. It may be incremented in either major or minor notation to denote clearly the evolution of the content of the document. Issuing parties must ensure that this field is incremented appropriately, even for the least editorial or grammatical changes, when the field is used. It is validated using the following regular expression: <code>(0|[1-9][0-9]*)(\.(0|[1-9][0-9]*)){0,3}</code>.</p>
+{{ examples(['1.0', '1.0.1', '1.0.0.1']) }}
+{% endcall %}
+{% call textinput("initial", "Initial Release Date", value=tracking._initialDate.isoformat(), required=True, type="datetime") %}
+<p><strong>Initial Release Date</strong> is the date (and time, optionally) that the document was initially released by the issuing party. All dateTime values in CVRF require a time, and we recommend the inclusion of a time zone as well (ICASI endorses the use of GMT or “Zulu time”). If a time zone is excluded, Zulu should be assumed.</p>
+{{ examples(['2011-11-26T00:00:00+00:00']) }}
+{% endcall %}
+{% call textinput("current", "Current Release Date", value=tracking._currentDate.isoformat(), required=True, type="datetime") %}
+<p><strong>Current Release Date</strong> is the current date (and time, optionally) that the document was released by the issuing party. All dateTime values in CVRF require a time, and we recommend the inclusion of a time zone as well (ICASI endorses the use of GMT or “Zulu time”). If a time zone is excluded, Zulu should be assumed.</p>
+{{ examples(['2011-11-26T00:00:00+00:00']) }}
+{% endcall %}
 
 {% call panel(heading="Generator", title=3, collapsible=False) %}
-  {{ textinput("gen_engine", "Generator Engine", value=generator._engine or '') }}
-  {{ textinput("gen_date", "Generator Date", now.isoformat(), generator._date and generator._date.isoformat() or None, type="datetime") }}
+  {% call textinput("gen_engine", "Generator Engine", value=generator._engine or '') %}
+  <p><strong>Engine</strong> will refer to the name and optional version of the engine that generated the CVRF document.</p>
+  {{ examples(['Mike Schiffman’s sublime fingertips version 1.0']) }}
+  {% endcall %}
+  {% call textinput("gen_date", "Generator Date", now.isoformat(), generator._date and generator._date.isoformat() or None, type="datetime") %}
+  <p><strong>Date</strong> will refer to the date the CVRF document was generated. Because documents are often generated internally by a document producer and exist for a nonzero amount of time before being released, this field can be different from the <strong>Initial Release Date</strong>. All dateTime values in CVRF require a time, and we recommend the inclusion of a time zone as well (ICASI endorses the use of GMT or “Zulu time”). If a time zone is excluded, Zulu should be assumed.</p>
+  {{ examples(['2012-02-27T00:00:00+00:00']) }}
+  {% endcall %}
 {% endcall %}
 
 <button class="btn btn-primary" type="submit">Update</button>