W3C home > Mailing lists > Public > public-webapps@w3.org > July to September 2011

[Bug 9739] Editorial review from timeless on March 24/25, 2010

From: <bugzilla@jessica.w3.org>
Date: Tue, 16 Aug 2011 22:36:50 +0000
To: public-webapps@w3.org
Message-Id: <E1QtSFe-000708-7O@jessica.w3.org>
http://www.w3.org/Bugs/Public/show_bug.cgi?id=9739

Eliot Graff <eliotgra@microsoft.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |RESOLVED
         Resolution|                            |FIXED

--- Comment #14 from Eliot Graff <eliotgra@microsoft.com> 2011-08-16 22:36:43 UTC ---
This final batch addresses the issues in the original post to this bug and
Comment 1 of this bug.

I believe that takes care of all of the issues raised in this bug, and so I am
resolving it as fixed. The final batch are published in changeset 227 for the
IndexedDB Editor's Draft. Thanks.

Responses:

> so, i had trouble following the last part 'the key applicable for some 
> index that references that object store'
> i don't see how that precise thing actually gives me the right 
> individual record it maybe be 'some applicable key for an index that 
> references it in its object store'
> but i'm not sure
Cannot find the reference. May have been changed already due to another reason.

> > A key range is a continuous interval over some data type used for keys.
> can you write 'some key <ref>data type</ref>' ?
Won’t fix. Will make the construction possibly confusing to non-English
readers. 

> > A key range may be left-bounded or right-bounded if there is a value 
> > that is,
> respectively, smaller than or larger than all its elements.
> i think less/greater, but i'm not certain (it's midnight, i'm 
> exhausted, and sick, and have a headache)
> > A key range is said to be bounded if it is both left- and 
> > right-bounded and
> unbounded otherwise.
> 'otherwise unbounded'
> > A valid key range must be either half-bounded or bounded.
> i don't think you've defined 'half-bounded'
Changed as described in comment 12

> > The storage operations are performed on the underlying index or an 
> > object
> store.
> I think you can omit 'The'
Removed “The”

> > A cursor comprises a range of records in either an index or an object store.
> A cursor maintains a position over this series, which moves in a 
> direction that is either monotonically increasing or decreasing order of the record keys.
> you start by talking about a 'range' and then switch to a 'series'
Description has been expanded to cover this transition.

> > If the scope is static, it can cover either all the object stores 
> > and indexes in a
> database or it may include a subset of them.
> … and if it's dynamic?
Language has been removed some time in the past

> > A connection may have at most one transaction at any given time.
> i think you need a word before 'at'
> something like 'open' or 'running' or 'active'
The referenced content is no longer in the spec.

> > Moreover, there may not be any overlap among the scopes of all open
> connections to a given database.
> this is confusing
> if scopes are limited to transactions, then i think it'd be better to 
> say 'among the scope of all (active?) transactions to a given database'
> or perhaps scopes
The discussion of scope and overlap has been expanded and rewritten (in the
past) in section 3.1.7 Transaction.

> > Conforming user agents may terminate transactions that take too long 
> > to
> complete in order to free up storage resources that are locked by a 
> long running transaction.
> the may is interesting, as a useragent, i'd be tempted to terminate 
> transactions that take too much ram :)
This language is no longer in the spec.

> > 3.2.1 Opening the database
> should it be 'a' ?
Why yes; yes, it should. Changed.

> > The steps for opening a database are as follows.
> the first thing that follows isn't a step
> > These steps must be run with an origin, a database name and description.
> drop 'a' from before 'database', or add 'a' before 'description'
Changed to the following:
The steps for opening a database are defined in the following steps. The
algorithm in these steps takes two arguments: an origin, which requested the
database to be opened, and a database, name. The algorithm also optionally
takes a request which represents a request used when opening the database is
done by using an asynchronous API.


