--- a/model/comments/issue-332-Simon.txt Fri Apr 13 17:13:06 2012 +0100
+++ b/model/comments/issue-332-Simon.txt Fri Apr 13 17:20:34 2012 +0100
@@ -13,15 +13,23 @@
- Bullet 4: "identifier always occur"
- Bullet 4: "with optional identifier"
+PM done.
+
5. I notice that PROV-N has no plan(...) construct, while PROV-O has a Plan class (also raised in my review of PROV-O). Might this cause issues translating between them?
+PM this is rather a PROV-O issue
+
6. Considering the document as a whole, its real purpose seems a little unclear to me. Is it meant to be (a) the grammar of PROV-N, or (b) an explanation of the grammar of PROV-N? The document seems maybe too heavyweight for (a) and too minimal for (b).
In more detail, if it is just intended to be a grammar for a language whose meaning is explained elsewhere (the DM spec), then why include examples, subsections, introductory boilerplate, and design rationale? That is, why not just have a file containing the EBNF?
If it is supposed to explain the grammar, so helping those constructing PROV-N or reading PROV-N others have constructed, then I find it too light. To take an example from the document, if a user reads "actedOnBehalfOf(r, ag2, ag3, a, [prov:type="contract"])" in some PROV-N data, then looks up the expression in Section 4.2.4 of the PROV-N document, they will not understand what it means, and will not know which agent is acting on behalf of which other (as all the parameter names are opaque with regard to their role). They could understand from looking in the DM spec, but then the PROV-N document is not needed for explanation after all.
+PM the plan here is to blend the DM descriptions for each relation in as part of the production descriptions, in a way that can be shown/hidden on demand. This has not been achieved yet.
+
There is one piece of explanation of expressions' meaning at the end of Section 2, that the subject of the relation precedes its object, but this seems inadequate for understanding most expressions and inconsistent with the lack of explanation of meaning elsewhere in the document.
+PM that is a general consideration, I have tried to explain it better, see also my comment to the previous point.
+
I'm not sure what to suggest to resolve this point, except to consider whether the content of the document really fits its intended use, as it wasn't entirely clear to me that this is the case now.
--- a/model/prov-n.html Fri Apr 13 17:13:06 2012 +0100
+++ b/model/prov-n.html Fri Apr 13 17:20:34 2012 +0100
@@ -270,8 +270,9 @@
</ul>
This document introduces the PROV-N grammar along with examples of its usage.<br/>
-Its target audience includes both developers of provenance management application, as well as implementors of new PROV-DM encodings, and thus in particular of PROV-N parsers. It also includes those readers of the [[PROV-DM]] and of [[PROV-DM-CONSTRAINTS]] documents, who are interested in the details of the formal language underpinning the notation used in the examples and in the definition of the constraints.
-
+Its target audience includes multiple roles. <br/>
+Firstly, it includes developers of provenance management applications, as well as implementors of new PROV-DM encodings, and thus in particular of PROV-N parsers. These readers may be interested in the entire structure of the grammar, starting from the top level nonterminal <a href="#ExpressionContainer">container</a>.
+Secondly, it also includes those readers of the [[PROV-DM]] and of [[PROV-DM-CONSTRAINTS]] documents, who are interested in the details of the formal language underpinning the notation used in the examples and in the definition of the constraints. Those readers may find the <a href="#grammar-notation">expression</a> nonterminal a useful entry point into the grammar.
</section>
@@ -320,14 +321,16 @@
</section>
+<section id="general-conventions">
+<h3>General grammar considerations</h3>
-<section id="grammar-notation">
+<section id="functional-syntax">
<h3>Functional-style Syntax</h3>
<p> PROV-N adopts a functional-style syntax consisting of a predicate name and an ordered list of terms.
All PROV-DM predicates involve two primary elements, the <em>subject</em> and the <em>object</em>, in this order. Furthermore, some predicates also admit additional elements that further characterize it.
<div class="anexample">
-The following expression should be read as "<span class="name">e2</span> was generated by <span class="name">e1</span>". Here <span class="name">e2</span> is the subject, and <span class="name">e1</span> is the object.
+The following expression should be read as "<span class="name">e2</span> was derived from <span class="name">e1</span>". Here <span class="name">e2</span> is the subject, and <span class="name">e1</span> is the object.
<pre class="codeexample" >
wasDerivedFrom(e2, e1)
</pre>
@@ -341,6 +344,11 @@
</pre>
</div>
+</section>
+
+<section id="grammar-notation">
+<h3>EBNF Grammar</h3>
+
The grammar is specified using the Extended Backus-Naur Form (EBNF) notation.<br/>
<div class="grammar">
Each production rule (or <dfn>production</dfn>, for short) in the grammar defines one non-terminal symbol <span class="nonterminal">E</span>, in the following form:</p>
@@ -373,9 +381,7 @@
</ul>
</div>
-<div class="note">this is confusing. look at http://www.w3.org/TR/owl2-syntax/#BNF_Notation for example</div>
-
-The most relevant nonterminal for the purpose of understanding the overall grammar is <span class="nonterminal">expression</span>, defined as follows.
+The grammar is centered on nonterminals for various types of <span class="nonterminal">expression</span>. The main production is introduced here below as it reflects the rationale for the design of the entire grammar. Note that parser developers may use the top level <a href="#ExpressionContainer">container</a> nonterminal as a starting point instead.
<div class='grammar'>
<table style="background: white; border=0; ">
@@ -423,11 +429,10 @@
</section>
-<section id="prov-n-conventions">
-<h3>General grammar conventions</h3>
+<!--
The following conventions are introduced concerning the specification of optional terms in an expression, of default terms, and of terms whose value is not specified, either because it is not available, or because it does not apply.
-
+-->
<section id="prov-n-optionals">
<h3>Optional terms in expressions</h3>
@@ -513,15 +518,13 @@
</section>
-
-</section> <!-- conventions for optionals etc. -->
+</section>
<section id="prov-n-expressions">
<h2>PROV-N Productions per Component</h2>
This section introduces grammar productions for each expression type, followed by small examples illustrating the use of expressions in PROV-N. </p>
-
<section id="component1">
<h3>Component 1: Entities and Activities</h3>
@@ -530,9 +533,9 @@
<div class="withPn">
<p>
- The <span class="nonterminal">entityExpression</span> production is used to express entities:
- <div class="note">only changed here to see if it works</div>
+<p> The <span class="nonterminal">entityExpression</span> production encodes entity predicates.</p>
+
</p>
<div class='grammar'>
@@ -563,10 +566,14 @@
<div class="anexample">
<pre class="codeexample">
-entity(tr:WD-prov-dm-20111215)
entity(tr:WD-prov-dm-20111215, [ prov:type="document" ])
-entity(tr:WD-prov-dm-20111215, [ prov:type="document", ex:version=2 ])
</pre>
+ Here <span class="name">tr:WD-prov-dm-20111215</span> is the optional entity identifier, and <span class="name">[ prov:type="document" ]</span> groups the optional attributes with their values.
+ <pre class="codeexample">
+<!-- entity(tr:WD-prov-dm-20111215, [ prov:type="document", ex:version=2 ]) -->
+entity(tr:WD-prov-dm-20111215)
+</pre>
+Here the optional attributes are not used.
</div>
@@ -575,10 +582,7 @@
<section id="expression-Activity">
<h4>Activity</h4>
-
-<div class="withPn">
-<p>An activity's text matches the <span class='nonterminal'>activityExpression</span> production.</p>
-
+ <p>The <span class="nonterminal">activityExpression</span> production encodes activity predicates.</p>
<div class='grammar'>
@@ -597,13 +601,17 @@
<div class="anexample">
<pre class="codeexample">
+activity(ex:a10, 2011-11-16T16:00:00, 2011-11-16T16:00:01, [prov:type="createFile"])
+</pre>
+Here <span class="name">ex:a10</span> is the optional activity identifier, <span class="name">2011-11-16T16:00:00</span> and <span class="name">2011-11-16T16:00:01</span> are the optional start and end times for the activity, and <span class="name">[prov:type="createFile"]</span> are optional attributes. <br/>
+The remaining examples show cases where some of the optionals are omitted.
+<pre class="codeexample">
activity(ex:a10)
activity(ex:a10, -, -)
activity(ex:a10, -, -, [prov:type="edit"])
activity(ex:a10, -, 2011-11-16T16:00:00)
activity(ex:a10, 2011-11-16T16:00:00, -)
activity(ex:a10, 2011-11-16T16:00:00, -, [prov:type="createFile"])
-activity(ex:a10, 2011-11-16T16:00:00, 2011-11-16T16:00:01, [prov:type="createFile"])
activity(ex:a10, [prov:type="edit"])
</pre>
</div>
@@ -615,7 +623,7 @@
<div class="withPn">
-<p>A generation's text matches the <span class='nonterminal'>generationExpression</span> production.</p>
+ <p>The <span class="nonterminal">generationExpression</span> production encodes generation predicates.</p>
<div class='grammar'>
<span class="nonterminal">generationExpression</span> ::=
@@ -632,13 +640,20 @@
</div>
<div class="anexample">
+
+<pre class="codeexample">
+wasGeneratedBy(ex:g1, tr:WD-prov-dm-20111215, ex:edit1, 2011-11-16T16:00:00, [ex:fct="save"])
+</pre>
+ Here <span class="name">ex:g1</span> is the optional generation identifier, <span class="name">tr:WD-prov-dm-20111215</span> is the identifier of the entity being generated,
+ <span class="name">ex:edit1</span> is the optional identifier of the generating activity, <span class="name">2011-11-16T16:00:00</span> is the generation time, and <span class="name"> [ex:fct="save"]</span> are optional attributes. <br/>
+The remaining examples show cases where some of the optionals are omitted.
+
<pre class="codeexample">
wasGeneratedBy(tr:WD-prov-dm-20111215, ex:edit1, -)
wasGeneratedBy(tr:WD-prov-dm-20111215, ex:edit1, 2011-11-16T16:00:00)
wasGeneratedBy(e2, a1, -, [ex:fct="save"])
wasGeneratedBy(e2, -, -, [ex:fct="save"])
wasGeneratedBy(ex:g1, tr:WD-prov-dm-20111215, ex:edit1, -)
-wasGeneratedBy(ex:g1, tr:WD-prov-dm-20111215, ex:edit1, 2011-11-16T16:00:00)
wasGeneratedBy(-, tr:WD-prov-dm-20111215, ex:edit1, -)
</pre>
</div>
@@ -652,8 +667,7 @@
<section id="expression-Usage">
<h4>Usage</h4>
-
-<p>A usage's text matches the <span class='nonterminal'>usageExpression</span> production.</p>
+ <p>The <span class="nonterminal">usageExpression</span> production encodes usage predicates.</p>
<div class='grammar'>
<span class="nonterminal">usageExpression</span> ::=
@@ -684,9 +698,8 @@
<section id="expression-Start">
<h4>Start</h4>
-<p>An activity start's text matches the <span class="nonterminal">startExpression</span> production of the grammar
-</p>
+ <p>The <span class="nonterminal">startExpression</span> production encodes activity start predicates.</p>
<div class='grammar'>
<span class="nonterminal">startExpression</span> ::=
@@ -722,9 +735,7 @@
<section id="expression-End">
<h4>End</h4>
-<p>An activity end's text matches the <span class="nonterminal">endExpression</span> production of the grammar.
-</p>
-
+ <p>The <span class="nonterminal">endExpression</span> production encodes activity end predicates.</p>
<div class='grammar'>
<span class="nonterminal">endExpression</span> ::=
@@ -759,6 +770,9 @@
<section id="expression-wasInformedBy">
<h4>Communication</h4>
+ <p>The <span class="nonterminal">communicationExpression</span> production encodes communication predicates.</p>
+
+
<div class="grammar">
<span class="nonterminal">communicationExpression</span> ::=
@@ -787,6 +801,8 @@
<section id="expression-startByActivity">
<h4>Start by Activity</h4>
+ <p>The <span class="nonterminal">startByActivityExpression</span> production encodes Start-by-Activity predicates.</p>
+
<div class="grammar">
<span class="nonterminal">startByActivityExpression</span> ::=
<span class="name">wasStartedByActivity</span>
@@ -819,10 +835,7 @@
<section id="expression-Agent">
<h4>Agent</h4>
-
-<div class="withPn">
-<p>An agent's text matches the <span class="nonterminal">agentExpression</span> production.
-</p>
+ <p>The <span class="nonterminal">agentExpression</span> production encodes Agent predicates.</p>
<div class='grammar'>
@@ -847,6 +860,8 @@
<section id="expression-attribution">
<h4>Attribution</h4>
+ <p>The <span class="nonterminal">attributionExpression</span> production encodes Attribution predicates.</p>
+
<div class="grammar">
<span class="nonterminal">attributionExpression</span> ::=
<span class="name">wasAttributedTo</span>
@@ -874,8 +889,8 @@
<section id="expression-Association">
<h4>Association</h4>
-<p>An association's text matches the <span class="nonterminal">activityAssociationExpression</span> productions of the grammar defined in this specification
-document.</p>
+ <p>The <span class="nonterminal">associationExpression</span> production encodes Association predicates.</p>
+
<div class='grammar'>
<span class="nonterminal">associationExpression</span> ::=
@@ -913,6 +928,8 @@
<section id="expression-responsibility">
<h4>Responsibility</h4>
+ <p>The <span class="nonterminal">responsibilityExpression</span> production encodes Responsibility predicates.</p>
+
<div class='grammar'>
<span class="nonterminal">responsibilityExpression</span> ::=
<span class="name">actedOnBehalfOf</span>
@@ -946,7 +963,7 @@
<section id="Derivation-Relation">
<h4>Derivation</h4>
-<p>A derivation expression's text matches the <span class='nonterminal'>derivationExpression</span> production.</p>
+ <p>The <span class="nonterminal">derivationExpression</span> production encodes Derivation predicates.</p>
<div class='grammar'>
<span class="nonterminal">derivationExpression</span> ::=
@@ -988,6 +1005,9 @@
<section id="expression-Revision">
<h4>Revision</h4>
+ <p>The <span class="nonterminal">revisionExpression</span> production encodes Revision predicates.</p>
+
+
<div class="grammar">
<span class="nonterminal">revisionExpression</span> ::=
<span class="name">wasRevisionOf</span>
@@ -1019,7 +1039,7 @@
<section id="expression-quotation">
<h4>Quotation</h4>
-<p>A quotation expression's text matches the <span class="nonterminal">quotationExpression</span> production of the grammar.</p>
+ <p>The <span class="nonterminal">quotationExpression</span> production encodes Quotation predicates.</p>
<div class="grammar">
<span class="nonterminal">quotationExpression</span> ::=
@@ -1059,7 +1079,7 @@
<section id="expression-original-source">
<h4>Original Source</h4>
-<p>An original source record's text matches the <span class="nonterminal">originalSourceExpression</span> production of the grammar.</p>
+ <p>The <span class="nonterminal">quotationExpression</span> production encodes Original Source predicates.</p>
<div class="grammar">
<span class="nonterminal">originalSourceExpression</span> ::=
@@ -1087,8 +1107,7 @@
<section id="expression-traceability">
<h4>Traceability</h4>
-<p>A traceability expression's text matches the <span class="nonterminal">traceabilityExpression</span> production of the grammar.</p>
-
+ <p>The <span class="nonterminal">traceabilityExpression</span> production encodes Traceability predicates.</p>
<div class="grammar">
<span class="nonterminal">traceabilityExpression</span> ::=
@@ -1119,7 +1138,7 @@
<section id="expression-alternate">
<h4>Alternate</h4>
-<p>An alternate relation's text matches the <span class="nonterminal">alternateExpression</span> production.</p>
+ <p>The <span class="nonterminal">alternateExpression</span> production encodes Alternate predicates.</p>
<div class='grammar'>
<span class="nonterminal">alternateExpression</span> ::=
@@ -1142,7 +1161,7 @@
<section id="expression-specialization">
<h4>Specialization</h4>
-<p>A specialization relation's text matches the <span class="nonterminal">specializationExpression</span> production.</p>
+ <p>The <span class="nonterminal">specializationExpression</span> production encodes Specialization predicates.</p>
<div class='grammar'>
<span class="nonterminal">specializationExpression</span> ::=
@@ -1200,7 +1219,8 @@
<section id="expression-collection-insertion">
<h3>Insertion</h3>
-<p>A Derivation-by-Insertion relation's text matches the <span class="nonterminal">derivationByInsertionFromExpression</span> production.</p>
+ <p>The <span class="nonterminal">derivationByInsertionFromExpression</span> production encodes Insertion-into-collection predicates.</p>
+
<div class="grammar">
<span class="nonterminal">derivationByInsertionFromExpression</span> ::=
<span class="name">derivedByInsertionFrom</span>
@@ -1232,7 +1252,7 @@
<section id="expression-collection-removal">
<h3>Removal</h3>
-<p>A Derivation-by-Removal relation's text matches the <span class="nonterminal">derivationByRemovalFromExpression</span> production.</p>
+ <p>The <span class="nonterminal">derivationByRemovalFromExpression</span> production encodes Removal-from-collection predicates.</p>
<div class="grammar">
<span class="nonterminal">derivationByRemovalFromExpression</span> ::=
@@ -1265,7 +1285,7 @@
<section id="expression-collection-membership">
<h3>Membership</h3>
-<p>A Membership relation's text matches the <span class="nonterminal">membershipExpression</span> production.</p>
+ <p>The <span class="nonterminal">membershipExpression</span> production encodes collection Membership predicates.</p>
<div class="grammar">
<span class="nonterminal">membershipExpression</span> ::=
@@ -1301,10 +1321,7 @@
<section id="expression-note">
<h4>Note</h4>
-<div class="withPn">
-<p>A note's text matches the <span class="nonterminal">noteExpression</span> production.
-</p>
-
+ <p>The <span class="nonterminal">noteExpression</span> production encodes Note predicates.</p>
<div class='grammar'>
<span class="nonterminal">noteExpression</span> ::=
@@ -1327,9 +1344,7 @@
<section id="expression-annotation">
<h4>Annotation</h4>
-
-<p>A note's text matches the <span class="nonterminal">noteExpression</span> production.
-</p>
+ <p>The <span class="nonterminal">annotationExpression</span> production encodes Annotation predicates.</p>
<div class='grammar'>
<span class="nonterminal">annotationExpression</span> ::=