Merge pull request #2040 from nickanderson/CFE-2945/3.12

CFE-2954 Clarify how classes are defined from augments

reference/functions/classesmatching.markdown

@@ -30,7 +30,7 @@ Output:
 
 [%CFEngine_include_snippet(classesmatching.cf, #\+begin_src\s+example_output\s*, .*end_src)%]
 
-**See also:** [variablesmatching()][variablesmatching], [bundlesmatching()][bundlesmatching]
+**See also:** [variablesmatching()][variablesmatching], [bundlesmatching()][bundlesmatching], [classes defined via augments][Augments#classes], [classmatch()][classmatch], [countclassesmatching()][countclassesmatching] 
 
 **Note**: This function replaces the `allclasses.txt` static file available
 in older versions of CFEngine.

reference/functions/classmatch.markdown

@@ -24,4 +24,4 @@ Output:
 
 [%CFEngine_include_snippet(classmatch.cf, #\+begin_src\s+example_output\s*, .*end_src)%]
 
-**See also:** [canonify()][canonify], [classify()][classify], [classesmatching()][classesmatching]
+**See also:** [canonify()][canonify], [classify()][classify], [classesmatching()][classesmatching], [classes defined via augments][Augments#classes], [countclassesmatching()][countclassesmatching]

reference/functions/countclassesmatching.markdown

@@ -24,3 +24,5 @@ You can optionally restrict the search by tags, which you can list after the reg
 Output:
 
 [%CFEngine_include_snippet(countclassesmatching.cf, #\+begin_src\s+example_output\s*, .*end_src)%]
+
+**See also:** [classes defined via augments][Augments#classes], [classmatch()][classmatch], [classesmatching()][classesmatching] 

reference/language-concepts/augments.markdown

@@ -76,19 +76,25 @@ Variables of other types than string can be defined too, like in this example
 ## classes
 
 Any class names you put here will be evaluated and installed as **hard classes**
-if they match as a class name or a regular expression. Thus:
+if they match the [anchored regular expression][anchored]. You can use any
+[**hard** classes][Classes and Decisions], persistent classes, or classes
+defined earlier in the augments list. Thus:
 
 ```
 "classes":
 {
-  "my_always": "any",
+  "my_always": [ "any" ],
   "my_other_apache": [ "server[34]", "debian.*" ],
+  "my_other_always": [ "my_always" ],
+  "when_MISSING_not_defined": [ "^(?!MISSING).*" ]
 }
 ```
 
 results in `my_always` being always defined. `my_other_apache` will be defined
-if the classes `server3` or `server4` are defined, or if any class starting
-with `debian` is defined. You can use any [**hard** classes][Classes and Decisions].
+if the classes `server3` or `server4` are defined, or if any class starting with
+`debian` is defined. `my_other_always` will be defined because `my_always` is
+always defined, and listed first. `when_MISSING_not_defined` will be defined if
+the class `MISSING` is not defined.
 
 You can see the list of classes thus defined through `def.json` in the output
 of `cf-promises --show-classes` (see [Components and Common Control][]). They
@@ -99,9 +105,14 @@ the above two classes result in:
 % cf-promises --show-classes=my_
 ...
 my_always                                                    source=augments_file,hardclass
+my_other_always                                              source=augments_file,hardclass
 my_other_apache                                              source=augments_file,hardclass
 ```
 
+**See also:**
+
+* Functions that use regular expressions with classes: `classesmatching()`, `classmatch()`, `countclassesmatching()`
+
 ## augments
 
 A list of file names that should be merged using `mergedata()` semantic