- From: Karen Coyle <kcoyle@kcoyle.net>
- Date: Tue, 12 Jul 2016 21:39:10 -0700
- To: Dimitris Kontokostas <kontokostas@informatik.uni-leipzig.de>
- Cc: Arnaud Le Hors <lehors@us.ibm.com>, public-data-shapes-wg <public-data-shapes-wg@w3.org>
Thank you Dimitris - this is like a breath of fresh air. I tried the feature of hiding the SPARQL and it does hide the $variables and the text about the SPARQL, so this is now much more readable. kc On 7/12/16 10:04 AM, Dimitris Kontokostas wrote: > Hi Karen, all, > the scopes section is now re-worked and available for review in the > online version > > - http://w3c.github.io/data-shapes/shacl/#scopes > - > https://github.com/w3c/data-shapes/commit/674ddaa3f858df306cf3e8e8f9b2932ff9397bdf > > On Fri, Jul 8, 2016 at 10:11 PM, Karen Coyle <kcoyle@kcoyle.net > <mailto:kcoyle@kcoyle.net>> wrote: > > That's considerably better, Dimitris. I think that using the name of > the variable as the placeholder, which is done in other parts of the > spec, is a guarantee of confusion. As I recall, we fixed some of > those in the examples, but maybe now we should go through the text > as well. > > kc > > On 7/8/16 9:01 AM, Dimitris Kontokostas wrote: > > 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 <mailto:lehors@us.ibm.com> > <mailto:lehors@us.ibm.com <mailto: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 > <mailto:kontokostas@informatik.uni-leipzig.de> > <mailto:kontokostas@informatik.uni-leipzig.de > <mailto:kontokostas@informatik.uni-leipzig.de>>> > To: Arnaud Le Hors/Cupertino/IBM@IBMUS > Cc: Karen Coyle <kcoyle@kcoyle.net > <mailto:kcoyle@kcoyle.net> > <mailto:kcoyle@kcoyle.net <mailto:kcoyle@kcoyle.net>>>, > public-data-shapes-wg > <public-data-shapes-wg@w3.org > <mailto:public-data-shapes-wg@w3.org> > <mailto:public-data-shapes-wg@w3.org > <mailto: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_ > <mailto:lehors@us.ibm.com <mailto: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_ <mailto:kcoyle@kcoyle.net > <mailto:kcoyle@kcoyle.net>>> wrote > on 07/07/2016 08:52:00 PM: > > > From: Karen Coyle <_kcoyle@kcoyle.net_ > <mailto:kcoyle@kcoyle.net <mailto:kcoyle@kcoyle.net>>> > > To: _public-data-shapes-wg@w3.org_ > <mailto:public-data-shapes-wg@w3.org > <mailto: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_ <mailto:kcoyle@kcoyle.net > <mailto:kcoyle@kcoyle.net>>_http://kcoyle.net_ > <http://kcoyle.net/> > > > m: 1-510-435-8234 > > skype: kcoylenet/_+1-510-984-3600 <tel:%2B1-510-984-3600>_ > <tel:%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_ > Research Group: AKSW/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 > > > -- > Karen Coyle > kcoyle@kcoyle.net <mailto:kcoyle@kcoyle.net> http://kcoyle.net > m: 1-510-435-8234 > skype: kcoylenet/+1-510-984-3600 <tel:%2B1-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 > -- Karen Coyle kcoyle@kcoyle.net http://kcoyle.net m: 1-510-435-8234 skype: kcoylenet/+1-510-984-3600
Received on Wednesday, 13 July 2016 04:39:47 UTC