Another alternate version of the JSON-LD API spec

I've added a rough draft of the alternate version of the JSON-LD API 
spec I've been working on to the json-ld.org repository on github.

It can be viewed here: 
http://json-ld.org/spec/latest/json-ld-api/alternate2.html

The main purpose of this spec is to provide more explanation for how 
each algorithm works, integrate some of Markus' ideas (in particular, 
inverse context) with the original algorithms, and make appropriate 
changes to reflect an actual implementation of the algorithms (the 
playground's processor uses the algorithms in this version).

This spec version does not include some of the issues that I believe are 
still being debated, including the issue related to relative IRIs and 
terms appearing in @ids.

In addition to changes to the algorithms, the introduction was 
rewritten, some sections were reordered, and some of the examples were 
shortened or changed slightly for simplicity. I think there may still be 
room for improvement with simplifying or cleaning up the examples. Some 
of the now unused terminology was also removed. I think we may want to 
revisit some of the terminology like "active <variable>" -- perhaps not 
renaming these things, but instead considering them simply variable 
names instead of part of a heavy processor state that isn't needed to 
implement the spec or describe the algorithms.

While working on the spec, I noticed a number of inconsistencies that we 
should resolve. I'm sure many of these simply arose out of different 
people working on the spec. These inconsistencies include but are not 
limited to: variable naming (camel-case or multiple words?), the use of 
"an" or "a" preceding keywords, the use of "the" or "a/an" prior to 
variable names in algorithm prose, various capitalization differences 
for headings, etc., the use of very specific data-structure information 
within algorithms (see the new inverse context algorithm for example) 
vs. loose instructions to just "store X in Y"or "retrieve X from Y", 
whether or not the new "Problem" and "General Solution" subsections 
should appear with every algorithm, what is considered a "subalgorithm" 
and what isn't (perhaps there's a better way to help the reader 
understand how these algorithms fit together), the use of "equals 
null/true/false" or "is null/true/false", the use of "if foo is not a 
key" vs. "if foo does not equal a key in".

I also noticed that we do a lot of the same semi-simple operations 
throughout the algorithms, such as normalizing values to arrays 
(creating an array with a single item in it if the item isn't already an 
array). There may be a nicer technique for describing this (or linking 
to it) than either being overly verbose or too vague.

I didn't make changes to the flattening, node map generation, or convert 
to RDF algorithms.

Hopefully this new text can be a basis for moving the spec forward.

-dave

-- 
Dave Longley
CTO
Digital Bazaar, Inc.
http://digitalbazaar.com