Re: Comments on the API document (version of Monday

On 05/19/2010 02:50 AM, Ivan Herman wrote:
> 1. Basic API level:
>  - RDF interfaces (IRI, Literal, etc). With restrictions: I do not
> want to know about the possibility of redefining the '
> datatype->javascript object conversion; 80% of users won't do that,
> some defaults should prevail

I tried to put this at the top of the document and it just didn't work
very well. To use the simple RDFa DOM API, developers don't need to know
anything about these underlying classes.

>  - Notion of PropertyGroup (note that the current definition does not
> include the origin, and should be)
>  - The Document interface

Done, the order is not the same as yours, but what you have above is
what constitutes the "Basic Concepts" Section now.

> That is it. I believe a vast majority of our users will be happy with
> that
>
> 2. Basic Store level:
>  - a restricted view of store, without mentioning the possibility for
> parser setup and the like; again, most of our users would just want
> an RDFa or maybe a microformat parser.
>  - the datastore stuff, ie, get, add and filter triples
> 3. Personalisation/adaptation
>  - the extension possibilities, that were silent on in the previous
> sections: adding your own parser, changing the datatype->object
> conversions, etc.
> 4. High level queries
>  - essentially, the query interface, allowing the mini-sparql queries

These three items are in an "Advanced Concepts" section, in the
following order:

3.1 Advanced Queries
3.1.1 Querying by Type
3.1.2 Querying by Property Value

3.2 Direct Access to the Data Store

3.3 Direct Access to the Parser Stream

3.4 Overriding the Defaults
3.4.1 Overriding the Data Store
3.4.2 Overriding the Data Parser
3.4.3 Overriding the Data Query

The major difference is that we don't even go into the .select() call in
the basic section anymore. The order has been moved around a bit from
what you proposed, but we basically have this setup now:

Introduction
Basic Concepts
Advanced Concepts
Implementation Sequence Details
Implementation Interface Details

The document is setup so that developers can read the Introduction and
Basic Concepts sections and start using the API without reading anything
else.

They can then come back later, read the Advanced Concepts section and
leave without reading the rest of the document.

Finally, implementers can read the last two sections to understand how
to implement the API and what is required from them at an interface-level.

Does that work for you, Ivan?

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: Bitmunk 3.2.2 - Good Relations and Ditching Apache+PHP
http://blog.digitalbazaar.com/2010/05/06/bitmunk-3-2-2/2/

Received on Wednesday, 26 May 2010 05:54:40 UTC