Tidy up presentation of outstanding issues and TODOs in the document
authorGraham Klyne
Thu, 17 Nov 2011 17:15:44 +0000
changeset 953 bca4fcd1b63c
parent 941 8c10d4ec8b3f
child 954 ad9a0b38a946
Tidy up presentation of outstanding issues and TODOs in the document
paq/css/paq.css
paq/provenance-access.html
--- a/paq/css/paq.css	Thu Nov 17 11:55:13 2011 +0000
+++ b/paq/css/paq.css	Thu Nov 17 17:15:44 2011 +0000
@@ -23,6 +23,25 @@
 
 
 /* --- EDITORIAL NOTES (from model doc) --- */
+
+.TODO {
+    padding:    1em;
+    margin: 1em 0em 0em;
+    border: 1px solid #f00;
+    background: #ffc;
+}
+
+.TODO::before {
+    content:    "TODO";
+    display:    block;
+    width:  150px;
+    margin: -1.5em 0 0.5em 0;
+    font-weight:    bold;
+    border: 1px solid #f00;
+    background: #fff;
+    padding:    3px 1em;
+}
+
 .pending {
     padding:    1em;
     margin: 1em 0em 0em;
--- a/paq/provenance-access.html	Thu Nov 17 11:55:13 2011 +0000
+++ b/paq/provenance-access.html	Thu Nov 17 17:15:44 2011 +0000
@@ -121,7 +121,7 @@
     
     <section>
       <h2>Introduction</h2>
-      <p>
+      <p class="TODO">
         @@TODO Introductory text
       </p>
       
@@ -359,25 +359,10 @@
         <p>
           Another new RDF property, <code>prov:hasAnchor</code>, is defined to allow the RDF content to specify one or more <a class="internalDFN">entity-URI</a>s of the RDF document for the purpose of provenance information (similar to the use of the "anchor" link relation in HTML).
         </p>
-        <p class="issue">
-          @@TODO: needs to be completed.
-          <br/><br/>
-          Review choice of RDF property names
-          <br/><br/>
-          Discussion:
-          <br/><br/>
-          The containing RDF resource is the subject.  For RDF documents, this is sometimes written as an empty URI-reference; e.g.<br/>
-          <code>
-            &lt;rdf:Description rdf:about=""&gt;<br/>
-            &nbsp;&nbsp;&lt;prov:hasProvenance rdf:resource="(provenance_URI)"/&gt;<br/>
-            &lt;/rdf:Description&gt;<br/>
-          </code>
-          (If publishing the RDF in a named graph, then use the URI of the graph.)
-        </p>
-        <p>
+        <p class="TODO">
           @@TODO: example
         </p>
-        <p>
+        <p class="TODO">
           @@TODO: document namespace.  Check naming style.  Use provenance model namespace?  Define as part of model?
         </p>
       </section>
@@ -409,6 +394,9 @@
             </li>
           </ul>
         </p>
+        <p class="TODO">
+          Fix references in above text.
+        </p>
       </section>
 
     </section>
@@ -465,7 +453,7 @@
               <li>Dereference <code>service-URI</code> to obtain a representation of the <a class="internalDFN">service description</a>.</li>
               <li>Extract the provenance information template from the service description.</li>
               <li>Use the provenance information template with <code>context-URI</code> for template variable <code>uri</code> to form <code>provenance-URI</code>.</li>
-              <li>Dereference <code>provenance-URI</code> to obtain <a class="internalDFN">provenance information</a> (@@redundant, maybe misleading: as described by the Provenance Model specification [[PROV-MODEL]]@@).</li>
+              <li>Dereference <code>provenance-URI</code> to obtain <a class="internalDFN">provenance information</a>.</li>
             </ol>
           </p>
         </section>
@@ -587,7 +575,7 @@
             </pre>
           </code>
         </p>
-        <p class="issue">
+        <p class="TODO">
           @@TODO: specific provenance namespace and property to be determined by the model or ontology specification?
         </p>
       </section>
@@ -607,7 +595,7 @@
             </pre>
           </code>
         </p>
-        <p class="issue">
+        <p class="TODO">
           @@TODO: specific provenance namespace and property to be determined by the model specification?
         </p>
       </section>
@@ -634,7 +622,7 @@
           </code>
           This query essentially extracts all available properties and values available from the query service used that are directly about the specified entity, and returns them as an RDF graph.  This may be fine if the service contains <em>only</em> provenance information about the indicated resource, or if the non-provenance information is also of interest.  A more complex query using specific provenance vocabulary terms may be needed to selectively retrieve just provenance information when other kinds of information are also available.
         </p>
-        <p class="issue">
+        <p class="TODO">
           @@TODO: specific provenance namespace and property to be determined by the model specification?  The above query pattern assumes provenance information is included in direct properties about the entity.  When an RDF provenance vocabulary is formulated, this may well turn out to not be the case.  A better example would probably be one that retrieves specific provenance information when the vocabulary terms have been defined.
         </p>
       </section>
@@ -676,7 +664,10 @@
 
     <section>
       <h2>IANA considerations</h2>
-      <p>This document requests registration of new link relations, per <a href="http://tools.ietf.org/html/rfc5988#section-6.2.1">section-6.2.1 of RFC 5988</a>.  @@TODO At an appropriate time (??), the following templates should be submitted to link-relations@ietf.org:
+      <p>This document requests registration of new link relations, per <a href="http://tools.ietf.org/html/rfc5988#section-6.2.1">section-6.2.1 of RFC 5988</a>.
+      </p>
+      <p class="TODO">
+          @@TODO The following templates should be completed and submitted to link-relations@ietf.org:
       </p>
       <section>
         <h2>Registration template for link relation: "provenance"</h2>
@@ -777,10 +768,10 @@
       <p>
         When retrieving a provenance URI from a document, steps SHOULD be taken to ensure the document itself is an accurate copy of the original whose author is being trusted (e.g. signature checking, or verifying its checksum against an author-provided secure web service).
       </p>
-      <p>
-        @@TODO ... privacy, access control to provenance (from Edinburgh meeting).  In particular, note that the fact that a resource is openly accessible does not mean that its provenance information should also be.
+      <p class="TODO">
+        @@TODO ... privacy, access control to provenance (note to self: discussed in Edinburgh linked data provenance workshop).  In particular, note that the fact that a resource is openly accessible does not mean that its provenance information should also be.
       </p>
-      <p>
+      <p class="TODO">
         @@TODO ... more, probably
       </p>
     </section>
@@ -822,6 +813,9 @@
         <p class="note">
           The provenance URI templates are encoded in RDF as plain string literals, <em>not</em> as resource URIs.
         </p>
+        <p class="TODO">
+          Finalize URIs in the above example.
+        </p>
       </section>
 
       <section>
@@ -841,11 +835,14 @@
             &lt;/rdf:RDF&gt;
           </pre>
         </code>
+        <p class="TODO">
+          Finalize URIs in the above example.
+        </p>
       </section>
 
       <section>
         <h2>Plain XML example of service description</h2>
-        <p class="issue">
+        <p class="TODO">
           @@TODO: provide example and schema
         </p>
       </section>
@@ -868,7 +865,7 @@
         <p class="issue">
           NOTE: The namespace URI used here for the provenance properties is different from that used in the service description.  I am anticipating that it will be defined as part of the provenance model.  If it is not defined as part of the provenance model, then a property name should be allocated in the provenance discovery service namespace.
         </p>
-        <p class="issue">@@TODO: revise to conform with Provenance Model vocabulary</p>
+        <p class="TODO">@@TODO: revise to conform with Provenance Model vocabulary; review URIs</p>
       </section>
 
       <section>
@@ -896,7 +893,7 @@
 
       <section>
         <h2>Plain XML example of provenance locations</h2>
-        <p class="issue">
+        <p class="TODO">
           @@TODO: provide example and schema
         </p>
       </section>