Re: $variables

the confusing part here is $nodescope as Karen already noted. We use
$nodeScope as a variable placeholder here that is the confusing part, if
you replace this with an actual value things should be easier to understand

earlier we have

2.1 Scopes
Scopes specify which nodes in the data graph are considered in-scope for a
shape and SHACL includes four core scope types: node scopes, class-based
scopes, property scopes, and inverse property scopes.
...

2.1.1 Node scopes (sh:scopeNode)
e.g.
a node scope with value X, defines X as the node in-scope in the data graph
or
a node scope with value e.g. "ex:Node", defines "ex:Node" as the node
in-scope in the data graph

The way I would rephrase it is the following: remove the first sentence and
adjust the second one as this:
Node scopes <http://w3c.github.io/data-shapes/shacl/#dfn-node-scope> are
defined with the sh:scopeNode predicate. The values
<http://w3c.github.io/data-shapes/shacl/#dfn-values> of sh:scopeNode can be
a IRIs <http://w3c.github.io/data-shapes/shacl/#dfn-iri> or literals
<http://w3c.github.io/data-shapes/shacl/#dfn-literal>. Each value of a node
scope defines a node in-scope in the data graph


would this be easier to understand?


On Fri, Jul 8, 2016 at 6:11 PM, Arnaud Le Hors <lehors@us.ibm.com> wrote:

> 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*
> <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* <kcoyle@kcoyle.net>> wrote on 07/07/2016
> 08:52:00 PM:
>
> > From: Karen Coyle <*kcoyle@kcoyle.net* <kcoyle@kcoyle.net>>
> > To: *public-data-shapes-wg@w3.org* <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* <kcoyle@kcoyle.net>*http://kcoyle.net*
> <http://kcoyle.net/>
>
> > m: 1-510-435-8234
> > skype: kcoylenet/*+1-510-984-3600* <%2B1-510-984-3600>
> >
>
>
>
>
> --
> Dimitris Kontokostas
> Department of Computer Science, University of Leipzig & DBpedia Association
> Projects: *http://dbpedia.org* <http://dbpedia.org/>,
> *http://rdfunit.aksw.org* <http://rdfunit.aksw.org/>,
> *http://aligned-project.eu* <http://aligned-project.eu/>
> Homepage: *http://aksw.org/DimitrisKontokostas*
> <http://aksw.org/DimitrisKontokostas>
> Research Group: AKSW/KILT *http://aksw.org/Groups/KILT*
> <http://aksw.org/Groups/KILT>
>
>
>
>


-- 
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