Add trigger/complete expression language reference

Document the expression language used by the trigger and complete
attributes as a dedicated, reference-level page in the User Manual.
The specification is derived from the expression lexer/parser and the
abstract syntax tree it produces, and covers the operands and
operators, a two-layer (lexical and syntactic) EBNF grammar, operator
precedence and associativity, and worked examples showing the
fully-bracketed parse of representative expressions.

Re ECFLOW-2112

Author: marcosbento

docs/_static/css/custom_style.css

@@ -67,3 +67,26 @@ div.admonition.implementation > .admonition-title {
     background-color: #e0e0e0;
     color: #424242;
 }
+
+/* Grammar (productionlist) blocks are rendered as a bare <pre> and can contain
+   long lines; keep them within the content area by scrolling horizontally
+   instead of overflowing past the right-hand border.
+   The `grammar-pre` class is added by _static/js/grammar_terminals.js to the
+   productionlist blocks only, so these rules do not affect other <pre> blocks. */
+.rst-content pre.grammar-pre {
+    max-width: 100%;
+    overflow-x: auto;
+    white-space: pre;
+    /* Match the size/metrics of code (highlight/literal) blocks: a bare <pre>
+       (as produced by productionlist) otherwise renders at 1em, much larger. */
+    font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", Courier, monospace;
+    font-size: 12px;
+    line-height: 1.4;
+}
+
+/* Terminal (quoted) symbols in the grammar productionlist blocks, wrapped by
+   _static/js/grammar_terminals.js, are coloured blue to distinguish them from
+   the non-terminals. */
+.rst-content pre.grammar-pre .grammar-terminal {
+    color: #1565c0;
+}

docs/_static/js/grammar_terminals.js

@@ -0,0 +1,60 @@
+// Colourise terminal (quoted) symbols in grammar ``productionlist`` blocks.
+//
+// Sphinx renders a ``.. productionlist::`` as a bare <pre> in which the
+// non-terminals are <strong>/<a> elements but the terminal literals (e.g.
+// ":", "(", "and") are plain text with no markup to style. This script wraps
+// each double-quoted literal in a <span class="grammar-terminal"> so it can be
+// coloured via CSS, making terminals stand out from non-terminals.
+(function () {
+    function colouriseTerminals(root) {
+        var walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+        var textNodes = [];
+        var node;
+        while ((node = walker.nextNode())) {
+            textNodes.push(node);
+        }
+        textNodes.forEach(function (textNode) {
+            var text = textNode.nodeValue;
+            if (text.indexOf('"') === -1) {
+                return;
+            }
+            var frag = document.createDocumentFragment();
+            var re = /"[^"]*"/g;
+            var last = 0;
+            var match;
+            while ((match = re.exec(text)) !== null) {
+                if (match.index > last) {
+                    frag.appendChild(document.createTextNode(text.slice(last, match.index)));
+                }
+                var span = document.createElement('span');
+                span.className = 'grammar-terminal';
+                span.textContent = match[0];
+                frag.appendChild(span);
+                last = re.lastIndex;
+            }
+            if (last < text.length) {
+                frag.appendChild(document.createTextNode(text.slice(last)));
+            }
+            textNode.parentNode.replaceChild(frag, textNode);
+        });
+    }
+
+    function run() {
+        var pres = document.querySelectorAll('.rst-content pre');
+        Array.prototype.forEach.call(pres, function (pre) {
+            // Only touch productionlist blocks (they contain grammar-token anchors).
+            if (pre.querySelector('strong[id^="grammar-token"]')) {
+                // Tag the block so the scoped CSS (see custom_style.css) applies to
+                // grammar blocks only, not to every <pre> on the page.
+                pre.classList.add('grammar-pre');
+                colouriseTerminals(pre);
+            }
+        });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', run);
+    } else {
+        run();
+    }
+})();

docs/conf.py

@@ -84,6 +84,8 @@
 
 html_css_files = ["css/custom_style.css"]
 
+html_js_files = ["js/grammar_terminals.js"]
+
 html_logo = ""
 
 highlight_language = "none"

docs/ug/index.rst

@@ -15,6 +15,7 @@ User Manual
    user_manual/python_based_suite_definition/index.rst
    user_manual/node_attribute_overview
    user_manual/definition_file_format
+   user_manual/expression_spec
    ecflow_ui/index.rst
    cookbook/index.rst
    elearning