Make naming of algorithms more consistent (2/2)
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Wed, 27 Feb 2013 19:41:34 +0100
changeset 1345 bef96121bcfe
parent 1344 a14d1bb76c6a
child 1346 4bb161df2274
Make naming of algorithms more consistent (2/2)

This is probably controversial, thus the separate commit so that we can easily revert it. I think almost all algorithms are "subalgorithms". Just marking a few as such doesn't improve clarity. The approach I'm taking here is to add the word "Algorithm" to the main algorithms and drop it (as well as "Subalgorithm") from all others.

//cc @dlongley @gkellogg

This addresses #218.
spec/latest/json-ld-api/index.html
--- a/spec/latest/json-ld-api/index.html	Wed Feb 27 19:29:56 2013 +0100
+++ b/spec/latest/json-ld-api/index.html	Wed Feb 27 19:41:34 2013 +0100
@@ -941,7 +941,7 @@
               or currently being defined during recursion.</li>
             <li>For each <em>key</em>-<em>value</em> pair in <em>context</em> where
               <em>key</em> is not <code>@vocab</code> or <code>@language</code>, invoke the
-              <a href="#create-term-definition-subalgorithm">Create Term Definition subalgorithm</a>,
+              <a href="#create-term-definition">Create Term Definition algorithm</a>,
               passing <em>result</em> for <tref>active context</tref>,
               <em>context</em> for <tref>local context</tref>, <em>key</em>,
               and <em>defined</em>.</li>
@@ -953,7 +953,7 @@
   </section> <!-- end of Context Processing -->
 
   <section>
-    <h2>Create Term Definition Subalgorithm</h2>
+    <h2>Create Term Definition</h2>
 
     <p>This algorithm is called from the
       <a href="#context-processing-algorithm">Context Processing algorithm</a>
@@ -1157,7 +1157,7 @@
           <tref>true</tref>.</li>
       </ol>
     </section>
-  </section> <!-- end of Term Creation subalgorithm -->
+  </section> <!-- end of Term Creation -->
 
   <section>
     <h2>IRI Expansion</h2>
@@ -1174,7 +1174,7 @@
       map from the <a href="#context-processing-algorithm">Context Processing algorithm</a>
       are passed to this algorithm. This allows for <tref>term definition</tref>
       dependencies to be processed via the
