Re: Comments on Model WD of 2015-10-15: Editorial comments

> On 16 Oct 2015, at 20:34, Robert Sanderson <azaroth42@gmail.com> wrote:
> 
> 
> Thanks for the comments, Ivan!
> 
> On Fri, Oct 16, 2015 at 12:44 PM, Ivan Herman <ivan@w3.org <mailto:ivan@w3.org>> wrote:
> 
> • All the references are marked as informative references. I do not think this is correct; some of those (reference to JSON-LD, Turtle, various RFC-s, etc) are clearly normative and should be marked as such. On the other hand, we will have to be careful not to use as normative reference a document that is still in flux (e.g., Jeni's document on fragment ID usage)
> 
> Agreed. That's my fault ... how do you get respec to put them in as normative references rather than informative?

If you use [[!blabla]] instead of [[blabla]], then respec will consider the former as normative and will automatically separate the references into two sections at the end.

> 
> • We have to separate the normative and informative sections in the document. Section 1, Appendix C, E, F are probably informative, the rest are normative. There may be subsections that are also informative, I did not check.
> 
> I wondered about this, actually.  The use cases in the sections are all informative.  The normative parts are just the model bits of each section, but they're not full numbered sections …

One way of doing this is to always add the "informative" mention to, say, the use cases or the examples. The other, probably more effective and easy approach is to add a separate section at the beginning, where we declare once and for all that, eg, use case examples, and examples in general, are informative. This can be added, for example, at the end of section 1.2

Actually, just to make it really separate from the main flow, the use case examples can just be considered as 'examples' and use the same style. That may make the point of being informative all the more clear.

B.t.w., in case you do not know, you simply have to add the class 'informative'  to the relevant section. Respec will add the necessary note.


> 
> • Isn't it correct that, in English, it is considered better to use 'zero' instead of '0', 'one' instead of '1', etc, for small numbers? This pattern is used quite a number of times in the text.
> 
> In prose, yes.  In technical snippets, then it's less important and personally I find the numerals easier to scan than a bunch of text.  Easy to change, however.
> 
> 
> • 3.2.1. is, sort of, the definition of what an external resource is, but the text itself is not really defining it. Even after reading it is unclear whether there is a difference between a Web Resource and and External resource… Actually, is there?
> 
> This is one of the areas where I was trying to avoid talking in linked data terms, and it came out mediocre.
> 
> The thinking is:  There are resources which, as we know, include things like SpecificResource, EmbeddedContent, Choice, and all of the other nodes in the Annotation graph.  But we want to talk about resources that are -not- encapsulated in the graph, just described in it, like blog posts, images, videos, data sets and so forth.
> 
> So ... Web Resource ... but then some of those things could be Web Resources as well.  So I punted and talked about "External Resources" :S
> 
> Suggestions welcome.

"If the annotation graph does not add any further properties to a Web Resource, just referring to its identifier, it is called an 'External Resource'"

How does that sound?


> 
> • In section 3.2.1.1. there seems to be a mixup in the example. The Turtle example seems to be different from the JSON-LD one…
> 
> Yes, I forgot to update for the use case from the vanilla example. *blush*
> My example checking script should check isomorphism between the examples, not just for syntax errors.
> 

:-)

Ivan

> Rob
> 
> --
> Rob Sanderson
> Information Standards Advocate
> Digital Library Systems and Services
> Stanford, CA 94305


----
Ivan Herman, W3C
Digital Publishing Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
ORCID ID: http://orcid.org/0000-0003-0782-2704