Update trace docs and spec for the loop-head element

Extend the documentation to cover the new version of location-only
called loop-head.

Author: Thomas Kiley

doc/assets/xml_spec.md

@@ -389,10 +389,18 @@ Function Return (element name: `function_return`)
 </xs:element>
 ```
 
-All Other Steps (element name: `location-only`)
+All Other Steps (element name: `location-only` and `loop-head`)
+
+A step that indicates where in the source program we are.
+
+A `location-only` step is emitted if the source location exists and
+differs from the previous one.
+
+A  `loop-head` step is emitted if the location relates to the start of a loop,
+even if the previous step is also the same start of the loop (to ensure
+that it is printed out for each loop iteration)
+
 
-Only included if the source location exists and differs from the
-previous one.\
 **Attributes**:
 
 -   `hidden`: boolean attribute
@@ -411,6 +419,9 @@ previous one.\
 <location-only hidden="false" step_nr="19" thread="0">
   <location .. />
 </location-only>
+<loop-head hidden="false" step_nr="19" thread="0">
+  <location .. />
+</loop-head>
 ```
 
 **XSD**:
@@ -424,6 +435,15 @@ previous one.\
     <xs:attributeGroup ref="traceStepAttrs">
   </xs:complexType>
 </xs:element>
+
+<xs:element name="loop-head">
+  <xs:complexType>
+    <xs:all>
+      <xs:element name="location" minOccurs="0"></xs:element>
+    </xs:all>
+    <xs:attributeGroup ref="traceStepAttrs">
+  </xs:complexType>
+</xs:element>
 ```
 
 Full Trace XSD
@@ -440,6 +460,7 @@ Full Trace XSD
       <xs:element ref="input"></xs:element>
       <xs:element ref="output"></xs:element>
       <xs:element ref="location-only"></xs:element>
+      <xs:element ref="loop-head"></xs:element>
     </xs:choice>
   </xs:complexType>
 </xs:element>

doc/assets/xml_spec.tex

@@ -373,10 +373,18 @@ \subsection{Trace Steps in XML}
 
 
 \begin{center}
-  {\Large All Other Steps} (element name: \texttt{location-only})
+  {\Large All Other Steps} (element name: \texttt{location-only} and
+\texttt{loop-head})
 \end{center}
 
-\noindent Only included if the source location exists and differs from the previous one.\\
+\noindent A step that indicates where in the source program we are.
+
+A \texttt{location-only} step is emitted if the source location exists and
+differs from the previous one.
+
+A  \texttt{loop-head} step is emitted if the location relates to the start of a loop,
+even if the previous step is also the same start of the loop (to ensure
+that it is printed out for each loop iteration) \\
 
 \noindent\textbf{Attributes}:
 \begin{itemize}
@@ -395,6 +403,9 @@ \subsection{Trace Steps in XML}
 <location-only hidden="false" step_nr="19" thread="0">
   <location .. />
 </location-only>
+<loop-head hidden="false" step_nr="19" thread="0">
+<location .. />
+</loop-head>
 \end{minted}
 
 \noindent\textbf{XSD}:
@@ -407,6 +418,14 @@ \subsection{Trace Steps in XML}
     <xs:attributeGroup ref="traceStepAttrs">
   </xs:complexType>
 </xs:element>
+<xs:element name="loop-head">
+  <xs:complexType>
+    <xs:all>
+      <xs:element name="location" minOccurs="0"></xs:element>
+    </xs:all>
+    <xs:attributeGroup ref="traceStepAttrs">
+  </xs:complexType>
+</xs:element>
 \end{minted}
 
 \subsection{Full Trace XSD}
@@ -422,6 +441,7 @@ \subsection{Full Trace XSD}
       <xs:element ref="input"></xs:element>
       <xs:element ref="output"></xs:element>
       <xs:element ref="location-only"></xs:element>
+      <xs:element ref="loop-head"></xs:element>
     </xs:choice>
   </xs:complexType>
 </xs:element>

doc/assets/xml_spec.xsd

@@ -138,6 +138,15 @@
   </xs:complexType>
 </xs:element>
 
+<xs:element name="loop-head">
+  <xs:complexType>
+    <xs:all>
+      <xs:element ref="location" minOccurs="0"/>
+    </xs:all>
+    <xs:attributeGroup ref="traceStepAttrs"/>
+  </xs:complexType>
+</xs:element>
+
 <xs:element name="goto_trace">
   <xs:complexType>
     <xs:choice minOccurs="0" maxOccurs="unbounded">
@@ -148,6 +157,7 @@
       <xs:element ref="input"></xs:element>
       <xs:element ref="output"></xs:element>
       <xs:element ref="location-only"></xs:element>
+      <xs:element ref="loop-head"></xs:element>
     </xs:choice>
   </xs:complexType>
 </xs:element>