Re: $variables

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

Received on Friday, 8 July 2016 19:11:58 UTC