RDFa Core editorial comments

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.


Section by Section feedback:

Section 2.

   You might have noticed that a number of the prefixes above have a
   trailing '#'.

s/prefixes/URIs


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 ...

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.

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.

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:

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.

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:

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

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.


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 ...


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/


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'.

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.


and.. that's it. I skipped section 7 in detail (need to implement for 
proper feedback) and the rest looks fine!

Best,

Nathan

Received on Friday, 4 March 2011 15:36:55 UTC