Re: Review of RDFa Core 1.1 (Dec. 15th 2011)

Manu,

I have integrated most of your comments.  My notes are inline below.  
Manu and Ivan, there are questions for you inline.

As always, the updated draft is at 
http://www.w3.org/2010/02/rdfa/sources/rdfa-core/Overview-src.html

I am going to push a version into datespace now so there can be 
diffmarks from the last published version.  I will send out mail when 
that is ready.

On 1/18/2012 10:49 PM, Manu Sporny wrote:
> This is a review of the RDFa Core 1.1 specification dated December 15th
> 2011. I reviewed the document checking for grammar, spelling and
> technical concerns. It took 5 hours to read the entire document and
> comment on it... I would expect it to take longer for someone reading
> the document for the first time. I don't think that's a good thing, but
> don't think we should remove anything from the document either.
>
> Thanks again to the editors of this document (as well as the rest of the
> documents), and especially to Shane, for sticking with it for so long,
> always being on top of things, and for being an all around great guy...
> the entire WG owes you a beer (or five hundred). I only found one thing
> that could be a non-editorial issue and it's really not that big of an
> issue.
>
> Abstract
> --------
>
> The Abstract is still not succinct. I vaguely remember promising to
> provide an alternate and I have yet to do so. :(
>
>> already available in the markup language (e.g., XHTML)
>
> I think we should just use "HTML" here instead of "XHTML" because it is
> our largest target market. (yes a little bit of me just died suggesting
> that)

Fixed

>
>> please consult the RDFa Primer.
>
> RDFa Primer link is wrong, use this one instead:
>
> http://www.w3.org/TR/rdfa-primer/

Fixed

>
> How to Read this Document
> -------------------------
>
>> then you may find the RDFa Primer [RDFA-PRIMER]
>
> Link is wrong, reference is wrong in bibliography, point to the new RDFa
> Primer. This is the case throughout the document, I'm sure once you
> clean up the bibliography that all references will take care of 
> themselves.
>

Fixed

> 2. Syntax Overview
> ------------------
>
> The note at the end needs to be updated to Jeni's new text.
>

Fixed

> 2.1 The RDFa Attributes
> -----------------------
>
> In hindsight, I think we should've named "CURIEs" - "SIRIs", for "Short
> IRI". I hesitate to say that we should do this now because of everyone
> that knows what a CURIE is at this point... and all the other specs that
> it's gone into. I'm on the fence... I think SIRI would be best
> long-term... maybe.
>

Not gonna happen

> 2.2 Examples
> ------------
>
>> it's possible with RDFa to indicate the type of that item using
>> @typeof:
>
> Hmm, this example is a bit mis-leading as it creates a new bnode and the
> data isn't associated with the page anymore. Maybe we should use the
> book example w/o @typeof and the book example with @typeof to
> demonstrate @typeof. So, the example below this one is moved up and
> @typeof is removed, the next example should also be the book example,
> but with @typeof added.

Fixed

>
> 3.2 Triples
> -----------
>
>> The second part of a triple is the property
>
> Should 'property' be italicized to match the style for 'subject' above?
>

Fixed

>> These are more usually called predicates in RDF.
>
> The sentence is a bit strange... maybe:
>
> "These properties are typically called /predicates/ in RDF."
>

Fixed

> 3.3 IRI references
> ------------------
>
> Should "references" be capitalized?
>

Fixed

>> the predicate
>
> Terminology issue - I think we should be using "property" here and in
> the rest of the document when referring to "predicate"s. I think it's
> easier for people to grasp what a property is without having to learn
> about RDF's strange language.
>

I don't want to make this change now.  I put in a note about it.

>> 'Friend of a Friend' taxonomy.
>
> We should use "vocabulary" instead of "taxonomy" here.
>

Fixed

> 3.9 Markup Fragments and RDFa
> -----------------------------
>
>> (A good example of the latter is the licensing fragment provided by
>> Creative Commons.)
>
> Does this entire sentence need to be parenthetical? Probably not.
>

Fixed

> 3.10 A description of RDFa in RDF terms
> ---------------------------------------
>
> Does the title need to be capitalized?
>

Fixed

>> The aim of RDFa is to allow a single RDF graph to be carried in
>> various types of document markup. An RDF graph comprises nodes linked
>> by relationships.
>
> May want to switch the second sentence the first sentence - we use the
> definition before it is defined.
>

Fixed

>> the predicate is always
>
> Change to "the property is always"?
>

No

> 4.1 RDFa Processor Conformance
> ------------------------------
>
> The start of the section is slightly confusing. It says an RDFa
> processor MUST make a single output graph available, but then describes
> this thing called the processor graph - does an RDFa processor need to
> make that available too? Is that a MAY? I'm pretty sure we intended it
> to be a MAY. So, you might want to reword this to say an RDFa processor
> MUST make at least the output graph available and MAY make the processor
> graph available.

Reworded

>
> 4.3 XML+RDFa Document Conformance
> ---------------------------------
>
> This is non-editorial. I don't think people will do this:
>
>> The document must use the attributes defined in this specification
>> through references to the XHTML namespace
>> (http://www.w3.org/1999/xhtml).
>
> I think they'll use the RDFa attributes in the 'no namespace' context...
> and I think the spec should say that doing that is fine. If people don't
> want to do that, then they can use the XHTML namespace.

Changed as per working group resolution last week.


>
> 5. Attributes and Syntax
> ------------------------
>
>> a traditionally navigable URI for expressing
>
> This should be IRI, no? There are other mentions of URI in this section
> that we'd want to change to IRI.

Fixed.

>
>> property ... used for expressing relationships between a subject and
>>  some literal text
>
> This is no longer true as @property can be used for resources as well.

Fixed.

>
>> An attribute (value ignored)
>
> Move the parenthetical out into another sentence to make it more clear
> about what "value ignored" means.
>

Fixed

>> Causes a list to be created if it does not already exist
>
> Missing a period at the end of the sentence.
>

Fixed

> 7.1 Overview
> ------------
>
> 2nd Note - we may want to mention something about the processor graph 
> here?

Fixed

>
> 7.4 CURIE and IRI Processing
> ----------------------------
>
>> In RDFa these mappings are expressed using the XML namespace syntax:
>
> Not anymore, they're not! :)
>

Fixed

>> The author is free to split the IRI at any point, as long as it
>> begins at the left end.
>
> I don't know what "begins at the left end" means. Do we need that? Why
> isn't "The author is free to split the IRI at any point." good enough?
>

Fixed

> 7.5 Sequence - Step 2
> ---------------------
>
>> In such a case, setting @vocab to the empty value has the effect of
>> clearing the local default vocabulary.
>
> I don't think this is clear enough. If the @vocab is set via the default
> vocabulary, it is cleared? Or if it is set to something, it is cleared?
> My assumption is that if you do vocab='' it is cleared in all cases,
> even if a default vocabulary is specified.

No.  vocab='' resets to the host language default.  It is the only way 
you can be certain you are at a known baseline when embedding a 
fragment, for example.

>
> 7.5 Sequence - Step 2
> ---------------------
>
>> Note that a IRI mapping will simply overwrite
>
> /an/ IRI mapping
>

Fixed

> 7.5 Sequence - Step 5.1
> -----------------------
>
>> but does not contains neither the @content nor @datatype attributes
>
> but does not /contain either/ the @content /or the/ @datatype /attribute/
>

Fixed

>> is set the IRI from the first value
>
> is set /to/ the IRI ?
>

Fixed

> 7.5 Sequence - Step 5.2
> -----------------------
>
>> otherwise:
>
> No need to italicize this.
>

Actually, I changed it so they are ALL italicized.  I like that it 
stresses there is a choice.

>> contains a @about
>
> contains /an/ @about

FIxed.

>
> 7.5 Sequence - Step 11
> ----------------------
>
> This step made my brain hurt... the new algorithm feels twice as
> complicated as the old one due to the RDFa Lite 1.1 changes. I don't
> think there is any way we can simplify it without getting folks upset
> about dropped features.

Nothing to be done.

>
> 7.5 Sequence - Step 12
> ----------------------
>
>> This list is iterated and is and each of the predicates is used
>
> This list is iterated and /DELETE/ each of the predicates is used

Fixed

>
> 7.5 Sequence - Step 12
> ----------------------
>
>> For each IRI in the local list mapping, if the equivalent list does
>> not exist in the evaluation context, indicating that the list was
>> originally defined on the current element, use the list as follows
>
> Awkward sentence is awkward.

Restructured.

>
>> For each pair of bnode and IRI from the list the following triple
>
> For each /bnode-IRI pair/ in the list/,/ the following triple

Restructured, but it is still awkward.

>
> 7.6 Processor Status
> --------------------
>
>> The processor graph is designed as a possible mechanism
>
> The processor graph is designed as the mechanism

Fixed.

>
>> generation of a processor graph,
>
> Missing <tref>

Fixed

>
>> host language
>
> Host Language should be capitalized like it is in the rest of the
> document, no?

Fixed

>
>> rdfa:Info, rdfa:Warning, or rdfa:Error triples may
>
> We should have <code> elements around rdfa:Info / rdfa:Warning / etc.

Fixed

>
> 7.6.2 Processor Graph Terms
> ---------------------------
>
>> Other, implementation-specific subclasses
>
> Unnecessary comma

Fixed

>
> 7.7 Vocabulary Expansion
> ------------------------
>
>> Processors may perform limited RDFS entailment rules to perform
>> vocabulary expansion
>
> rephrase:
>
> Processors MAY perform vocabulary expansion by utilizing limited RDFS
> entailment rules,

Fixed

>
> 8.1 Changing the evaluation context
> -----------------------------------
>
> capitalization issue
>

Fixed

> 8.1.1.1 The current document
> ----------------------------
>
> In section 8, we say "The examples are all written using XHTML+RDFa.",
> but then we use plain 'ol HTML5 in the examples. We may just want to say
> that the examples are written in "HTML+RDFa".

Actually, I ensured they are all XHTML+RDFa.  We don't want a dependency 
on HTML+RDFa.

>
>> In (X)HTML the value of base may change the initial value of current
>>  subject:
>
> This isn't an XHTML document, is it? No xmlns declaration?

Fixed

>
>> <http://www.example.org/jo/blog> foaf:primaryTopic <#bbq> .
>
> This triple is wrong, no? #bbq should be
> http://www.example.org/jo/blog#bbq ?

Fixed

>
> 8.1.1.3 Typing resources with @typeof
> -------------------------------------
>
>> <div  about=
>
> In space, no one can hear you scream.

Fixed

>
> 8.3.1 Object resolution for the @property attribute
> ---------------------------------------------------
>
> The image is too small to make out what it says.

Ivan - suggestions???

>
> 8.3.2.2 Using @href or @src
> ---------------------------
>
> May want to make this "Using @href or @src to set the subject"?

Fixed

>
>
> 8.4 List generation
> -------------------
>
> capitalization issue "List Generation"

Fixed

>
> We use "dc:creator" in this section and use text strings and IRIs for
> the object. The range of dc:creator in dcterms is supposed to be an IRI,
> specifically a http://purl.org/dc/terms/Agent
>
> I suggest we use IRIs for all three authors.

Would love to - no idea how.  Help Manu?

>
>> elements are resources and not literal.
>
> elements are resources and not literal/s/.

Fixed

>
> 10.1 Details of the RDFa Vocabulary Expansion
> ---------------------------------------------
>
>> Applications usually do not require those additional information.
>
> s/those/any of this/
>

Fixed

> 10.1.1 RDFa Vocabulary Entailment
> ---------------------------------
>
>> and is based on the RDF-Based Semantics of OWL[
>
> missing space between OWL and [
>

Fixed

>> and it considers
>
> Sentence starts with "and", rephrase.
>

Fixed

>> In particular, the relevant rules are (using the rule identifications
>> in section 4.3 of [OWL2-PROFILES]):
>
> rephrase:
>
> The relevant rules are, using the rule identifications in section 4.3 of
> [OWL2-PROFILES]:
>

Fixed

> 10.2 Vocabulary Expansion Control of RDFa Processors
> ----------------------------------------------------
>
>> Conforming RDFa processors are NOT required to provide vocabulary
>> expansion.
>
> NOT doesn't need to be capitalized, does it?
>

Nope.  Fixed.

> A. CURIE Datatypes
> ------------------
>
>> A single curie
>
> CURIE should be capitalized here?
>

No - it is a reference to the production rule in the grammar.

>> A white space separated list of CURIEs
>
> No <tref> for CURIE?

Fixed.

>
>> A CURIE or a IRI
>
> External definition link doesn't go anywhere or do anything or say
> anything helpful by hovering.

Yeah - not sure what to do about that.  Looking into it.

>
>> A single safe_curie
>
> underscores are weird in this context, also shouldn't CURIE be 
> capitalized?

No.  Again, reference to production in the grammar.

>
> A.1 XML Schema Definition
> -------------------------
>
>> <xs:simpleType name="CURIEorIRI"> <xs:union memberTypes="xh11d:CURIE
>> xs:anyURI" />
>
> xs:anyURI isn't the exact same lexical space as IRI, is it?

Yes, in this case we are okay

>
> B.2 Processor Graph Reporting
> -----------------------------
>
>> "is the
>
> We start a number of these dc:descriptions with the phrase "is the" when
> we should just be using "The".

Fixed

>
>> error condition; warning;
>
> We should be using complete sentences here as well. "A warning to be
> used...", "An error condition to be used...", etc. Shane, could you
> please make a full pass for grammar on this section?

Fixed

>
>> B.3 Term for vocabulary expansion
>
>> "provides a
>
> Capitalize the first letter in the sentence, add a period to the end of
> the sentence.

Fixed

>
> C. Acknowledgments
> ------------------
>
> This list needs to be updated, probably to this:
>
> Stéphane Corlosquet, Massachusetts General Hospital
> Ivan Herman, W3C
> Gregg Kellogg (Invited Expert)
> Niklas Lindström (Invited Expert)
> Shane McCarron, Applied Testing and Technology, Inc. (Invited Expert)
> Steven Pemberton, Centre for Mathematics and Computer Science (CWI)
> Manu Sporny, Digital Bazaar (Chair, Invited Expert)
>

Fixed, but the list looks short to me.

-- 
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
+1 763 786 8160 x120

Received on Tuesday, 24 January 2012 23:22:40 UTC