Merge pull request #3346 from nickanderson/rename-normal-order-policy-eval/master

Renamed Normal ordering to Policy evaluation

Author: nickanderson

examples/tutorials/writing-and-serving-policy/policy-style.markdown

@@ -28,9 +28,9 @@ guide.
 ## Promise ordering
 
 There are two common styles that are used when writing policy. The
-[Normal Order][Normal ordering] style dictates that promises should be
-written in in the Normal Order that the agent evaluates promises
-in. The other is reader optimized where promises are written in the
+[Normal Order][Policy evaluation] style dictates that promises should be
+written in the order that the agent evaluates promises.
+The other is reader optimized where promises are written in the
 order they make sense to the reader. Both styles have their merits,
 but there seems to be a trend toward the reader optimized style.
 

reference/functions.markdown

@@ -111,11 +111,11 @@ When enabled
 [cached functions](https://docs.cfengine.com/docs/{{site.cfengine.branch}}/search.html?q=The+return+value+is+cached)
 are **not executed on every pass of convergence**. Instead, the function will
 only be executed once during the
-[agent evaluation step][Normal ordering#Agent evaluation step]
+[agent evaluation step][Policy evaluation#Agent evaluation step]
 and its result will be cached until the end of that agent execution.
 
 **Note:** Cached functions are executed multiple times during
-[policy validation and pre-evaluation][Normal ordering#cf-promises policy validation step].
+[policy validation and pre-evaluation][Policy evaluation#cf-promises policy validation step].
 Function caching is *per-process*, so results will not be cached between
 separate components e.g. `cf-agent`, `cf-serverd` and `cf-promises`.
 Additionally functions are cached by hashing the function arguments. If you have

reference/language-concepts.markdown

@@ -63,12 +63,11 @@ CFEngine's boolean classifiers that describe context.
 An association of the form "LVALUE *represents* RVALUE", where RVALUE may be a
 scalar value or a list of scalar values: a string, integer or real number.
 
-This documentation about the language concepts introduces in addition
+This documentation about the language concepts introduces:
 
-* [**normal ordering**][Normal ordering],
-* [**loops**][Loops],
-* [**pattern matching and referencing**][Pattern matching and referencing],
-  and
+* Policy evaluation (also known as [**Normal order**][Policy evaluation])
+* [**loops**][Loops] and implicit iteration
+* [**pattern matching and referencing**][Pattern matching and referencing]
 * [**namespaces**][namespaces]
 
 ## Syntax, identifiers and names

reference/language-concepts/classes.markdown

@@ -289,7 +289,7 @@ If a class is set, then it is certain that the corresponding fact is true.
 However, that a class is not set could mean that something is not the case, or
 that something is simply not known. This is only a problem with soft classes,
 where the state of a class can change during the execution of a policy,
-depending on the [order][normal ordering] in which bundles and promises are
+depending on the [order][Policy evaluation] in which bundles and promises are
 evaluated.
 
 ## Making decisions based on classes

reference/language-concepts/normal-ordering.markdown renamed to reference/language-concepts/policy-evaluation.markdown

@@ -1,6 +1,7 @@
 ---
 layout: default
-title: Normal ordering
+title: Policy evaluation
+alias: Normal ordering
 published: true
 sorting: 40
 ---
@@ -10,7 +11,7 @@ attributes and properties, ordering is irrelevant and should not be considered.
 More complex patterned data structures require ordering to be preserved, e.g.
 editing in files. CFEngine solves this in a two-part strategy:
 
-CFEngine maintains a default order of promise-types. This is based on a simple
+CFEngine maintains a default order of promise-types, referred to as `Normal order`. This is based on a simple
 logic of what needs to come first, e.g. it makes no sense to create something
 and then delete it, but it could make sense to delete and then create (an
 equilibrium). This is called normal ordering and is described below.  You can

reference/promise-types.markdown

@@ -6,7 +6,7 @@ sorting: 20
 ---
 
 Within a bundle, the promise types are executed in a round-robin fashion in the
-following [normal ordering][Normal ordering]. Which promise types are available
+following [normal order][Policy evaluation]. Which promise types are available
 depends on the [bundle][bundles] type:
 
 | Promise type   | common | agent | server | monitor |

reference/promise-types/custom.markdown

@@ -98,7 +98,7 @@ Due to the implementation details, the following attributes from the `classes` b
 ### Evaluation passes and normal order
 
 In CFEngine, each bundle is evaluated in multiple passes (3 main passes for most promise types).
-Within each evaluation pass of a bundle, the promises are not evaluated from top to bottom, but based on a [normal order][Normal ordering] of the promise types.
+Within each evaluation pass of a bundle, the promises are not evaluated from top to bottom, but based on the [normal order][Policy evaluation] of the bundle type.
 Custom promise types are added dynamically and don't have a predefined order, they are evaluated as they appear within a bundle (top to bottom), but at the end of each evaluation pass, after all the built in promise types.
 As with other promise types, we recommend not relying too much on this ordering, if you want some promises to be evaluated before others, use the `bundlesequence` or `depends_on` attribute to achieve this.
 

reference/promise-types/vars.markdown

@@ -377,7 +377,7 @@ two_example_com::
     comment => "Define a global domain for hosts in the two.example.com domain";
 ```
 
-(Promises within the same bundle are evaluated top to bottom, so vars promises further down in a bundle can overwrite previous values of a variable. See [**normal ordering**][Normal ordering] for more information).
+(Promises within the same bundle are evaluated top to bottom, so vars promises further down in a bundle can overwrite previous values of a variable. See [policy evaluation][Policy evaluation] for more information).
 
 ## Defining variables in foreign bundles
 

resources/faq/manual-execution.markdown

@@ -102,4 +102,4 @@ This command will run `cf-agent` with the additional class `patch_and_reboot` on
 classes it is using must be resolvable during pre-evaluation as the full
 evaluation is only allowed when the classes are found to be defined.
 
-**See also:** [How is "recently seen" determined][Components#lastseenexpireafter], [`cf-runagent`][cf-runagent], [pre-evaluation][Normal ordering#agent pre-evaluation step]
+**See also:** [How is "recently seen" determined][Components#lastseenexpireafter], [`cf-runagent`][cf-runagent], [pre-evaluation][Policy evaluation#agent pre-evaluation step]