More thoughts on the RDFa DOM API document

Hi,

I know this comes on very short notice, but I hope it's still useful. I don't have/couldn't find any fundamental issues (it's great work!), so my comments are restricted to details. They follow the structure of the document. Off we go:

- would it be a good idea to briefly explain some core principles of the API wherever appropriate? E.g., in "The RDF Interfaces": "The different RDF interfaces give access to both the extracted value of the RDF resource, as well as to the DOM node that this value was extracted from. This will allow agents to extract and use RDF triples from a host language, but also to subsequently manipulate the DOM based on the extracted triples. E.g., an agent could highlight all strings that are marked up as names in a Web page."

- it might be a bit confusing that examples such as 2.2.1.2 first construct a new RDF resource and then access its attributes. Since the main focus of the API is extracting triples, would it not be beneficial to start with an RDFa snippet and then construct the RDF resource from that? E.g.:

--------
Example

<div xmlns:dcterms="http://purl.org/dc/terms/" 
   about="#book" 
   property="dcterms:title">Harry Potter and the Half-Blood Prince</div>

Based on this RDFa snippet, a PlainLiteral object is generated and accessed as follows:

>> var literal = new PlainLiteral('Harry Potter and the Half-Blood Prince', 'en');
...
---------

- this is probably completely irrelevant, but why is the type of the index parameter of RDFTriple.get a long? Legal values are 0..2, so wouldn't a byte suffice? Same argument for RDFTriple's constants.

- in Sect. 3, the RDFTripleIterator is described as iterating _all_ triples in a document. However, looking at the definitions in Sect. 3.2, it actually iterates through a subset of all triples.

- I'm also a bit confused about the mapping API in 4.2. Two things:
  1.) are the following two just two different ways of doing the same thing (creating a mapping)? Will the second one overwrite the mapping defined in the first?
     >> rdfa.setMapping("foaf", "name", "http://xmlns.com/foaf/0.1/name");
     >> rdfa.foaf = {"knows" : new IRI("http://xmlns.com/foaf/0.1/knows")};
  2.) Would it not be nice if one could simply map a prefix, and the other mappings would just follow? E.g.
     >> rdfa.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
     >> print(rdfa.foaf.name);
     http://xmlns.com/foaf/0.1/name
     >> print(rdfa.foaf.Person);
     http://xmlns.com/foaf/0.1/Person

- Sect. 4.4: "The primary goal of the RDFa DOM API is to help web developers filter the set of RDF triples ..." - that's probably not the primary goal, but an important goal?

Spelling, grammar, etc.

- everywhere:
  - s/a RDFa .../an RDFa ...
  - "web" is inconsistently capitalised or not capitalised

- Abstract:
  - s/machine readable/machine-readable

- How to Read this Document
  - s/the inner-workings/the inner workings

- 2.4 RDF Triples
  - s/represents RDF Triple as/represents RDF triples as

- 3.1 RDF Triple List
  - s/sequence of of/sequence of

Cheers,
Knud

-------------------------------------------------
Knud Möller, PhD
+353 - 91 - 495086
Smile Group: http://smile.deri.ie
Digital Enterprise Research Institute
  National University of Ireland, Galway
Institiúid Taighde na Fiontraíochta Digití
  Ollscoil na hÉireann, Gaillimh

Received on Thursday, 29 April 2010 05:25:22 UTC