HPCC-8549 Document all the DICTIONARY syntax changes. Edits

Signed-off-by: Richard Taylor <richard.taylor@lexisnexis.com>

docs/ECLLanguageReference/ECLR_mods/Basics-ActionsandAttrib.xml

@@ -4,30 +4,33 @@
 <sect1 id="Actions_and_Attributes">
   <title>Actions and Definitions</title>
 
-  <para>There are several built-in Actions in ECL (such as OUTPUT), but there
-  are many more actions that you can execute as queries to the supercomputer.
-  Fundamentally, an Action is simply an expression that produces a result that
-  has not been given a definition name.</para>
+  <para>While Definitions define expressions that may be evaluated, Actions
+  trigger execution of a workunit that produces results that may be viewed. An
+  Action may evaluate Definitions to produce its result. There are a number of
+  built-in Actions in ECL (such as OUTPUT), and any expression (without a
+  Definition name) is implicitly treated as an Action to produce the result of
+  the expression.</para>
 
   <sect2 id="Functions_as_ActionsFunctions_as_Actions">
-    <title>Functions as Actions<indexterm>
-        <primary>Functions as Actions</primary>
+    <title>Expressions as Actions<indexterm>
+        <primary>Expressions as Actions</primary>
       </indexterm></title>
 
-    <para>Fundamentally, all the built-in functions that return single values
-    (such as COUNT) can be executed as Actions. For example,</para>
+    <para>Fundamentally, any expression in can be treated as an Action. For
+    example,</para>
 
-    <programlisting>Attr1 := COUNT(Trades);
+    <programlisting>Attr1 := COUNT(Trades);     
 Attr2 := MAX(Trades,trd_bal);
 Attr3 := IF (1 = 0, 'A', 'B');</programlisting>
 
-    <para>are all definitions, but</para>
+    <para>are all definitions, but without a definition name, they are simply
+    expressions</para>
 
-    <programlisting>COUNT(Trades);       //execute these Function calls as Actions
+    <programlisting>COUNT(Trades);       //execute these expressions as Actions
 MAX(Trades,trd_bal);
 IF (1 = 0, 'A', 'B');</programlisting>
 
-    <para>are also all valid actions, and as such, can directly generate
+    <para>that are treated as actions, and as such, can directly generate
     result values by simply submitting them as queries to the supercomputer.
     Basically, any ECL expression can be used as an Action to instigate a
     workunit.</para>
@@ -38,9 +41,8 @@ IF (1 = 0, 'A', 'B');</programlisting>
         <primary>Definitions as Actions</primary>
       </indexterm></title>
 
-    <para>Any definition that defines a single value or record set can be
-    executed as an Action. These same actions can be executed by submitting
-    the names of the Attributes as queries, like this:</para>
+    <para>These same expression definitions can be executed by submitting the
+    names of the Definitions as queries, like this:</para>
 
     <programlisting>Attr1; //These all generate the same result values
 Attr2; // as the previous examples
@@ -52,9 +54,9 @@ Attr3;</programlisting>
         <primary>Actions as Definitions</primary>
       </indexterm></title>
 
-    <para>Conversely, by simply giving any Action a Definition name you turn
-    it into a definition, therefore no longer a directly executable action.
-    For example,</para>
+    <para>Conversely, by simply giving any Action a Definition name it becomes
+    a definition, therefore no longer a directly executable action. For
+    example,</para>
 
     <programlisting>OUTPUT(Person);</programlisting>
 
@@ -67,7 +69,7 @@ Attr3;</programlisting>
     must execute the Definition name you've given to the Action, like
     this:</para>
 
-    <programlisting>Attr4; // run the OUTPUT(Person) action</programlisting>
+    <programlisting>Attr4;    // run the previously defined OUTPUT(Person) action </programlisting>
   </sect2>
 
   <sect2 id="Debugging_Uses">

docs/ECLLanguageReference/ECLR_mods/Basics-AttributeDef.xml

