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