Late updates from #441 (#446)

Author: TallTed

shacl12-node-expr/index.html

@@ -562,10 +562,10 @@ <h3>Document Conventions</h3>
 			<h2>Getting started with Node Expressions</h2>
 			<p><em>This section is informative.</em></p>
 			<p>
-				SHACL <a>shapes graphs</a> can declare node expressions as values of various properties where dynamic computation is useful,
+				A SHACL <a>shapes graph</a> can declare node expressions as values of various properties where dynamic computation is useful,
 				such as <code>sh:targetNode</code>, <code>sh:values</code> and <code>sh:deactivated</code>.
-				Node expressions are represented by RDF nodes and can be evaluated to produce a list of <a>output nodes</a>.
-				For example when used at <code>sh:targetNode</code>, a node expression produces the list
+				A node expression is represented by an RDF node and can be evaluated to produce a list of <a>output nodes</a>.
+				For example, when used at <code>sh:targetNode</code>, a node expression produces the list
 				of target nodes of a <a>shape</a>.
 				When used at <code>sh:values</code>, a node expression produces the derived values for the property specified by <code>sh:path</code>.
 			</p>
@@ -602,11 +602,11 @@ <h2>Getting started with Node Expressions</h2>
 				The following diagram illustrates how this node expression is interpreted, from a logical point of view.
 				During validation, a SHACL processor will determine the <a>target</a> nodes of the shape
 				by evaluating the <a>filterShape expression</a>.
-				The filterShape expression, however, first evaluates its input expression, which is specified via <code>sh:nodes</code>
+				However, the filterShape expression first evaluates its input expression, which is specified via <code>sh:nodes</code>
 				and is an <a>instancesOf expression</a>.
-				This will produce all instances of the given class <code>ex:Company</code>.
-				The <code>sh:filterShape</code> is then applied to all of these instances, to only keep the companies
-				that <a>conform</a> to the provided <a>shape</a> by having their headquarter in Estonia.
+				This will produce all instances of the given class, <code>ex:Company</code>.
+				The <code>sh:filterShape</code> is then applied to all of these instances, to keep only the companies
+				that <a>conform</a> to the provided <a>shape</a>, by having their headquarters in Estonia.
 			</p>
 			<div>
 				<img 
@@ -616,8 +616,8 @@ <h2>Getting started with Node Expressions</h2>
 				>
 			</div>
 			<p>
-				The same scenario as above can also be expressed using SPARQL <a href="shacl12-sparql#SelectExpression">select expressions</a>.
-				Specific implementations of the SHACL node expressions may (for example for performance reasons)
+				The scenario above can also be expressed using SPARQL <a href="shacl12-sparql#SelectExpression">select expressions</a>.
+				For performance reasons, for example, specific implementations of SHACL node expressions might
 				internally convert node expressions such as the <code>sh:filterShape</code> above to SPARQL.
 			</p>
 			<p>
@@ -688,10 +688,10 @@ <h2>Getting started with Node Expressions</h2>
 				>
 			</div>
 			<p>
-				A difference between this example and the previous examples about <code>sh:targetNode</code>
+				One difference between this example and the previous examples about <code>sh:targetNode</code>
 				is that these node expressions are evaluated against a given <a>focus node</a>.
-				So when a data visualization needs to render an instance of <code>ex:Company</code>,
-				the currently displayed company is the <a>focus node</a>, from which the number of employees
+				This means that when a data visualization needs to render an instance of <code>ex:Company</code>,
+				the currently displayed company is the <a>focus node</a>, for which the number of employees
 				will be fetched.
 			</p>
 			<p class="todo">Clarify when these derived properties can be used (e.g. in sh:path expressions but not as triples elsewhere)</p>
@@ -705,30 +705,30 @@ <h2>Node Expression Syntax</h2>
 			<p>
 				The term <a>node expression function</a> refers to the <em>kind</em> or <em>type</em>
 				of a <a>node expression</a>.
-				For example, <code>sh:FilterShapeExpression</code> is a <a>node expression function</a>
+				For example, <code>sh:FilterShapeExpression</code> is a <a>node expression function</a>,
 				while a specific instance of this function in the <a>graph</a> is the <a>node expression</a> itself.
 			</p>
 			<p>
 				The most basic node expression functions are <a>constant node expressions</a>, which are either
-				<a>literals</a> or <a>IRIs</a> and simply evaluate to these constants.
-				All other node expressions are represented by <a>blank nodes</a> and come in the following two variations.
+				<a>literals</a> or <a>IRIs</a>, and simply evaluate to these constants.
+				All other node expressions are represented by <a>blank nodes</a>, and come in the following two variations:
 			</p>
 			<ul>
 				<li>
-					<a>Named parameter functions</a> are represented by a <a>blank node</a> that is the subject of one or more
+					A <a>named parameter function</a> is represented by a <a>blank node</a> that is the subject of one or more
 					triples, including the <a>key parameter</a> of the node expression function.
 				</li>
 				<li>
-					<a>List parameter functions</a> are comparable to traditional functions in, for example, SPARQL
-					and are represented by a <a>blank node</a> that is the subject of a single triple with a SHACL list as its object.
+					A <a>list parameter function</a> is comparable to a traditional function in SPARQL, for example,
+					and is represented by a <a>blank node</a> that is the subject of a single triple with a SHACL list as its object.
 				</li>
 			</ul>
 
 			<section id="ConstantNodeExpression">
 				<h3>Constant Node Expressions</h3>
 				<p>
 					The <a>node expression functions</a> in this section are called <dfn>constant node expressions</dfn>.