@@ -6,12 +6,12 @@
 
   <para>Each ECL definition<indexterm>
       <primary>ECL definition</primary>
-    </indexterm> is the basic building block of ECL. A definition asserts that
-  something is true; it defines <emphasis>what </emphasis>is done but not
-  <emphasis>how</emphasis> it is to be done. Definitions can be thought of as
-  a highly developed form of macro-substitution, making each succeeding
-  definition more and more highly leveraged upon the work that has gone
-  before. This results in extremely efficient query construction.</para>
+    </indexterm> is the basic building block of ECL. A definition specifies
+  <emphasis>what </emphasis>is done but not <emphasis>how</emphasis> it is to
+  be done. Definitions can be thought of as a highly developed form of
+  macro-substitution, making each succeeding definition more and more highly
+  leveraged upon the work that has gone before. This results in extremely
+  efficient query construction.</para>
 
   <para>All definitions take the form:</para>
 

docs/ECLLanguageReference/ECLR_mods/Basics-AttributeVisibility.xml

@@ -10,7 +10,7 @@
   disk). Within a module, you may define as many Definitions as needed. An
   IMPORT statement (see the <emphasis role="bold">IMPORT </emphasis>keyword)
   identifies any other modules whose visible Definitions will be available for
-  use in the current definition definition.</para>
+  use in the current definition.</para>
 
   <programlisting>IMPORT AnotherModule; //imports definitions from AnotherModule
 Definition1 := 5;     //as many definitions as needed</programlisting>

docs/ECLLanguageReference/ECLR_mods/Basics-FieldandAttribute.xml

@@ -13,8 +13,8 @@
         <primary>EXPORTed Definitions</primary>
       </indexterm> defined within another module and IMPORTed<indexterm>
         <primary>IMPORTed</primary>
-      </indexterm> (see the <emphasis role="bold">EXPORT </emphasis>and
-    <emphasis role="bold">IMPORT</emphasis> keywords) are available for use in
+      </indexterm> (see the <link linkend="EXPORT">EXPORT</link> and <link linkend="IMPORT">IMPORT</link>
+     keywords) are available for use in
     the definition that contains the IMPORT. Imported Definitions must be
     fully qualified by their Module name and Definition name, using dot
     syntax<indexterm>

docs/ECLLanguageReference/ECLR_mods/Basics-FunctionAttributes.xml

