Re: $variables

I have to agree with Karen. In fact, I will admit that I don't understand 
what this sentence means:

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

Actually, I can't even quite parse this sentence. What's with that comma? 
What's the subject of "defines"?

I do understand the following:

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

Although the "a" seems to be a typo.
--
Arnaud  Le Hors - Senior Technical Staff Member, Open Web Technologies - 
IBM Cloud


Karen Coyle <kcoyle@kcoyle.net> wrote on 07/07/2016 08:52:00 PM:

> From: Karen Coyle <kcoyle@kcoyle.net>
> To: public-data-shapes-wg@w3.org
> Date: 07/07/2016 08:53 PM
> Subject: 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
>