Re: $variables

Ok, but this isn't just a matter of hiding this when SPARQL is hidden. I 
still want to understand what that sentence means when SPARQL isn't 
hiddene. So, can you tell me what this sentence is supposed to be saying?

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

The way it reads to me is that a node scope has a variable $scopeNode as a 
value, and that this defines the variable as the "node in-scope". What 
does it mean for a scope node to have a value? And How does a node scope 
with a value define the value as the "node in-scope"? And shouldn't that 
rather be "node in scope"??

As I said I just can't parse this sentence. I'd appreciate if someone 
could rephrase.

Unfortunately the spec remains hard to read and understand because of 
stuff like this so I second the sentiment Karen conveys from the community 
she represents. I understand English isn't the editors' primary language 
and that's ok but given that I strongly encourage them to welcome comments 
pointing these problems out.

Thanks.
--
Arnaud  Le Hors - Senior Technical Staff Member, Open Web Technologies - 
IBM Cloud




From:   Dimitris Kontokostas <kontokostas@informatik.uni-leipzig.de>
To:     Arnaud Le Hors/Cupertino/IBM@IBMUS
Cc:     Karen Coyle <kcoyle@kcoyle.net>, public-data-shapes-wg 
<public-data-shapes-wg@w3.org>
Date:   07/08/2016 01:38 AM
Subject:        Re: $variables



You are right, 
although the button exists we the spec does not flow well in some cases 
when the sparql definitions are hidden
Holger created an issue to track this and we will try to have it ready for 
review by the next call

On Fri, Jul 8, 2016 at 8:09 AM, Arnaud Le Hors <lehors@us.ibm.com> wrote:
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
> 




-- 
Dimitris Kontokostas
Department of Computer Science, University of Leipzig & DBpedia 
Association
Projects: http://dbpedia.org, http://rdfunit.aksw.org, 
http://aligned-project.eu
Homepage: http://aksw.org/DimitrisKontokostas
Research Group: AKSW/KILT http://aksw.org/Groups/KILT