FHIR-27514 - Incorporated Diagram HTML into Authors and Developers Guide

spec/02-authorsguide.adoc

@@ -53,6 +53,8 @@ Libraries can contain any or all of the following constructs:
 
 Table 2‑A - Constructs that CQL libraries can contain
 
+A structure diagram of a library containing all of the constructs can be seen link:cql-structure-diagram.html#library[here].
+
 The following sections discuss these constructs in more detail.
 
 [[library]]
@@ -69,6 +71,8 @@ library CMS153_CQM version '2'
 
 The above declaration names the library with the identifier [.id]#CMS153_CQM# and specifies the version [.lit]#'2'#.
 
+A structure diagram of the [.kw]#library# declaration can be seen link:cql-structure-diagram.html#libraryDefinition[here].
+
 [[data-models]]
 === Data Models
 
@@ -92,6 +96,8 @@ If necessary, a version specifier can be provided to indicate which version of t
 using QUICK version '0.3.0'
 ----
 
+A structure diagram of the [.kw]#using# declaration can be seen link:cql-structure-diagram.html#usingDefinition[here].
+
 [[libraries]]
 === Libraries
 
@@ -142,13 +148,17 @@ define "SexuallyActive":
     or exists (Common."LaboratoryTestsIndicatingSexualActivity")
 ----
 
+A structure diagram of the [.kw]#include# declaration can be seen link:cql-structure-diagram.html#includeDefinition[here].
+
 [[terminology]]
 === Terminology
 
 A CQL library may contain zero or more named terminology declarations, including codesystems, valuesets, codes, and concepts, using the [.kw]#codesystem#, [.kw]#valueset#, [.kw]#code#, and [.kw]#concept# declarations.
 
 These declarations specify a local name that represents a codesystem, valueset, code, or concept and can be used anywhere within the library where the terminology is expected.
 
+The structure diagrams of the link:cql-structure-diagram.html#codesystemDefinition[codesystem definition],link:cql-structure-diagram.html#valuesetDefinition[valueset definition], link:cql-structure-diagram.html#codeDefinition[code definition] and link:cql-structure-diagram.html#conceptDefinition[concept definition].
+
 Consider the following valueset declaration:
 
 [source,cql]
@@ -200,6 +210,8 @@ A CQL library can define zero or more parameters. Each parameter is defined with
 
 Table 2‑B - Elements that define a parameter
 
+A structure diagram of the [.kw]#parameter# can be seen link:cql-structure-diagram.html#parameterDefinition[here].
+
 The parameters defined in a library may be referenced by name in any expression within the library. When expressions in a CQL library are evaluated, the values for parameters are provided by the environment. For example, a library that defines criteria for a quality measure may define a parameter to represent the measurement period:
 
 [source,cql]
@@ -264,6 +276,8 @@ The following table lists some typical contexts:
 
 Table 2‑C - Typical contexts for CQL
 
+A structure diagram of the [.kw]#context# declaration can be seen link:cql-structure-diagram.html#contextDefinition[here].
+
 Depending on different needs, models may define any context appropriate to their use case, but should identify a default context that is used when authors do not declare a specific context.
 
 When no context is specified in the library, and the model has not declared a default context, the default context is [.id]#Unfiltered#.
@@ -324,6 +338,8 @@ The _retrieve_ expression is the central construct for accessing clinical inform
 
 The retrieve in CQL has two main parts: first, the _type_ part, which identifies the type of data that is to be retrieved; and second, the _filter_ part, which optionally provides filtering information based on specific types of filters common to most clinical data.
 
+A structure diagram of the [.kw]#retrieve# expression can be seen link:cql-structure-diagram.html#retrieve[here].
+
 Note that the retrieve only introduces data into an expression; operations for further filtering, shaping, computation, and sorting will be discussed in later sections.
 
 [[clinical-statement-structure]]
@@ -514,6 +530,8 @@ Note that alias names, as with all language constructs, may be the subject of la
 
 The [.kw]#where# clause allows the results of the query to be filtered by a condition that is evaluated for each element of the query being filtered. If the condition evaluates to [.kw]#true# for the element being tested, that element is included in the result. Otherwise, the element is excluded from the resulting list.
 
+A structure diagram of a [.kw]#where# clause can be seen link:cql-structure-diagram.html#whereClause[here].
+
 For example:
 
 [source,cql]
@@ -542,6 +560,8 @@ Note that because CQL uses three-valued logic, the result of evaluating any give
 
 The [.kw]#return# clause of a CQL query allows the results of the query to be shaped. In most cases, the results of a query will be of the same type as the primary source of the query. However, some scenarios require only specific elements be extracted, or computations on the data involved in each element be performed. The [.kw]#return# clause enables this type of query.
 
+A structure diagram of a [.kw]#return# clause can be seen link:cql-structure-diagram.html#returnClause[here].
+
 For example:
 
 [source,cql]
@@ -571,7 +591,11 @@ If two encounters have the same value for [.id]#lengthOfStay#, that value will o
 [[sorting]]
 === Sorting
 
-CQL queries can sort results in any order using the [.kw]#sort by# clause. For example:
+CQL queries can sort results in any order using the [.kw]#sort by# clause.
+
+A structure diagram of a [.kw]#sort# clause can be seen link:cql-structure-diagram.html#sortClause[here].
+
+For example:
 
 [source,cql]
 ----
