Re: $variables

On 7/7/16 4:59 PM, Holger Knublauch wrote:
>
>
> On 8/07/2016 9:45, Karen Coyle wrote:
>>
>>
>> On 7/7/16 3:42 PM, Holger Knublauch wrote:
>>>
>>>
>>> On 8/07/2016 8:35, Karen Coyle wrote:
>>>> On the call today I was told that the way to avoid the complication of
>>>> the $variables in the spec is to choose not to view the SPARQL in the
>>>> draft. However, even with the SPARQL hidden, the $variables are still
>>>> visible since they are part of the explanatory text. So this does not
>>>> solve the problem, and in fact it probably makes it worse because
>>>> without the SPARQL the $variables make even less sense. For example,
>>>> with SPARQL definitions hidden, you see:
>>>>
>>>> **********
>>>>
>>>> 2.1.1 Node scopes (sh:scopeNode)
>>>>
>>>> A node scope with value $scopeNode, defines $scopeNode as the node
>>>> in-scope in the data graph.
>>>>
>>>> Node scopes are defined with the sh:scopeNode predicate. The values of
>>>> sh:scopeNode can be a IRIs or literals.
>>>>
>>>> *************
>>>>
>>>> I think they need to be removed from the text, and moved into the
>>>> SPARQL code area, and the text should be complete without using them.
>>>
>>> That would be fine with me. I had used the values in SPARQL-like $
>>> notation to make it easier to read for those who are familiar with
>>> SPARQL because the SPARQL query and its description would match. But if
>>> the WG thinks this is too geeky, we can just drop the $ sign and change
>>> the CSS style around these variables.
>>>
>>> I do wonder what audience are we talking about here? What in particular
>>> is difficult to understand about the $ variables? The spec is not a
>>> tutorial...
>>>
>>> Holger
>>
>> Holger, you always trot out this "not a tutorial" like anyone who has
>> any problem with the spec is some kind of backward dunce. I wish you
>> would be less condescending and more open to hearing suggestions. The
>> folks who brought this up are key RDF programmers on projects like
>> Europeana and DPLA. Hardly novices. But believe them when they say
>> that it makes the reading and comprehension more difficult. Do not
>> disparage them.
>
> The suggested change here is to drop the $ character before variable
> names in the scope section. I am really surprised this would make a
> difference, but said I have no problems with that.

I'm pretty sure it isn't just a matter of dropping the $ - it doesn't 
make sense to say:

"A node scope with value scopeNode, defines scopeNode as the node 
in-scope in the data graph."

So some more adjustment of the text is going to be needed. Especially 
because there is sometimes more about SPARQL in the text, such as:

*********
2.1.1 Node scopes (sh:scopeNode)

A node scope with value $scopeNode, defines $scopeNode as the node 
in-scope in the data graph.

Node scopes are defined with the sh:scopeNode predicate. The values of 
sh:scopeNode can be a IRIs or literals.

The following SPARQL query specifies the semantics of node scopes. The 
variable $scopeNode is assumed to be pre-bound to the given value of 
sh:scopeNode.

*******

It doesn't make sense to say "The following SPARQL query...." when the 
SPARQL query is hidden.

If we can agree on parameters of the edits, I'd be happy to pitch in a 
do some or all of the work. I'd say that the last paragraph belongs with 
the SPARQL code, and the first sentence needs a different value example, 
which should be uniform throughout where possible.

I'd also reverse the first two paragraphs, which I think increases 
readability.

kc

>
> What else would be needed to make the document more readable for the
> audience you are referring to?
>
> Anyway, I think you are over-reacting in your personal criticism. I am
> merely collecting information to help me fulfill my editing role. If I
> were to accept every single viewpoint without asking for clarifications
> we would never reach a fixpoint - there are just too many different
> viewpoints and potential audiences here.
>
> Holger
>
>
>

-- 
Karen Coyle
kcoyle@kcoyle.net http://kcoyle.net
m: 1-510-435-8234
skype: kcoylenet/+1-510-984-3600

Received on Friday, 8 July 2016 03:52:30 UTC