- From: Shane McCarron <shane@aptest.com>
- Date: Tue, 24 Jan 2012 17:22:14 -0600
- To: public-rdfa-wg@w3.org
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