Re: More thoughts on the RDFa DOM API document

On 04/29/2010 01:24 AM, Knud Hinnerk Möller wrote:
> I know this comes on very short notice, but I hope it's still useful.

Very useful... don't you know, this is a 24 hour, 7 days a week
operation! :P

> - would it be a good idea to briefly explain some core principles of >
the API wherever appropriate?

Done.

http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-dom-api-20100429#the-rdf-interfaces

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

Yes, this would be a good approach for a number of the examples.
Unfortunately, we don't have time to fix all of the examples before
FPWD, so we'll have to do this after FPWD.

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

Good catch. I had thought it was a WebIDL bug, but it turns out I didn't
understand how ReSpec transformed markup into WebIDL.

Fixed.

http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-dom-api-20100429#idl-def-RDFTriple

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

Fixed.

http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-dom-api-20100429#the-rdfa-interfaces


> - 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)?

Yes.

> Will the second one overwrite the mapping defined in the first?

Yes.

>   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

Hey, that's much better! We should do that.

Don't have time to integrate it into the FPWD, but I like this approach
much better. We can make the [NameGetter] a generator function that
produces the proper URI... it would greatly reduce the amount of mapping
code one would have to write.

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

Fixed.

http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-dom-api-20100429#pattern-filters

> Spelling, grammar, etc.
>
> - everywhere:
>   - s/a RDFa .../an RDFa ...

Fixed.

>   - "web" is inconsistently capitalised or not capitalised

Fixed.

Also changed all references from "Web page" to "Web document" since we
want to include XHTML, HTML, SVG, ODF and other web-enabled documents.

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

Fixed.

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

Fixed.

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

Fixed.

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

Fixed.

Thanks for the review Knud... good eyes!

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: PaySwarming Goes Open Source
http://blog.digitalbazaar.com/2010/02/01/bitmunk-payswarming/

Received on Thursday, 29 April 2010 06:40:05 UTC