@@ -162,19 +162,19 @@ OUTPUT(FilteredDS(SomeFile));</programlisting>
     <para><emphasis>DefinitionName</emphasis><emphasis role="bold">(
     DICTIONARY<indexterm>
         <primary>DICTIONARY parameter</primary>
-      </indexterm>(</emphasis><emphasis> struct </emphasis><emphasis
+      </indexterm>(</emphasis><emphasis> structure </emphasis><emphasis
     role="bold">) </emphasis><emphasis>AliasName</emphasis><emphasis
     role="bold"> ) := </emphasis><emphasis>expression</emphasis><emphasis
     role="bold">;</emphasis></para>
 
-    <para>The required <emphasis>struct</emphasis> names the RECORD structure
-    that defines the layout of fields in the passed DICTIONARY parameter. The
-    required<emphasis> AliasName</emphasis> names the DICTIONARY for use in
-    the function and is used in the Definition's
-    <emphasis>expression</emphasis> to indicate where in the operation the
-    passed parameter is to be used. See the <emphasis role="bold">DICTIONARY
-    as a Value Type</emphasis> discussion in the DICTIONARY
-    documentation.</para>
+    <para>The required <emphasis>structure</emphasis> parameter is the RECORD
+    structure that defines the layout of fields in the passed DICTIONARY
+    parameter (usually defined inline). The required<emphasis>
+    AliasName</emphasis> names the DICTIONARY for use in the function and is
+    used in the Definition's <emphasis>expression</emphasis> to indicate where
+    in the operation the passed parameter is to be used. See the <emphasis
+    role="bold">DICTIONARY as a Value Type</emphasis> discussion in the
+    DICTIONARY documentation.</para>
 
     <programlisting>rec := RECORD
   STRING10  color;
@@ -188,13 +188,18 @@ Ds := DATASET([{'Black' ,0 , 'Fred'},
 
 DsDCT := DICTIONARY(DS,{color =&gt; DS});
 
+DCTrec := RECORD 
+  STRING10 color =&gt; 
+  UNSIGNED1 code,
+  STRING10 name,
+END;
 InlineDCT := DICTIONARY([{'Black' =&gt; 0 , 'Fred'},
                          {'Brown' =&gt; 1 , 'Sam'},
                          {'Red'   =&gt; 2 , 'Sue'},
                          {'White' =&gt; 3 , 'Jo'} ], 
-                        {STRING10 color =&gt; UNSIGNED1 code,STRING10 name});
+                        DCTrec);
 
-MyDCTfunc(DICTIONARY({STRING10 color =&gt; UNSIGNED1 code,STRING10 name}) DCT,STRING10 key) := DCT[key].name;
+MyDCTfunc(DICTIONARY(DCTrec) DCT,STRING10 key) := DCT[key].name;
 
 MyDCTfunc(InlineDCT,'White');  //Jo
 MyDCTfunc(DsDCT,'Brown');      //Seth</programlisting>
@@ -316,7 +321,7 @@ OUTPUT(doApplyValue(2, multiValues));             // 24
 
 
           
-//An definition taking function parameters which themselves
+//A definition taking function parameters which themselves
 //have parameters that are functions...
 
 STRING doMany(INTEGER v1,

docs/ECLLanguageReference/ECLR_mods/BltInFunc-CASE.xml

@@ -44,8 +44,7 @@
           <row>
             <entry><emphasis>value</emphasis></entry>
 
-            <entry>The value to return. This may be a single value, a set of
-            values, a DATASET, a DICTIONARY, a record set, or an
+            <entry>The value to return. This may be any expression or
             action.</entry>
           </row>
 

docs/ECLLanguageReference/ECLR_mods/BltInFunc-CHOOSE.xml

@@ -30,8 +30,7 @@
 
             <entry>The values to return. There may be as many value parameters
             as necessary to specify all the expected values of the expression.
-            This may be a single value expression, a set of values, a DATASET,
-            a DICTIONARY, a record set, or an action.</entry>
+            This may be any expression or action.</entry>
           </row>
 
           <row>
@@ -39,8 +38,7 @@
 
             <entry>The value to return when the expression returns an
             out-of-range value. The last parameter is always the
-            <emphasis>elsevalue</emphasis>. This may not be a record
-            set.</entry>
+            <emphasis>elsevalue</emphasis>. </entry>
           </row>
 
           <row>

docs/ECLLanguageReference/ECLR_mods/BltInFunc-IF.xml

@@ -37,17 +37,15 @@
             <entry><emphasis>trueresult</emphasis></entry>
 
             <entry>The result to return when the expression is true. This may
-            be a single value, a SET of values, a DATASET, a DICTIONARY, a
-            recordset, or an action to perform.</entry>
+            be any expression or action.</entry>
           </row>
 
           <row>
             <entry><emphasis>falseresult</emphasis></entry>
 
             <entry>The result to return when the expression is false. This may
-            be a single value, a SET of values, a DATASET, a DICTIONARY, a
-            recordset, or an action to perform. This may be omitted only if
-            the result is an action.</entry>
+            be any expression or action. This may be omitted only if the
+            result is an action.</entry>
           </row>
 
           <row>

docs/ECLLanguageReference/ECLR_mods/Expr-InOps.xml

@@ -30,8 +30,8 @@
         <row>
           <entry><emphasis>value_set</emphasis></entry>
 
-          <entry>A set of values. This may be an explicit set of values, the
-          SET function, or a DICTIONARY.</entry>
+          <entry>A set of values. This may be a set expression or a
+          DICTIONARY.</entry>
         </row>
       </tbody>
     </tgroup>