Re: RDFa Core editorial comments

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!

-- 
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: shane@aptest.com

Received on Sunday, 6 March 2011 01:50:01 UTC