- From: Karen Coyle <kcoyle@kcoyle.net>
- Date: Thu, 7 Jul 2016 20:52:00 -0700
- To: public-data-shapes-wg@w3.org
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
Received on Friday, 8 July 2016 03:52:30 UTC