Merge pull request #2882 from henrikt-ma/comment-mathescape-emph

Add comments with TODOs after LaTeXML issue is fixed

chapters/classes.tex

@@ -1562,7 +1562,10 @@ \subsubsection{Attributes of Enumeration Types}\label{attributes-of-enumeration-
 
 \subsubsection{Type Conversion of Enumeration Values to String or Integer}\label{type-conversion-of-enumeration-values-to-string-or-integer}
 
-The type conversion function \lstinline!Integer($\mbox{\emph{\textless{}expression of enumeration type\textgreater{}}}$)! returns the ordinal number of the enumeration value \lstinline!E.enumvalue!, to which the expression is evaluated, where $\text{\lstinline!Integer(E.e1)!} = 1$, $\text{\lstinline!Integer(E.en)!} = n$, for an enumeration type \lstinline!E = enumeration(e1, $\ldots$, en)!.
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
+The type conversion function \lstinline!Integer($\langle$$\mbox{\emph{expression of enumeration type}}$$\rangle$)! returns the ordinal number of the enumeration value \lstinline!E.enumvalue!, to which the expression is evaluated, where $\text{\lstinline!Integer(E.e1)!} = 1$, $\text{\lstinline!Integer(E.en)!} = n$, for an enumeration type \lstinline!E = enumeration(e1, $\ldots$, en)!.
 
 \lstinline!String(E.enumvalue)! gives the \lstinline!String! representation of the enumeration value.
 
@@ -1579,10 +1582,10 @@ \subsubsection{Type Conversion of Integer to Enumeration Values}\label{type-conv
 implicitly defined. This function can be used in an expression to
 convert an integer value to the corresponding (as described in \cref{type-conversion-of-enumeration-values-to-string-or-integer}) enumeration value.
 
-For an enumeration type named \lstinline!EnumTypeName!, the expression
-\lstinline!EnumTypeName(<Integer expression>)! returns the
-enumeration value \lstinline!EnumTypeName.e! such that \lstinline!Integer(EnumTypeName.e)! is
-equal to the original integer expression.
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
+For an enumeration type named \lstinline!EnumTypeName!, the expression \lstinline!EnumTypeName($\langle$$\mbox{\emph{Integer expression}}$$\rangle$)! returns the enumeration value \lstinline!EnumTypeName.e! such that \lstinline!Integer(EnumTypeName.e)! is equal to the original integer expression.
 
 Attempting to convert an integer argument that does not correspond to a
 value of the enumeration type is an error.

chapters/connectors.tex

@@ -786,26 +786,28 @@ \section{Equation Operators for Overconstrained Connection-Based Equation System
 
 \subsection{Overconstrained Equation Operators for Connection Graphs}\label{overconstrained-equation-operators-for-connection-graphs}
 
-A type or record declaration may have an optional definition of function
-\lstinline!equalityConstraint! that shall have the following prototype:
+A type or record declaration may have an optional definition of function \lstinline!equalityConstraint! that shall have the following prototype:
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
 \begin{lstlisting}[language=modelica]
 type Type // overdetermined type
-  extends <base type>;
+  extends $\langle$$\mbox{\emph{base type}}$$\rangle$;
   function equalityConstraint // non-redundant equality
     input Type T1;
     input Type T2;
-    output Real residue[ <n> ];
+    output Real residue[$n$];
   algorithm
     residue := $\ldots$;
   end equalityConstraint;
 end Type;
 
 record Record
-  < declaration of record fields>
+  $\langle$$\mbox{\emph{declaration of record fields}}$$\rangle$;
   function equalityConstraint // non-redundant equality
     input Record R1;
     input Record R2;
-    output Real residue[ <n> ];
+    output Real residue[$n$];
   algorithm
     residue := $\ldots$;
   end equalityConstraint;
@@ -875,7 +877,11 @@ \subsection{Overconstrained Equation Operators for Connection Graphs}\label{over
 This function can be used at all places where a \lstinline!connect! statement is allowed.
 
 \begin{nonnormative}
-E.g., it is not allowed to use this function in a when-clause.  This definition shall be used if in a model with connectors \lstinline!A! and \lstinline!B! the overdetermined records \lstinline!A.R! and \lstinline!B.R! are algebraically coupled in the model, e.g., due to \lstinline!B.R = f(A.R!, \textless{}other unknowns\textgreater{}).
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
+E.g., it is not allowed to use this function in a when-clause.
+This definition shall be used if in a model with connectors \lstinline!A! and \lstinline!B! the overdetermined records \lstinline!A.R! and \lstinline!B.R! are algebraically coupled in the model, e.g., due to \lstinline!B.R = f(A.R, $\langle$$\mbox{\emph{other unknowns}}$$\rangle$)!.
 \end{nonnormative}
 \end{semantics}
 \end{operatordefinition}

chapters/functions.tex

@@ -12,7 +12,10 @@ \section{Function Declaration}\label{function-declaration}
 \begin{nonnormative}
 The structure of a typical function declaration is sketched by
 the following schematic function example:
-\begin{lstlisting}[language=modelica,escapechar=!]
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
+\begin{lstlisting}[language=modelica]
 function $\mathit{functionname}$
   input  TypeI1 in1;
   input  TypeI2 in2;
@@ -22,10 +25,10 @@ \section{Function Declaration}\label{function-declaration}
   output TypeO2 out2 = $\mathit{defaultExpr}_{2}$;
   $\ldots$
 protected
-  !\emph{\textless{}local variables\textgreater{}}!
+  $\langle$$\mbox{\emph{local variables}}$$\rangle$
   $\ldots$
 algorithm
-  !\emph{\textless{}statements\textgreater{}}!
+  $\langle$$\mbox{\emph{statements}}$$\rangle$
   $\ldots$
 end $\mathit{functionname}$;
 \end{lstlisting}
@@ -159,7 +162,7 @@ \section{Function as a Specialized Class}\label{function-as-a-specialized-class}
   \end{nonnormative}
   A function \emph{cannot contain} calls to the Modelica \emph{built-in operators} \lstinline!der!, \lstinline!initial!, \lstinline!terminal!, \lstinline!sample!, \lstinline!pre!, \lstinline!edge!, \lstinline!change!, \lstinline!reinit!, \lstinline!delay!, \lstinline!cardinality!, \lstinline!inStream!, \lstinline!actualStream!, to the operators of the built-in package \lstinline!Connections!, to the operators defined in \cref{synchronous-language-elements} and \cref{state-machines}, and is not allowed to contain when-statements.
 \item
-  The dimension \emph{sizes} not declared with (\lstinline!:!) of each array result or array local variable (i.e., a non-input components) of a function must be either given by the input formal parameters, or given by constant or parameter expressions, or by expressions containing combinations of those (\cref{initialization-and-binding-equations-of-components-in-functions}).
+  The dimension \emph{sizes} not declared with colon (\lstinline!:!) of each array result or array local variable (i.e., a non-input component) of a function must be either given by the input formal parameters, or given by constant or parameter expressions, or by expressions containing combinations of those (\cref{initialization-and-binding-equations-of-components-in-functions}).
 \item
   For initialization of local variables of a function see \cref{initialization-and-binding-equations-of-components-in-functions}).
 \item
@@ -202,7 +205,7 @@ \section{Function as a Specialized Class}\label{function-as-a-specialized-class}
 \item
   A function may have a \lstinline!return! statement in its algorithm section body.
 \item
-  A function allows dimension sizes declared with (\lstinline!:!) to be resized for non-input array variables, see \cref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.
+  A function allows dimension sizes declared with colon (\lstinline!:!) to be resized for non-input array variables, see \cref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.
 \item
   A function may be defined in a short function definition to be a
   function partial derivative.

chapters/synchronous.tex

@@ -812,9 +812,12 @@ \subsection{Sub-clock conversion operators}\label{sub-clock-conversion-operators
 \section{Clocked When-Clause}\label{clocked-when-clause}
 
 In addition to the previously discussed conditional when-clause, a \emph{clocked} when-clause\index{clocked!when-clause}\index{when-clause!clocked} is introduced:
-\begin{lstlisting}[language=modelica,escapechar=!]
+% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
+% - https://github.com/brucemiller/LaTeXML/issues/1477
+% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
+\begin{lstlisting}[language=modelica]
 when $\mathit{clockExpression}$ then
-  !\emph{\textless{}clocked equations\textgreater{}}!
+  $\langle$$\mbox{\emph{clocked equations}}$$\rangle$
   $\ldots$
 end when;
 \end{lstlisting}