J#34199: Documented translator options that impact language features

spec/06-translationsemantics.adoc

@@ -405,6 +405,41 @@ Table 6‑O - The ELM equivalent for each CQL construct
 
 Although these elements can be used to directly represent the _query_ construct of CQL, it is also possible to represent queries using a series of equivalent operations that simplify implementation. ELM defines simplified operations specifically for this purpose. See the <<05-languagesemantics.adoc#implementing-query-evaluation,Implementing Query Evaluation>> section for more information on how to transform any given CQL query into an equivalent representation using these operators.
 
+[[translation-options]]
+=== Translation Options
+
+There are several points throughout the specification that introduce optionality to support different use cases and implementation goals. This section provides a summary of those options with an explanation of their impact on translation and language features.
+
+[.note-warning]
+____
+Note that implementations may define other options as appropriate for their translation use cases, but these options all potentially impact whether a given library of CQL can be correctly compiled, and should therefore be used with care. Implementations that make use of these options should provide facilities for ensuring that these options are communicated as part of the resulting ELM output, as well as that the appropriate options are used if the CQL library is re-translated by consuming environments.
+____
+
+[[disable-list-promotion-and-demotion]]
+==== Disable List Promotion and Demotion
+
+List promotion and demotion are a special case of implicit conversions and enable list-valued expressions to be passed to singleton parameters (by invoking the [.kw]#singleton from# operator) and vice-versa (by invoking the [.id]#ToList# function). These conversions are useful for writing expressions against models with deeply nested hierarchies and variable cardinality elements, but can sometimes result in surprising overload selections and conversion choices. As a result, implementations may choose to enable or disable this language feature using the _disable-list-promotion_ and _disable-list-demotion_ options. For a more detailed discussion, see link:03-developersguide.html#promotion-and-demotion[List Promotion and Demotion].
+
+[[disable-list-traversal]]
+==== Disable List Traversal
+
+In addition to list promotion and demotion, CQL allows for paths to be traversed through list-valued elements. Again, this is useful when writing expressions against models with variable cardinality elements, and can be disabled with the _disable-list-traversal_ option. For a more detailed discussion, see link:03-developersguide.html#path-traversal[Path Traversal].
+
+[[disable-method-invocation]]
+==== Disable Method Invocation
+
+To support FHIRPath as the base expression language for CQL, beginning with 1.3, the option to allow functions to be invoked using method-style invocation was introduced. This feature can be disabled using the _disable-method-invocation_ option. For a more complete discussion, see link:03-developersguide.html#method-invocation[Method Invocation].
+
+[.note-warning]
+____
+Note that with the introduction of link:03-developersguide.html#fluent-functions[Fluent Functions] in 1.5, using this option effectively disables fluent functions as well.
+____
+
+[[require-from-keyword]]
+==== Require From Keyword
+
+To encourage consistent use of the [.kw]#from# keyword to being queries, implementations may provide support for the _require-from-keyword_ option. See link:03-developersguide.html#query-syntax-options[Query Syntax Options] for more discussion.
+
 [[elm-to-cql]]
 == ELM-to-CQL