- From: Dimitris Kontokostas <kontokostas@informatik.uni-leipzig.de>
- Date: Tue, 12 Jul 2016 20:04:45 +0300
- To: Karen Coyle <kcoyle@kcoyle.net>
- Cc: Arnaud Le Hors <lehors@us.ibm.com>, public-data-shapes-wg <public-data-shapes-wg@w3.org>
- Message-ID: <CA+u4+a04Kr5gbT+0k9_c5mMkqGNWcL80GCRuHU-LCriGxHQ0FA@mail.gmail.com>
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> 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>> 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>> >> To: Arnaud Le Hors/Cupertino/IBM@IBMUS >> Cc: Karen Coyle <kcoyle@kcoyle.net >> <mailto:kcoyle@kcoyle.net>>, public-data-shapes-wg >> <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>> 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>> wrote >> on 07/07/2016 08:52:00 PM: >> >> > From: Karen Coyle <_kcoyle@kcoyle.net_ <mailto:kcoyle@kcoyle.net>> >> > To: _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>_http://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://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 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
Received on Tuesday, 12 July 2016 17:05:48 UTC