-      <a href="#create-term-definition-subalgorithm">Create Term Definition subalgorithm</a>.</p>
+      <a href="#create-term-definition">Create Term Definition algorithm</a>.</p>
 
     <p>After application of this algorithm, values processed by this algorithm are
       said to be in <tdef>expanded IRI form</tdef> (Advanced note: this form
@@ -1214,7 +1214,7 @@
         which <tref title="term">terms</tref> have already been defined or are
         in the process of being defined. We create a
         <tref>term definition</tref> by using the
-        <a href="#create-term-definition-subalgorithm">Create Term Definition subalgorithm</a>.</p>
+        <a href="#create-term-definition">Create Term Definition algorithm</a>.</p>
     </section>
 
     <section>
@@ -1240,7 +1240,7 @@
           a key that equals <em>value</em>, and the value associated with the key
           that equals <em>value</em> in <em>defined</em> is not <tref>true</tref>,
           then invoke the
-          <a href="#create-term-definition-subalgorithm">Create Term Definition subalgorithm</a>,
+          <a href="#create-term-definition">Create Term Definition algorithm</a>,
           passing <tref>active context</tref>, <tref>local context</tref>,
           <em>value</em> as <em>term</em>, and <em>defined</em>. This will ensure that
           a <tref>term definition</tref> is created for <em>value</em> in
@@ -1275,7 +1275,7 @@
               <ol class="algorithm">
                 <li>If <tref>local context</tref> is not <tref>null</tref> and it
                   contains a key that equals <tref>prefix</tref>, then invoke the
-                  <a href="#create-term-definition-subalgorithm">Create Term Definition subalgorithm</a>,
+                  <a href="#create-term-definition">Create Term Definition algorithm</a>,
                   passing <tref>active context</tref>,
                   <tref>local context</tref>, <em>prefix</em> as <em>term</em>,
                   and <em>defined</em>. This will ensure that a
@@ -1617,7 +1617,7 @@
             <li>If <em>expanded property</em> is an <tref>array</tref>:
               <ol class="algorithm">
                 <li>Set <em>expanded value</em> to the result of the
-                  <a href="#label-blank-nodes-subalgorithm">Label Blank Nodes subalgorithm</a>,
+                  <a href="#label-blank-nodes">Label Blank Nodes algorithm</a>,
                   passing <tref>active context</tref> and
                   <em>expanded value</em> as <em>element</em>.</li>
                 <li>For each item <em>iri</em> in <em>expanded property</em>:
@@ -1831,7 +1831,7 @@
   </section> <!-- end of Value Expansion -->
 
   <section>
-    <h2>Label Blank Nodes Subalgorithm</h2>
+    <h2>Label Blank Nodes</h2>
 
     <p>During <tref>expansion</tref>, it is sometimes necessary to ensure
       all <tref title="blank node">blank nodes</tref> have been labeled. This
@@ -1880,7 +1880,7 @@
       </li>
       <li>Return <em>element</em>.</li>
     </ol>
-  </section> <!-- end of Label Blank Nodes Subalgorithm -->
+  </section> <!-- end of Label Blank Nodes -->
 
 </section> <!-- end of Expansion section -->
 
@@ -2116,7 +2116,7 @@
                 <li>If there is a <tref>term definition</tref> for
                   <em>item active property</em> in <tref>active context</tref>
                   that is a <tref>property generator</tref>, then invoke the
-                  <a href="#find-property-generator-duplicates-subalgorithm">Find Property Generator Duplicates algorithm</a>,
+                  <a href="#find-property-generator-duplicates">Find Property Generator Duplicates algorithm</a>,
                   passing <tref>active context</tref>,
                   <em>shallow</em> for <em>element</em>,
                   <em>expanded property</em>, <em>expanded item</em> for
@@ -2264,7 +2264,7 @@
       <tref title="container mapping">container mappings</tref> and the
       <tref>type mapping</tref> or <tref>language mapping</tref> are gathered
       for a particular value associated with an <tref>IRI</tref>. These parameters
-      are then fed to the <a href="#term-selection-subalgorithm">Term Selection subalgorithm</a>,
+      are then fed to the <a href="#term-selection">Term Selection algorithm</a>,
       which will find the <tref>term</tref> that most appropriately
       matches the value's mappings.</p>
 
@@ -2293,7 +2293,7 @@
         <tref>language mapping</tref> (or some combination of these), then it
         will have an entry in the <tref>inverse context</tref> using the special
         key <code>@none</code>. This allows the
-        <a href="#term-selection-subalgorithm">Term Selection subalgorithm</a> to fall back
+        <a href="#term-selection">Term Selection algorithm</a> to fall back
         to choosing more generic <tref title="term">terms</tref> when a more
         specifically-matching <tref>term</tref> is not available for a particular
         <tref>IRI</tref> and value combination.</p>
@@ -2496,7 +2496,7 @@
         JSON-LD lists, the <tref>type mapping</tref> or <tref>language mapping</tref>
         will be chosen based on the most specific values that work for all items in
         the list. Once this information is gathered, it is passed to the
-        <a href="#term-selection-subalgorithm">Term Selection subalgorithm</a>, which will
+        <a href="#term-selection">Term Selection algorithm</a>, which will
         return the most appropriate <tref>term</tref> to use.</p>
 
       <p>If no <tref>term</tref> was found that could be used to compact the
@@ -2638,7 +2638,7 @@
               </ol>
             </li>
             <li>Initialize <em>term</em> to the result of the
-              <a href="#term-selection-subalgorithm">Term Selection subalgorithm</a>, passing
+              <a href="#term-selection">Term Selection algorithm</a>, passing
               <tref>active context</tref>, <em>inverse context</em>, <em>iri</em>,
               <em>value</em>, <em>parent</em>, <em>containers</em>,
               <em>typeOrLanguage</em>, and <em>typeOrLanguageValue</em>.</li>
@@ -2701,11 +2701,10 @@
   </section> <!-- end of IRI Compaction -->
 
   <section>
-    <h2>Term Selection Subalgorithm</h2>
-
-    <p>This subalgorithm, invoked via the
-      <a href="#iri-compaction">IRI Compaction algorithm</a>, makes use
-      of an <tref title="active context">active context's</tref>
+    <h2>Term Selection</h2>
+
+    <p>This algorithm, invoked via the <a href="#iri-compaction">IRI Compaction algorithm</a>,
+      makes use of an <tref title="active context">active context's</tref>
       <tref>inverse context</tref> to find the <tref>term</tref> that is best
       used to <tref title="compaction">compact</tref> an <tref>IRI</tref>. Other
       information about a value associated with the <tref>IRI</tref> is given,
@@ -2749,7 +2748,7 @@
     <section>
       <h3>Algorithm</h3>
 
-      <p>This subalgorithm has eight required inputs. They are:
+      <p>This algorithm has eight required inputs. They are:
         an <tref>active context</tref>, an <tref>inverse context</tref>, an
         <tref>IRI</tref> <em>iri</em>, a <em>value</em> associated with the
         <tref>IRI</tref>, the expanded <em>parent</em> element for <em>value</em>
@@ -2825,7 +2824,7 @@
                   <em>selected term</em> is <tref>null</tref>:
                   <ol class="algorithm">
                     <li>Initialize <em>match</em> to the result of using the
-                      <a href="#find-property-generator-duplicates-subalgorithm">Find Property Generator Duplicates algorithm</a>,
+                      <a href="#find-property-generator-duplicates">Find Property Generator Duplicates algorithm</a>,
                       passing <tref>active context</tref>,
                       <em>parent</em> for <em>element</em>, <em>iri</em> for
                       <em>expanded property</em>, <em>value</em>,
@@ -2847,7 +2846,7 @@
         <li>Return <em>selected term</em>.</li>
       </ol>
     </section>
-  </section> <!-- end of Term Selection subalgorithm -->
+  </section> <!-- end of Term Selection -->
 
   <section>
     <h2>Value Compaction</h2>
@@ -2990,7 +2989,7 @@
   </section> <!-- end of Value Compaction algorithm -->
 
   <section>
-    <h2>Find Property Generator Duplicates Subalgorithm</h2>
+    <h2>Find Property Generator Duplicates</h2>
 
     <p>This algorithm checks if a specific value exists for all
       <tref title="IRI">IRIs</tref> associated with a
@@ -3073,7 +3072,7 @@
       </li>
       <li>Return <em>result</em>.</li>
     </ol>
-  </section> <!-- end of Find Property Generator Duplicates Subalgorithm -->
+  </section> <!-- end of Find Property Generator Duplicates -->
 </section> <!-- end of Compaction section -->
 
 
@@ -3295,12 +3294,12 @@
         <li>Expand <em>element</em> according the
           <a href="#expansion-algorithm">Expansion algorithm</a>.</li>
         <li>Generate a <em>nodeMap</em> according the
-          <a href="#node-map-generation">Node Map Generation subalgorithm</a>.</li>
+          <a href="#node-map-generation">Node Map Generation algorithm</a>.</li>
         <li>Initialize an empty <tref>RDF dataset</tref> <em>dataset</em>.</li>
         <li>For each <em>graph name</em> and <em>graph</em> in <em>nodeMap</em>:
           <ol class="algorithm">
             <li>Retrieve <em>triples</em> using the
-              <a href="#nodemap-rdf">Node Map to RDF subalgorithm</a>.</li>
+              <a href="#node-map-to-rdf-conversion">Node Map to RDF Conversion algorithm</a>.</li>
             <li>If <em>graph name</em> is <code>@default</code>, add
               <em>triples</em> to the <tref>default graph</tref> in <em>dataset</em>.</li>
             <li>Otherwise, create a <tref>named graph</tref> in <em>dataset</em>
@@ -3312,11 +3311,11 @@
     </section>
   </section> <!-- end of Convert to RDF Algorithm -->
 
-  <section id="nodemap-rdf">
-    <h3>Node Map to RDF Subalgorithm</h3>
+  <section>
+    <h3>Node Map to RDF Conversion</h3>
 
     <p>This algorithm takes the a <em>Node Map</em> for a particular graph as generated
-      by the <a href="#node-map-generation">Node Map Generation subalgorithm</a>
+      by the <a href="#node-map-generation">Node Map Generation algorithm</a>
       and returns a set of <em>RDF triples</em>.</p>
 
     <section class="informative">
@@ -3331,16 +3330,12 @@
       <h3>General Solution</h3>
 
       <p>Identify <tref title="RDF subject">RDF subjects</tref> and
-        <tref title="RDF predicate">RDF predicates</tref> from the
-        <tref>node</tref> identifier and properties. Transform each property value
-        into an <tref>IRI</tref> or
-        <tref
-        href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal">RDF literal</tref>
-        to generate an <tref>RDF triple</tref>.
-        <tref title="list">Lists</tref> are transformed into an
-        <tref
-        href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF Collection</tref>
-        using the <a href="#list-conversion">List to RDF Conversion subalgorithm.</a></p>
+        <tref title="RDF predicate">RDF predicates</tref> from the <tref>node</tref> identifier
+        and properties. Transform each property value into an <tref>IRI</tref> or
+        <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal">RDF literal</tref>
+        to generate an <tref>RDF triple</tref>. <tref title="list">Lists</tref> are transformed into an
+        <tref href="http://www.w3.org/TR/rdf-schema/#ch_collectionvocab">RDF Collection</tref>
+        using the <a href="#list-to-rdf-conversion">List to RDF Conversion algorithm.</a></p>
     </section>
 
     <section>
@@ -3368,7 +3363,7 @@
                     <li>If <em>item</em> is a <tref>list object</tref>, initialize
                       <em>list result</em> as an empty <tref>array</tref>, and
                       <em>object</em> to the result of the <a
-                      href="#list-conversion">List Conversion algorithm</a>, passing
+                      href="#list-to-rdf-conversion">List Conversion algorithm</a>, passing
                       the value associated with the <code>@list</code> key from
                       <em>item</em> and <em>list result</em>. Append a
                       <tref>triple</tref> composed of <em>subject</em>,
@@ -3378,7 +3373,7 @@
                     <li>Otherwise, <em>item</em> is a <tref>value object</tref>
                       or a <tref>node object</tref>. Generate <em>object</em> as
                       the result of the
-                      <a href="#rdf-object-conversion">Object to RDF Conversion subalgorithm</a>
+                      <a href="#object-to-rdf-conversion">Object to RDF Conversion algorithm</a>
                       passing <em>item</em>. Append a <tref>triple</tref> composed of
                       <em>subject</em>, <em>property</em>, and <em>object</em> to
                       <em>result</em>.</li>
@@ -3391,10 +3386,10 @@
         <li>Return <em>result</em>.</li>
       </ol>
     </section>
-  </section> <!-- end of Node Map to RDF Subalgorithm -->
-
-  <section id="rdf-object-conversion">
-    <h3>Object to RDF Conversion Subalgorithm</h3>
+  </section> <!-- end of Node Map to RDF Conversion -->
+
+  <section>
+    <h3>Object to RDF Conversion</h3>
 
     <p>This algorithm takes a <tref>node</tref> or <tref>value object</tref>
       and transforms it into an <tref
@@ -3458,10 +3453,10 @@
           <tref>blank node identifier</tref> value. Return that value.</li>
       </ol>
     </section>
-  </section> <!-- end of Object to RDF Conversion Subalgorithm -->
-
-  <section id="list-conversion">
-    <h3>List to RDF Conversion Subalgorithm</h3>
+  </section> <!-- end of Object to RDF Conversion -->
+
+  <section>
+    <h3>List to RDF Conversion</h3>
 
     <p>List Conversion is the process of taking a <tref>list</tref> <tref>node</tref>
       and transforming it into an
@@ -3502,7 +3497,7 @@
         <li>For each pair of <em>subject</em> from <em>array</em> and <em>item</em> from <em>list</em>:
           <ol class="algorithm">
             <li>Generate <em>object</em> as the result of the
-              <a href="#rdf-object-conversion">Object to RDF Conversion subalgorithm</a>
+              <a href="#object-to-rdf-conversion">Object to RDF Conversion algorithm</a>
               passing <em>item</em>. Append a <tref>triple</tref> composed of <em>subject</em>,
               <code>rdf:first</code>, and <em>object</em> to <em>list triples</em>.</li>
             <li>Set <em>rest</em> as the next entry in <em>array</em>, or if that
@@ -3515,7 +3510,7 @@
           <code>rdf:nil</code> if <em>array</em> is empty.</li>
       </ol>
     </section>
-  </section> <!-- end of List to RDF Subalgorithm -->
+  </section> <!-- end of List to RDF -->
 
   <section>
     <h2>Convert from RDF Algorithm</h2>