@@ -649,6 +673,8 @@ The [.kw]#without# clause returns only those elements from the primary source th
 
 This query is the same as the previous example, except that only encounters that _do not_ have overlapping conditions of [.id]#"Acute Pharyngitis"# are returned. In other words, if the _such that_ condition evaluates to [.kw]#true# (if the Encounter has an overlapping Condition of [.id]#Acute Pharyngitis# in this case), then that Encounter is not included in the result.
 
+A structure diagram of a link:cql-structure-diagram.html#withClause[with] clause and link:cql-structure-diagram.html#withoutClause[without] clause.
+
 A given query may include any number of [.kw]#with# and [.kw]#without# clauses in any order, but they must all come before any [.kw]#where#, [.kw]#return#, or [.kw]#sort# clauses.
 
 The [.kw]#such that# conditions in the examples above used <<Timing Relationships>> (e.g. during, after end of), but any expression may be used, so long as the overall result is boolean-valued. For example:
@@ -850,6 +876,8 @@ For case- and locale-insensitive comparison, locale-insensitive meaning that an
 
 CQL supports the representation of [.id]#Date#, [.id]#DateTime#, and [.id]#Time# values.
 
+A structure diagram of a [.id]#Date, DateTime and Time# format can be seen link:cql-structure-diagram.html#DATETIME[here].
+
 [.id]#DateTime# values are used to represent an instant along the timeline, known to at least the year precision, and potentially to the millisecond precision. [.id]#DateTime# values are specified using an at-symbol ([.sym]#@#) followed by an ISO-8601 textual representation of the [.id]#DateTime# value:
 
 [source,cql]
@@ -973,6 +1001,8 @@ The [.id]#Code# type has the following elements:
 
 Table 2‑F - Elements that make up a [.kw]#code# type
 
+A structure diagram of a [.id]#Code# declaration can be seen link:cql-structure-diagram.html#codeDefinition[here].
+
 The following examples illustrate the code declaration:
 
 [source,cql]
@@ -986,7 +1016,11 @@ code "Diastolic blood pressure": '8462-4' from "LOINC" display 'Diastolic blood
 
 The above declarations can be referenced directly or within a <<filtering-with-terminology,retrieve expression>>.
 
-In addition, CQL provides a [.id]#Code# literal that can be used to reference an existing code from a specific code system:
+A structure diagram of a [.id]#Code# referencing an existing code can be seen link:cql-structure-diagram.html#codeSelector[here].
+
+In addition, CQL provides a [.id]#Code# literal that can be used to reference an existing code from a specific code system.
+
+For example
 
 [source,cql]
 ----
@@ -1053,6 +1087,8 @@ concept "Type B Hepatitis": { "Hepatitis Type B (SNOMED)", "Hepatitis Type B (IC
 
 The above declaration can be referenced directly or within a <<filtering-with-terminology,retrieve expression>>.
 
+A structure diagram of a [.id]#Concept# declaration can be seen link:cql-structure-diagram.html#conceptDefinition[here].
+
 As with codes, local names for concept declarations should be consistent with external declarations to avoid introducing any confusion of meaning.
 
 The following example illustrates the use of a [.id]#Concept# literal:
@@ -1067,11 +1103,15 @@ Concept {
 
 This example constructs a [.id]#Concept# with display [.lit]#'Type B viral hepatitis'# and code of [.lit]#'66071002'#.
 
+A structure diagram of a [.id]#Concept# literal can be seen link:cql-structure-diagram.html#conceptSelector[here].
+
 [[valuesets]]
 ==== Valuesets
 
 As a value, a valueset is simply a list of [.id]#Code# values. However, CQL allows valuesets to be used without reference to the codes involved by declaring valuesets as a special type of value within the language.
 
+A structure diagram of a valueset declaration can be seen link:cql-structure-diagram.html#valuesetDefinition[here].
+
 The following example illustrates some typical valueset declarations:
 
 [source,cql]
@@ -1163,7 +1203,11 @@ The values of the elements of a tuple can be accessed using a dot qualifier ([.s
 define "PharyngitisOnSetDateTime": FirstPharyngitis.onsetDateTime
 ----
 
-Tuples can also be constructed directly using a tuple selector:
+Tuples can also be constructed directly using a tuple selector.
+
+A structure diagram of a _tuple_ selector can be seen link:cql-structure-diagram.html#tupleSelector[here].
+
+For example:
 
 [source,cql]
 ----
@@ -1272,7 +1316,11 @@ For a description of the distinct operator, as well as other operations that can
 
 CQL supports the representation of intervals, or ranges, of values of various types. In particular, intervals of date and time values, and ranges of integers and reals.
 
-Intervals in CQL are represented by specifying the low and high points of the [.id]#Interval# and whether the boundary is inclusive (meaning the boundary point is part of the interval) or exclusive (meaning the boundary point is excluded from the interval). Following standard mathematics notation, inclusive (closed) boundaries are indicated with square brackets, and exclusive (open) boundaries are indicated with parentheses. For example:
+Intervals in CQL are represented by specifying the low and high points of the [.id]#Interval# and whether the boundary is inclusive (meaning the boundary point is part of the interval) or exclusive (meaning the boundary point is excluded from the interval). Following standard mathematics notation, inclusive (closed) boundaries are indicated with square brackets, and exclusive (open) boundaries are indicated with parentheses.
+
+A structure diagram of an [.id]#Interval# construct can be seen link:cql-structure-diagram.html#intervalSelector[here].
+
+For example:
 
 [source,cql]
 ----