Add a section on using HTML documents for contexts (and frames).

[gkellogg]

For w3c/json-ld-api#66.

---

Preview | Diff

[gkellogg]

SpecGen is having some problems, you can find a preview here, sorry, no diffs, but changes are mostly in the "Using an HTML document as a Context" section and a paragraph at the end of "Framed Document Form".

[iherman]

For a first-time reader of that section it is not explicitly said in the text that a frame document is also a bona fide JSON-LD document. This is implicit by the fact that the two sections at the end (the new one and the previous one) refers to the JSON-LD profile; I think it should make it explicit in the text.

Obviously, this is not a comment on the new paragraph, but on the section as a whole. I am fine with the changes proper.

[deniak]

spec-generator is indeed timing out on large documents. I submitted a PR to increase the timeout:
w3c/spec-generator#210
Will deploy after Marcos reviews it.

[deniak]

It's now merged and deployed.

[gkellogg]

@iherman, I put the Processor Levels section within Conformance, which I think is appropriate.

[pchampin]

Isn't it a bit risky to have two normative definitions of the same terms live in two different files? I think we should at least have a comment in both files to remind our future selves (and future editors) that any update in one of the files should be reflected in the other... WDYT?

[gkellogg]

I can update the definitions in the context to reference the definitions in the syntax document easily enough. Doesn't change the way the text reads, but dereferences will go the the syntax versions.

[gkellogg]

See w3c/json-ld-api#84.

[BigBlueHat]

@gkellogg sorry I missed reviewing this before the merge. I'm still concerned that we explain @context string values as de-reference-able URLs (vs. IRIs, URIs, identifiers which may or may not be dereferenced remotely). I realize this sections "overhead" is all about content negotiation and dealing with a non-JSON-LD media type...but if we could rephrase sentences like "This string is interpreted as a URL to an external document from which the context is loaded" to something that states that @context contains an "identifier which may be derefenerced" we may avoid continued criticism that we're 100% network dependent.

[gkellogg]

I was also thinking to beef up the Document Loader section and move most of the logic there, having the document loader return the JSON structure resulting from dereferencing the document. This also provides a means of describing other ways a custom document loader might handle IRIs without actual dereference.