I'm a lousy computer, and I think stuff is much easier to understand and relate to when it's all cute and cuddly.

Could we exchange some of the abstract variables with something real? I'm thinking about changing this text in 3.1.6 Index [1]:

# The values in the index's records are always values of keys in the
# index's referenced object store. The keys are derived from the
# referenced object store's values using a key path. If a given record
# with key X in the object store referenced by the index has the value A,
# and evaluating the index's key path on A yields the result Y, then the
# index will contain a record with key Y and value X. 
# 
# Records in an index are said to have a referenced value. This is the
# value of the record in the index's referenced object store which has a
# key equal to the index's record's value. So in the example above, the
# record in the index whose key is Y and value is X has a referenced value
# of A.


To maybe something like:

# The values in the index's records are always values of keys in the
# index's referenced object store. The keys are derived from the
# referenced object store's values using a key path. If a given record
# with key 1337 in the object store referenced by the index has
# the value {name:'Ceiling cat', type:'cat'}, and evaluating the index's
# key path on that value yields the result 'cat', then the index will
# contain a record with key 'cat' and value 1337.
# 
# Records in an index are said to have a referenced value. This is the
# value of the record in the index's referenced object store which has a
# key equal to the index's record's value. So in the example above, the
# record in the index whose key is 'cat' and value is 1337 has a
# referenced value of {name:'Garfield', type:'cat'}.


That might be too concrete and tied to javascript and whatnot (although I personally don't mind), so if we can't do that, even using different varible names will help:

# The values in the index's records are always values of keys in the
# index's referenced object store. The keys are derived from the
# referenced object store's values using a key path. If a given record
# with key ID in the object store referenced by the index has the
# value CarInfo, and evaluating the index's key path on CarInfo yields the
# result Toyota, then the index will contain a record with key Toyota
# and value ID. 
# 
# Records in an index are said to have a referenced value. This is the
# value of the record in the index's referenced object store which has a
# key equal to the index's record's value. So in the example above, the
# record in the index whose key is Toyota and value is ID has a referenced value
# of CarInfo.


BTW, this is super duper minor, I won't shed a tear if it's WONTFIX'ed.


[1] http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#index-concept