Linked function names of algebra operators, and markup of variables in Section 18.5, 18.5.1, and 18.5.2

[hartig]

One thing that has always bugged me is that the spec represents the operators of the abstract/algebraic syntax of SPARQL in exactly the same way as it represents the algebra functions used to define the evaluation semantics. As an example, consider the following formula from Section 18.5.2 Evaluation Semantics.

eval(D(G), Filter(F, P)) = Filter(F, eval(D(G),P), D(G))

The 'Filter' on the left-hand side of this formula represents an operator of the algebraic syntax (as introduced in the second table of Section 18.2 Translation to the SPARQL Algebra), whereas the 'Filter' on the right-hand side refers to the algebra operator defined in Section 18.5 SPARQL Algebra. As you can see, they look identical.

This has often been a source of confusion for me. While the formulas of the form as above become understandable once one has figured it out (which is not trivial for someone new coming to the spec), it is worse for cases in which something like 'Filter( ... )' is mentioned elsewhere, in particular just within text.

This PR is a first step towards fixing this issue. All mentions of the algebra operators are wrapped as links to their corresponding definition in Section 18.5 SPARQL Algebra, and these links have a dedicated CSS class attribute that allows us to make them visually different in the future. Additionally, the PR adds another such class attribute for the (earlier-introduced) links to the set functions, and it adds <var>..</var> markup for all formulas in Sections 18.5 SPARQL Algebra, 18.5.1 Aggregate Algebra, and 18.5.2 Evaluation Semantics. The example formula above looks as follows now.

eval( D(G), Filter(F, P) ) = Filter( F, eval(D(G), P), D(G) )

I am leaving it to a future PR to do something similar for the operators of the algebraic syntax (e.g., the 'Filter' on the left-hand side of this formula) in order to avoid making this PR too complex. For the same reason, this PR does not change any of the actual content.

---

Preview | Diff

[TallTed]

I will resist the temptation to read the actual content and revise for comprehension. :-)

I look forward to the near-future PR which does "something similar for the operators of the algebraic syntax", which actual content I will also ignore.

Then I will make my own review of the actual content of Sections 18.5 SPARQL Algebra, 18.5.1 Aggregate Algebra, and 18.5.2 Evaluation Semantics.

[hartig]

@TallTed I think there is plenty to revise. I have a bunch of ideas for improving the presentation of the formal parts, but my intention is to keep this separate from pure markup improvements to keep the PRs focused.

[Tpt]

Thank you so much for this work.

[afs]

Looks great and a good improvement.

I do find the linking "eval" as less useful because it occurs everywhere, several times, to the point of being a distracting.

However, it is the same HTML in the document. Possibly we could style it differently (e.g. no underline) at some point.

[hartig]

@afs I admit, I find the underlining of the now-linked (as per this PR) function names a bit ugly and distracting as well. The explicit CSS classes introduced by this PR do indeed allow us to style these particular links differently, removing the underlining.

Having said that, linking all the occurrences of the eval function to the start of the recursive definition of this function is useful, I think; in particular, because there is another function called "eval" in the spec, namely the one for Property Path patterns in Section 18.4 Property Path Patterns.

[kasei]

We seem to be losing existing anchors in this change. Could we preserve id values in adjacent markup (the enclosing <p> or <b> perhaps) to allow any existing deep links into the 1.1 spec to still work with the 1.2 spec?

[afs]

Elsewhere, and in other docs, there are empty span's e.g.<span id=><!-- comment --></span> or <span id=/>.

[hartig]

We seem to be losing existing anchors in this change. [...]

I checked that these anchors are not used anywhere in the spec, but you are right, someone else may have used them externally. I have restored them now (commit 38052ef) using empty <span> elements as we have already done elsewhere for other obsolete anchors.

[hartig]

@kasei with the anchors restored now, do you approve this PR?

[TallTed]

there is another function called "eval" in the spec

This makes me think that one of these functions should be renamed, and if any other names are used for multiple functions, that all but one of each such group should be renamed.

[afs]

It would be possible to call the other one "evalPath".

[hartig]

@hartig: there is another function called "eval" in the spec

@TallTed: This makes me think that one of these functions should be renamed [...]

@afs It would be possible to call the other one "evalPath".

I have created a separate issue for this, #218