> > All the steps must be run atomically:
> drop 'the'?
> note that i'm not sure what 'All' means here does it mean that each 
> step is atomic, or the effect of the entire set of steps is atomic?
> > If there is already a database with the given name from the origin 
> > origin
> origin origin :(
Language has been previously removed from the spec.

> > 3.2.2 Object Store Storage steps
> 3.2.1 didn't include 'steps', why does 3.2.2?
Previously changed

> > These steps must be run with four parameters: the object store, a 
> > value, an
> optional key, and an optional no-overwrite flag.
> 'must'/'four' seems odd given that two are optional
Changed in the past: No more “must”

> > If store uses out-of-line keys but no key generator, then a key must 
> > be
> passed to these steps. If not, terminate these steps and set error 
> code DATA_ERR.
> i think it'd rather this be one if condition If 
> (store.uses(out_of_line_keys) &
> !store.has_(key_generator) & !key) then terminate(…)
This text has been removed sometime in the past.

> > If store uses in-line keys, then let key be the property of object 
> > at store's key
> path.
> what happens if 'key' was an argument?
This text has been removed sometime in the past.

> > Using store's key generator, produce the next key and store it as key.
> i'd avoid using the phrase 'store it'
This text has been removed sometime in the past

> > If store uses in-line keys, then store key as the property value for 
> > object at
> store's key path.
> using 'store' 3 times in a sentence with sometimes different meanings 
> is really confusing :(
Agreed. Thankfully, this text has been removed sometime in the past.

> > If any indexes are auto-populated for store, then store a record in 
> > that
> index according to index maintenance conditions.
> 'any indexes' is plural
This text has been removed sometime in the past.

> Comment 1:
> so i'd expect 'for each' instead of 'in that'
> > Auto populated index record will also be respectively inserted or 
> > updated
> depending on what storing results in.
> records
> note that ending a sentence with a preposition (in) is discouraged.
> note that you generally use articles a/an for each element in your 
> lists, so while i originally suggested dropping an 'a', you should 
> probably just add the missing one (alternatively you'd need to remove 
> all of the other articles from additional list items [3.2.3]
Cannot locate text. This has been changed or removed previously.

> > Storing would mean inserting if no record exists for that key or 
> > updating an
> existing record, otherwise.
> you haven't updated any automatic indexes …
> > Return the a new structured clone of the value in the record with 
> > key key in
> store.
> drop 'the'
Cannot locate text. This has been changed or removed previously.

> [3.2.7]
> > If any indexes are auto-populated for store, then remove the record 
> > in that
> index according to index maintenance conditions.
> see previous comment about 'in that'
Cannot locate text. This has been changed or removed previously.


> [3.2.8]
> > Remove the records from index with key key.
> oh, this is an index, ok :)
> > If these steps are called with an empty array of database objects
> this isn't a sentence
Cannot locate text. This has been changed or removed previously.


> > Do not acquire locks on any database objects now.
> [context] this looks like a sentence, but is confusing
Cannot locate text. This has been changed or removed previously.


> > Locks are obtained as the application attempts to access those objects.
> 'those objects' is odd


> > Programmers must use caution to acquire and release database objects 
> > in
> the same global order to avoid deadlocks.
> deadlock (singular)
> or rather, perhaps, uncountable ?
> (or state, whatever)

> > If a timeout duration is passed to these steps and is exceeded when
> acquiring locks, then set code to TIMEOUT_ERR and jump to the last step.
> 'when acquiring' isn't really right, perhaps 'while trying to acquire'
> > Open a new transaction to the database, and create a IDBTransaction 
> > object
> that represents that transaction.
> an IDBTransaction object representing that transaction
Changed “a” to “an” in IDBDatabase.transaction(). Sync version, too. Other than
that, cannot find this text.

> > A database connection can be used to manipulate the objects of that
> database.
> i don't really like 'of that'
Stet.

> > That is also the only means of obtaining a transaction for that database.
> change 'That' to 'It' or 'This' ?
> i don't like 'of obtaining' it's passive voice, could you rewrite the sentence?
> :)
> (sorry, i know i'm asking a lot)
Changed to:
A database object can be used to manipulate the objects of that database. It is
also the only way to obtain a transaction for that database.

> [removeObjectStore]
> > This method is used to destroy an object store with the given name 
> > as well
> as all indexes that are referencing that object store.
> drop 'are'
> and change 'referencing' to 'reference'
deleteObjectStore() now says:
This method destroys the object store with the given name in the connected
database as well as all indexes that reference that object store.

> fwiw, it's 1:30am and my eyes are glazing over, so i'm jumping through 
> things faster
> > Using the synchronous API, an application can process all the 
> > records in the
> cursor's range. No two values provided by the user agent to callbacks 
> processing data in this cursor can be identical.
> i wouldn't write 'can'.
> > Example
> > By default, a cursor walks over objects starting at the first record 
> > and ending
> at the last record including all the duplicates encountered along the 
> way. If the cursor callback returns true, then the iteration is stopped.
> the duplicates bit seems to contradict the previous section, which 
> confuses me :( It is also possible to create a bounded cursor, i.e., 
> with application- specified starting and ending points, the cursor 
> should be created with both the required keys.
Previously implemented in the spec. See section 3.3.5 Cursor

-- 
Configure bugmail: http://www.w3.org/Bugs/Public/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.
Received on Tuesday, 16 August 2011 22:36:52 GMT

This archive was generated by hypermail 2.3.1 : Tuesday, 26 March 2013 18:49:47 GMT