Merge some editorial changes from alternate2 into the API spec
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Tue, 05 Feb 2013 20:27:06 +0100
changeset 1190 0dc44fb2973f
parent 1189 85371a405e41
child 1191 83f71b5d3716
Merge some editorial changes from alternate2 into the API spec
spec/latest/json-ld-api/index.html
--- a/spec/latest/json-ld-api/index.html	Tue Feb 05 20:06:00 2013 +0100
+++ b/spec/latest/json-ld-api/index.html	Tue Feb 05 20:27:06 2013 +0100
@@ -99,15 +99,15 @@
 JSON [[!RFC4627]] has proven to be a highly useful object serialization and
 messaging format. JSON-LD [[!JSON-LD]] harmonizes the representation of
 Linked Data in JSON by outlining a common JSON representation format for
-expressing directed graphs; mixing both Linked Data and non-Linked Data in
+expressing directed graphs, mixing both Linked Data and non-Linked Data in
 a single document. This document outlines an Application Programming
 Interface and a set of algorithms for programmatically transforming
-JSON-LD documents in order to make them easier to work with in programming
-environments like JavaScript, Python, and Ruby.
+JSON-LD documents to make them easier to work with in programming
+environments like those that use JavaScript, Python, and Ruby.
 </p>
 </section>
 
-<section id='sotd'>
+<section id="sotd">
 <p>This document has been under development for over 18 months in the
 JSON for Linking Data Community Group. The document has recently been
 transferred to the RDF Working Group for review, improvement, and publication
@@ -148,11 +148,11 @@
     <a href="http://lists.w3.org/Archives/Public/public-linked-json/">[email protected]</a></li>
 
   <li><a href="http://json-ld.org/minutes/">Public JSON-LD Community Group teleconferences</a>
-  are held on Tuesdays at 1500UTC every week. Participation is open to the
-  public.</li>
+    are held on Tuesdays at 1500UTC every week. Participation is open to the
+    public.</li>
 
   <li>RDF Working Group teleconferences are held on Wednesdays at 1500UTC
-  every week. Participation is limited to RDF Working Group members.</li>
+    every week. Participation is limited to RDF Working Group members.</li>
 
   <li>Specification bugs and issues should be reported in the
     <a href="https://github.com/json-ld/json-ld.org/issues">issue tracker</a>
@@ -179,9 +179,9 @@
 
 <ul>
   <li>Web authors and developers that want a very detailed view of how
-  a JSON-LD processor and the API operates.</li>
+    a JSON-LD processor and the API operates.</li>
   <li>Software developers that want to implement processors and APIs for
-  JSON-LD.</li>
+    JSON-LD documents.</li>
 </ul>
 
 <p>
@@ -299,7 +299,7 @@
     <tref title="IRI">IRIs</tref> to <tref title="term">terms</tref> or
     <tref title="compact IRI">compact IRIs</tref> and <tref title="JSON-LD value">JSON-LD values</tref>
     expressed in <tref>expanded form</tref> to simple values such as
-    <tref title="string">strings</tref> and <tref title="number">numbers</tref>.</p>
+    <tref title="string">strings</tref> or <tref title="number">numbers</tref>.</p>
 
   <p>For example, assume the following expanded JSON-LD input document:</p>
 
@@ -489,17 +489,17 @@
   -->
   </pre>
 
-  <p>Please note that the flattened and compacted result will always explicitly
-    designate the default by the <code>@graph</code> member in the top-level
-    <tref>JSON object</tref>. <a href="#compaction">Compaction</a> optimizes that
-    member away if its value contains just one item.</p>
+  <p>Please note that the flattened and compacted result will explicitly
+    designate the default graph by the <code>@graph</code> member in the top-level
+    <tref>JSON object</tref>, except if its value contains just one item.</p>
+
 </section>
 
 <section class="informative">
   <h2>RDF Conversion</h2>
   <p>JSON-LD can be used to serialize data expressed in RDF as described in
-    [[RDF-CONCEPTS]]. This ensures that data can be round-tripped from and to
-    any RDF syntax without any loss in the fidelity of the data.</p>
+    [[RDF-CONCEPTS]]. This ensures that data can be round-tripped to and from
+    any RDF syntax without any loss in fidelity.</p>
 
   <p>For example, assume the following RDF input serialized in Turtle [[TURTLE-TR]]:</p>
 
@@ -543,7 +543,7 @@
 </section>
 
 <section>
-  <h2>Conformance</h2>
+  <h1>Conformance</h1>
 
   <p>All examples and notes as well as sections marked as non-normative in this
     specification are non-normative. Everything else in this specification is
@@ -561,10 +561,10 @@
     JSON-LD documents according the algorithms defined in this specification.</p>
 
   <p>A conforming <tdef>JSON-LD Processor</tdef> is a conforming <tref>JSON-LD Implementation</tref>
-    that exposes the application programming interface (API) defined in this specification.</p>
+    that exposes the Application Programming Interface (API) defined in this specification.</p>
 
   <p>The algorithms in this specification are generally written with more concern for clarity than
-    over efficiency. Thus, JSON-LD Implementations and Processors may implement the algorithms
+    efficiency. Thus, JSON-LD Implementations and Processors may implement the algorithms
     given in this specification in any way desired, so long as the end result is indistinguishable
     from the result that would be obtained by the specification's algorithms.</p>
 
@@ -583,7 +583,7 @@
 </section>
 
 <section>