-					They were introduced in the SHACL Core specification but are repeated here to keep this document self-contained.
+					They were introduced in the SHACL Core specification and are repeated here to keep this document self-contained.
 				</p>
 
 				<section id="IRIExpression">
@@ -782,22 +782,28 @@ <h3>Named Parameter Functions</h3>
 						that is represented by a <a>blank node</a> that is the <a>subject</a> of at least
 						one <a>triple</a> where the <a>predicate</a> can be used to uniquely identify the function,
 						which is known as the <dfn>key parameter</dfn>.
+					<p>
+					  The evaluation of a <a>named parameter function</a> can produce any of the following:
 					</p>
-<p>The evaluation of a <a>named parameter function</a> can produce either:
-<ul>
-<li>zero <a>output nodes</a>, i.e. the empty list</li>
-<li>one or more <a>output nodes</a>, i.e. a list of one or more nodes</li>
-<li>an <a>evaluation failure</a>, i.e. an (unexpected) error during the evaluation</li>
-</ul>
-</p>
-<p>
-						For example, the <a>named parameter function</a> <a href="#FilterShapeExpression">sh:FilterShapeExpression</a> has
-						<code>sh:filterShape</code> as its <a>key parameter</a>.
+					<ul>
+					  <li>zero <a>output nodes</a>,
+					    i.e., an empty list</li>
+					  <li>one or more <a>output nodes</a>,
+					    i.e., a list of one or more nodes</li>
+					  <li>an <a>evaluation failure</a>,
+					    i.e., an (unexpected) error during the evaluation</li>
+					</ul>
+					<p>
+						For example, the <a>named parameter function</a>
+						<a href="#FilterShapeExpression"><code>sh:FilterShapeExpression</code></a>
+						has <code>sh:filterShape</code> as its <a>key parameter</a>.
 						In this document, key parameters are marked in <b>bold face</b>.
 					</p>
 					<p>
-						Expressions based on <a>named parameter functions</a> often take other <a>node expressions</a>
-						as arguments, evaluate those input node expressions and then produce a different list of <a>nodes</a>
+						Expressions based on <a>named parameter functions</a> often
+						take other <a>node expressions</a> as arguments,
+						evaluate those input node expressions,
+						and then produce a different list of <a>nodes</a>
 						as <a>output nodes</a>.
 					</p>
 					<p><em>The remainder of this section is informative.</em></p>
@@ -815,32 +821,32 @@ <h3>List Parameter Functions</h3>
 						The <a>predicate</a> of this <a>triple</a> is called the <dfn>list parameter property</dfn>.
 					</p>
 					<p>
-						The <a>evaluation</a> of a <a>list parameter function</a> can produce either:
+						The <a>evaluation</a> of a <a>list parameter function</a> can produce any of the following:
 					</p>
 					<ul>
-						<li>one <a>output node</a>, i.e. a list of one <a>node</a></li>
-						<li>zero <a>output nodes</a>, i.e. the empty list</li>
-						<li>an <a>evaluation failure</a>, i.e. an (unexpected) error during the evaluation</li>
+						<li>one <a>output node</a>, i.e., a list of one <a>node</a></li>
+						<li>zero <a>output nodes</a>, i.e., an empty list</li>
+						<li>an <a>evaluation failure</a>, i.e., an (unexpected) error during the evaluation</li>
 					</ul>
 					<p>
-						Furthermore, all arguments of a <a>list parameter function</a> must evaluate to individual <a>nodes</a>
-						and not lists of nodes.
-						If an argument is a <a>node expression</a> then this <a>node expression</a> must evaluate to
-						at most one <a>output node</a>.
+						Furthermore, each argument of a <a>list parameter function</a> must evaluate to an individual, single <a>node</a>,
+						not to a list of nodes.
+						If an argument is a <a>node expression</a>, then this <a>node expression</a> must evaluate to
+						a maximum of one <a>output node</a>.
 						An <a>evaluation failure</a> must be produced if there is more than one <a>output node</a>.
 						This is different from <a>named parameter functions</a>, where arguments may produce lists of multiple nodes.
 					</p>
 					<p><em>The remainder of this section is informative.</em></p>
 					<p>
-						Note that some <a>named parameter functions</a> such as <code>sh:IntersectionExpression</code>
-						also use <a>SHACL lists</a> as object of the <a>key parameter</a>, similar to <a>list parameter functions</a> which always have <a>SHACL lists</a> as object of their <a>list parameter property</a>.
-						However, these may produce more than one <a>output nodes</a> and also accept lists as input nodes.
+						Note that some <a>named parameter functions</a> &mdash; such as <code>sh:IntersectionExpression</code> &mdash;
+						also use a <a>SHACL list</a> as an object of the <a>key parameter</a>, similar to <a>list parameter functions</a> which always have a <a>SHACL list</a> as the object of their <a>list parameter property</a>.
+						However, these may produce more than one <a>output nodes</a>, and also accept lists as input nodes.
 					</p>
 					<p>
-						The following example uses multiple (imaginary) <a>list parameter functions</a>
-						<code>ex:coalesce</code> and <code>ex:concat</code> to compute the <code>ex:displayName</code>
+						The following example uses multiple (imaginary) <a>list parameter functions</a> &mdash;
+						<code>ex:coalesce</code> and <code>ex:concat</code> &mdash; to compute the <code>ex:displayName</code>
 						of a person as either the value of <code>ex:fullName</code> or (if that doesn't exist)
-						as the concatenation of first and last names, with a space in between.
+						as a concatenation of <code>ex:firstName</code>, a space, and <code>ex:lastName</code>.
 					</p>
 					<p>
 						<aside class="example" title="A comple node expression based on list parameter functions.">