W3C home > Mailing lists > Public > public-rdfa-wg@w3.org > March 2011

Re: RDFa Core editorial comments

From: Nathan <nathan@webr3.org>
Date: Sun, 06 Mar 2011 14:25:31 +0000
Message-ID: <4D73995B.2040801@webr3.org>
To: Shane McCarron <shane@aptest.com>
CC: RDFA Working Group <public-rdfa-wg@w3.org>
Thanks Shane :)

Shane McCarron wrote:
> Thanks for your detailed review.  I have made edit based upon your 
> comments.  My responses inline.
> 
> On 3/4/2011 9:34 AM, Nathan wrote:
>> Hi Shane, All,
>>
>> Just a few editorial comments after reviewing the latest draft, quoted 
>> text indented.
>>
>> general comment:
>>  - The spec uses URL 26 times, IRI 5 times, and URI 206 times. I'd 
>> suggest URL is swapped to URI, and the 3 of the mentions of IRI (under 
>> 6.1) are also swapped to URI.
> 
> I have made this change.  I think that the distinction between URIs and 
> IRIs is lost on the casual reader, and our normative reference to RFC 
> 3987 makes it completely clear to the non-casual reader.
> 
>>
>>
>> Section by Section feedback:
>>
>> Section 2.
>>
>>   You might have noticed that a number of the prefixes above have a
>>   trailing '#'.
>>
>> s/prefixes/URIs
>>
> 
> Fixed
> 
>>
>> Section 2.1
>>
>>   ... in (X)HTML, @rel already defines the relationship between one
>>   document and another. However, in (X)HTML there is no clear way to
>>   add new values; RDFa sets out to explicitly solve this problem ...
>>
>> the meaning of rel has changed significantly in the next (X)HTML, and 
>> this section deals with syntax changes, so it may be wise to skirt 
>> this subject and change the text to:
>>
>>   ... in (X)HTML, there is no clear way to add new @rel values; RDFa
>>   sets out to explicitly solve this problem ...
>>
> 
> Changed
> 
>> Section 2.2
>>
>>   In HTML, authors can include metadata and relationships concerning the
>>   current document by using the link and meta elements.
>>
>> the order they are described and mentioned is inverted such that it 
>> may be confusing, consider changing to:
>>
>>   In HTML, authors can include metadata and relationships concerning the
>>   current document by using the meta and link elements.
>> /or/
>>   In HTML, authors can describe relationships and insert metadata
>>   concerning the current document by using the link and meta elements.
> 
> Changed.
> 
>>
>> next..
>>
>>   RDFa supports the use of @rel and @rev on any element. This is even
>>   more useful when with the addition of support for different
>>   vocabularies:
>>
>> "when with" doesn't make much sense, needs a reword.
> 
> LOL.  fixed.
> 
>>
>> next..
>>
>>   If some displayed text is different to the actual 'value' it
>>   represents, more precise values can be added, which can optionally
>>   include datatypes:
>>
>> this changes between singular and plural, and doesn't introduce the 
>> @datatype property like the others, consider changing to:
>>
>>   If some displayed text is different to the actual 'value' it
>>   represents, a more precise value can be added, which can optionally
>>   include a @datatype:
> 
> Changed
> 
>>
>> next...
>>
>>   In many cases a block of markup will contain a number of properties
>>   that relate to the same item; it's possible with RDFa to indicate the
>>   type of that item:
>>
>> this also doesn't introduce @typeof, needs a post fixed "using the 
>> @typeof attribute:" or similar.
>> x
> 
> Fixed.
> 
>> next...
>>
>>   A simple way of defining a portion of a document to use FOAF terms is
>>   to use @vocab to define a default vocabulary URI:
>>
>> this is worded to sound like you can only use FOAF terms with @vocab - 
>> needs reworded to something like:
>>
>>   A simple way of defining a portion of a document as using terms from
>>   a specific vocabulary, is to use @vocab to define a default vocabulary
>>   URI. For example to use FOAF terms:
> 
> Fixed.
> 
>>
>> immediately following this example the spec says "the following 
>> triples will be generated:", which comes from no where and is the 
>> first usage of turtle in the spec, this text needs expanded to 
>> something like:
>>
>>   The example above will produce the following triples, expressed here
>>   in [Turtle] syntax:
>>
>> where [Turtle] probably links to 3.6
> 
> Fixed.
> 
>>
>> next...
>>
>> The example profile has had the @typeof's stripped again, Jeni's 
>> feedback was to change to typeof="rdfa:PrefixMapping", which was done, 
>> but now stripped - can we get this put back please :) - likewise th 
>> example which follows which introduce terms in profiles has typeof="" 
>> again.
> 
> Ivan fixed this back.
> 
>>
>>
>> Section 3.
>>
>>   However, what RDFa represents is RDF. In order to author RDFa you do
>>   not need to understand RDF, although it would certainly help. However,
>>   if you are building a system that consumes the RDF output of a
>>   language that supports RDFa you will almost certainly need to
>>   understand RDF.
>>
>> pleaseeeee can we above that word represents, and also double use of 
>> However as an opener, consider:
>>
>>   RDFa is short for RDF in Attributes. In order to author RDFa you do
>>   not ...
>>
> 
> Sure
> 
>>
>> Section 4.2
>>
>> s/default graphto/default graph to/
>>
>> s/The processor graph term/The term processor graph/
>>
>> s/that may be used by the RDFa Processor/that may be generated by the 
>> RDFa Processor/
> 
> Fixed.
> 
>>
>>
>> Section 6.
>>
>>   This specification does not define a 'no prefix' mapping.
>>
>> Can we have some text or a note in there to let people know that if 
>> they, or an RDFa host language, does define a 'no prefix' mapping, 
>> it'll effectively break their RDFa? (curies with no prefix mapping in 
>> about issue). Likewise for the text under "In RDFa these values are 
>> defined as follows:", remembering that the "no prefix" mapping != the 
>> default vocabulary mapping. We can't have implementers confusing the 
>> two, or even using 'no prefix'.
> 
> OK.
> 
>>
>> Section 6.1
>>
>> Three mentions of "IRIs", should probably be "URIs", section 6 already 
>> clarifies they are also valid IRIs, thus the text can be confusing 
>> "compact URIs expends to IRIs" etc.
> 
> Done.
> 
>>
>>
>> and.. that's it. I skipped section 7 in detail (need to implement for 
>> proper feedback) and the rest looks fine!
>>
>> Best,
>>
>> Nathan
> 
> Thanks again!
> 
Received on Sunday, 6 March 2011 14:27:11 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 17:05:24 UTC