[Dev] Feedback on repository documents requested

[Donn Denman]

Ted,

I have a bunch of nit-picky comments, but overall this looks good.  It  
covers all the important points I was looking for, except that I'd like  
to see a section on trouble-shooting.  Also, if there's a way to do  
interactive experimentation that would be really great. Along those  
lines, I've been thinking about adding a field to the Detail View of an  
Item Collection for the query.  This should be easy for me to do, and  
then you can just edit the query in place, hit enter, and see the  
results in Chandler.  Now that 0.4 is branched, we can consider it -  
let me know if you think this is a good way to go.  Maybe we enable it  
from the "test" menu.

- Donn Denman

DETAILS
-------------

Here's the information I expected to find in your document, and what I  
found:
--------------
* Can queries be run over a subset of the repository?  YES, using an  
itemCollection for the input set.
* How do you iterate through queries?  What form are the results in?    
The query object is itself an iterator.  Saying this explicitly would  
be nice - it looks like it could be a sequence and support slicing...
* What's the grammar for queries?  You covered this, though not  
explicitly.  A BNF grammar might be nice for us techies.
* What are some common errors in writing a query?  You should add a  
section on how/where to find syntax errors.
* Is there an interactive way to experiment with queries?  Not yet...

Comments
--------------
* Typo in the second sentence: missing the word "of" before "care"
* Suggest adding a sentence to the second paragraph: This feature  
allows queries to automatically keep their result sets up-to-date.
* In the first paragraph of the Python API section, give an example of  
usage in parcel.xml.  In an ItemCollection, the query  is held in the  
"_rule" attribute:
     <_rule value="for i in  
'//parcels/osaf/contentmodel/calendar/CalendarEventMixin' where True"/>
* The next paragraph should start: "To use a query from Python, your  
code..."
* when you say "The query string may be "", the following sentence is  
ambiguous.  Do you mean the above example, or the empty string query?
* looks like you forgot to use boldface for the keywords of the query  
under the section "for queries"
* When using a lucene query, is the query run over all items with an  
attribute in the specified list whose type is lucene-type?  Seems like  
this is a potential long-term problem, because you have to run the  
lucene query over the entire repository.  Maybe this is the way lucene  
works, and that's why you did it this way.  If not, it seems like it  
would be good to be able to specify an ItemCollection for the search  
set, and still run a lucene-query, which you can't do now.
* Missing a section in the query syntax on literals.  Seems like you  
can use numbers, string literals, booleans...
* There are several little typos...I stopped making note of them.
* It would be good if you typographically highlighted the special use  
of the word "for", otherwise it's hard to read sentences like "...  
composed of three for queries that show..."
* You could mention that "union" combines the results from all queries  
specified, and intersection returns only items that are in both result  
sets.
* With difference, it's all the items in 1 that are not in 2, right?   
If there are items in 2 that are not in 1, they get ignored?  You could  
update the example to use 'block' and 'blocker' to illustrate the  
point.
* Query notification is a bit confusing.  The item is confusing,  
because I think it might correspond to the item added/removed from the  
query.  You should point out that the item is usually a block, or at  
least an item whose kind is associated with a class that has the  
specified method.
* Is there a way to get the item(s) that entered or exited the query in  
the notification?  I guess you could pass an "items" iterable to give  
access to that.  Not sure how useful it would be, but it seems like  
entered/exited isn't very useful if you can't find out which items  
entered/exited.  Also, what happens if some items enter and some exit?   
You get two notifications?
* You should quote "exited" at the end of the Query Notification  
section.

Comments on Query Functionality inspired by the Doc Review
-------------------
* It would be nice if the "where" clause was optional, so the user  
doesn't need to say "where True"
* It would also be nice if you could make "contains" a binary operator  
instead of a function. E.g.  "...where i.itsName contains 'arc'"
* Have you thought about allowing arbitrary python functions to execute  
in the query?  I know this is a security hole, and probably difficult  
to make robust.

On Oct 12, 2004, at 5:39 PM, Ted Leung wrote:

> Hi all,
>
> I checked in a pair of documents for repository features in 0.4.  I'd  
> appreciate any comments, corrections, or questions regarding their  
> contents.
>
> <http://cvs.osafoundation.org/viewcvs.cgi/*checkout*/chandler/distrib/ 
> docs/repository-intro.html?rev=HEAD&content-type=text/html>
>
> <http://cvs.osafoundation.org/viewcvs.cgi/*checkout*/chandler/distrib/ 
> docs/chandler-query-system.html?rev=HEAD&content-type=text/html>
>
> Thanks,
>
> Ted
>
> _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
>
> Open Source Applications Foundation "Dev" mailing list
> http://lists.osafoundation.org/mailman/listinfo/dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/enriched
Size: 5343 bytes
Desc: not available
Url : http://lists.osafoundation.org/pipermail/dev/attachments/20041013/8ee1ba5d/attachment.bin