-  <h3>General Terminology</h3>
+  <h1>General Terminology</h1>
 
   <p>This document uses the following terms as defined in JSON [[!RFC4627]]. Refer
     to the <em>JSON Grammar</em> section in [[!RFC4627]] for formal definitions.</p>
@@ -686,6 +686,7 @@
       <tref title="blank node">blank nodes</tref>, and
       <tref title="JSON-LD value">JSON-LD values</tref>.</dd>
   </dl>
+
 </section>
 
 <section>
@@ -698,6 +699,7 @@
 
 <section>
   <h2>Algorithm Terms</h2>
+
   <dl>
     <dt><tdef>active graph</tdef></dt>
     <dd>The name of the currently active graph that the processor should use when
@@ -713,9 +715,8 @@
     <dd>The currently active object that the processor should use when
       processing.</dd>
     <dt><tdef>active context</tdef></dt>
-    <dd>A context that is used to resolve <tref>term</tref>s while the processing
-      algorithm is running. The <tref>active context</tref> is the context
-      contained within the <tref>processor state</tref>.</dd>
+    <dd>A context that is used to resolve <tref title="term">terms</tref> while
+      the processing algorithm is running.</dd>
     <dt><tdef>local context</tdef></dt>
     <dd>A context that is specified within a <tref>JSON object</tref>,
       specified via the <code>@context</code> <tref>keyword</tref>.</dd>
@@ -749,14 +750,14 @@
       </ul>
     </dd>
     <dt><tdef>list object</tdef></dt>
-    <dd>A <tref>list object</tref> is a <tref>JSON object</tref> that has a <code>@list</code>
+    <dd>A <tref>list object</tref> is a <tref>JSON object</tref> that has an <code>@list</code>
       member.</dd>
     <dt><tdef>scalar</tdef></dt>
     <dd>A scalar is either a JSON <tref>string</tref>, <tref>number</tref>, <tref>true</tref>,
       or <tref>false</tref>.</dd>
     <dt><tdef>quad</tdef></dt>
-    <dd>An <em>RDF triple</em> as specified by [[RDF-CONCEPTS]] augmented with a a fourth component,
-      a <tref>graph name</tref>.</dd>
+    <dd>An <em>RDF triple</em> as specified by [[RDF-CONCEPTS]] augmented with
+      a fourth component, a <tref>graph name</tref>.</dd>
   </dl>
 </section>
 
@@ -1856,7 +1857,7 @@
         <li>If <em>defaultGraph</em> does not have a <em>graphName</em> member, create
           one and initialize its value to a <tref>JSON object</tref> consisting of an
           <code>@id</code> member whose value is set to <em>graphName</em>.</li>
-        <li>Add a <code>@graph</code> member set to an empty <tref>array</tref>
+        <li>Add an <code>@graph</code> member set to an empty <tref>array</tref>
           (referred to as <em>nodes</em>) to the <tref>JSON object</tref> which is the
           value of the <em>graphName</em> member of <em>nodeMap</em>.</li>
         <li>For each <em>id</em>-<em>node</em> pair in <em>graph</em> ordered by <em>id</em>,
@@ -1901,7 +1902,7 @@
     <li>Otherwise <em>element</em> is a <tref>JSON object</tref>. Let <em>activeGraph</em> be the
       <tref>JSON object</tref> which is the value of the <tref>active graph</tref> member of
       <em>nodeMap</em>.</li>
-    <li>If it has a <code>@type</code> member, perform for each <em>item</em> the following
+    <li>If it has an <code>@type</code> member, perform for each <em>item</em> the following
       steps:
       <ol class="algorithm">
         <li>If <em>item</em> is a <tref>blank node identifier</tref>, replace it with a
@@ -1983,7 +1984,7 @@
   <section>
     <h2>RDF Conversion Algorithms</h2>
 
-    <p>This specification describes algorithms to transform JSON-LD documents to an array of
+    <p>This section describes an algorithms to transform JSON-LD documents to an array of
       RDF <tref title="quad">quads</tref> and vice-versa. Note that many uses of JSON-LD
       may not require generation of RDF.</p>
 
@@ -2002,7 +2003,7 @@
       <p>
         A conforming JSON-LD processor implementing RDF conversion MUST implement a
         processing algorithm that results in the same set of RDF <tref title="quad">quads</tref> that the following
-        algorithm generates:
+        algorithm generates.
       </p>
 
       <p>The algorithm takes four input variables: a <em>element</em> to be converted, an
@@ -2158,7 +2159,7 @@
         JSON-LD document.</p>
       <p>When expanding <tref title="typed value">typed values</tref> having a datatype of <code>xsd:string</code>,
         the <code>@type</code> MUST NOT be set to <code>xsd:string</code> and the resulting value
-        MUST have only a <code>@value</code> property.</p>
+        MUST have only an <code>@value</code> property.</p>
 
       <p>The conversion algorithm takes a single parameter <em>input</em> in the form of an
         array of <tref>Quad</tref> representations.</p>
@@ -2614,7 +2615,7 @@
           <tref>IRI mapping</tref> of another <tref>term</tref> or
           <tref>property generator</tref>.</dd>
         <dt>invalid type value</dt>
-        <dd>An invalid value for a <code>@type</code> member has been detected,
+        <dd>An invalid value for an <code>@type</code> member has been detected,
           i.e., the value was neither a <tref>string</tref> nor an <tref>array</tref>
           of <tref title="string">strings</tref>.</dd>
         <dt>invalid value object</dt>