Cleanup listings related to external-clauses (#2688)

* Improve readability of external-clauses
* Clean up whitespace in listings related to external functions
* Remove bad escaping in 'size\_t' inside lstlisting
* Suggest that we add syntax highlighting for 'size_t' in C
This would be similar to how we do syntax highlighting of certain recognized identifiers in Modelica, apart from the keywords.
* Indent 'external' with to same level as 'function'
The annotation of the external clause is indented one level deeper than the external-function-call, to avoid mixing it up with the function annotation.

chapters/functions.tex

@@ -362,7 +362,8 @@ \section{Pure Modelica Functions}\label{pure-modelica-functions}
 impure function receiveRealSignal // impure function
   input HardwareDriverID id;
   output Real y;
-  external "C" y = receiveSignal(id);
+external "C"
+  y = receiveSignal(id);
 end receiveRealSignal;
 \end{lstlisting}
 Examples of allowed optimizations of pure functions:
@@ -1699,8 +1700,9 @@ \section{External Function Interface}\label{external-function-interface}
 function IDENT description-string
   { component-clause ";" }
   [ protected { component-clause ";" } ]
-  external [ language-specification ] [
-  external-function-call ] [annotation ] ";"
+external [ language-specification ]
+  [ external-function-call ]
+    [annotation ] ";"
   [ annotation ";" ]
 end IDENT;
 \end{lstlisting}
@@ -1735,13 +1737,14 @@ \section{External Function Interface}\label{external-function-interface}
     function sin
       input Real x;
       output Real y;
-      external "builtin" y=sin(x);
+    external "builtin"
+      y = sin(x);
     end sin;
   end Math;
 end Modelica;
 
 model UserModel
-  parameter Real p=Modelica.Math.sin(2);
+  parameter Real p = Modelica.Math.sin(2);
 end UserModel;
 \end{lstlisting}
 \end{example}
@@ -1932,7 +1935,7 @@ \subsubsection{Arrays}\label{arrays-1}
 function foo
   input Real a[:,:,:];
   output Real x;
-  external "FORTRAN 77";
+external "FORTRAN 77";
 end foo;
 \end{lstlisting}
 the default assumptions correspond to a FORTRAN~77 function
@@ -1964,7 +1967,8 @@ \subsubsection{Arrays}\label{arrays-1}
   input Integer i;
   output Real u1[size(y,1)];
   output Integer u2[size(y,2)];
-  external "FORTRAN 77" myfoo(x, y, size(x,1), size(y,2), u1, i, u2);
+external "FORTRAN 77"
+  myfoo(x, y, size(x,1), size(y,2), u1, i, u2);
 end foo;
 \end{lstlisting}
 The corresponding FORTRAN~77 subroutine would be declared as follows:
@@ -1993,7 +1997,7 @@ \subsubsection{Arrays}\label{arrays-1}
 \end{lstlisting}
 This corresponds to the following C prototype:
 \begin{lstlisting}[language=C]
-double fie(double *, size\_t, size\_t);
+double fie(double *, size_t, size_t);
 \end{lstlisting}
 \end{example}
 
@@ -2085,8 +2089,9 @@ \subsection{Aliasing}\label{aliasing}
 function foo
   input Real x;
   input Real y;
-  output Real z=x;
-  external "FORTRAN 77" myfoo(x,y,z);
+  output Real z = x;
+external "FORTRAN 77"
+  myfoo(x, y, z);
 end foo;
 \end{lstlisting}
 The following Modelica function:
@@ -2095,20 +2100,20 @@ \subsection{Aliasing}\label{aliasing}
   input Real a;
   output Real b;
 algorithm
-  b:=foo(a,a);
-  b:=foo(b,2*b);
+  b := foo(a, a);
+  b := foo(b, 2 * b);
 end f;
 \end{lstlisting}
 can on most systems be transformed into the following C function:
 \begin{lstlisting}[language=C]
 double f(double a) {
-  extern void myfoo_(double*,double*,double*);
-  double b,temp1,temp2;
+  extern void myfoo_(double*, double*, double*);
+  double b, temp1, temp2;
 
-  myfoo_(&a,&a,&b);
-  temp1=2*b;
-  temp2=b;
-  myfoo_(&b,&temp1,&temp2);
+  myfoo_(&a, &a, &b);
+  temp1 = 2 * b;
+  temp2 = b;
+  myfoo_(&b, &temp1, &temp2);
 
   return temp2;
 }
@@ -2126,10 +2131,11 @@ \subsection{Aliasing}\label{aliasing}
 \begin{lstlisting}[language=modelica]
 function foo
   input Real x;
-  protected Real xtemp=x; // Temporary used because myfoo changes its input
+  protected Real xtemp = x; // Temporary used because myfoo changes its input
   public input Real y;
   output Real z;
-  external "FORTRAN 77" myfoo(xtemp,y,z);
+external "FORTRAN 77"
+  myfoo(xtemp, y, z);
 end foo;
 \end{lstlisting}
 
@@ -2140,8 +2146,8 @@ \subsection{Aliasing}\label{aliasing}
 follow the standard and are unable to handle aliasing between input
 variables the tool must transform the first call of \lstinline!foo! into:
 \begin{lstlisting}[language=C]
-temp1=a; /* Temporary to avoid aliasing */
-myfoo_(&a,&temp1,&b);
+temp1 = a; /* Temporary to avoid aliasing */
+myfoo_(&a, &temp1, &b);
 \end{lstlisting}
 
 The use of the function \lstinline!foo! in Modelica is uninfluenced by these considerations.
@@ -2227,37 +2233,40 @@ \subsection{Annotations for External Libraries and Include Files}\label{annotati
 \begin{lstlisting}[language=modelica]
 package ExternalFunctions
   model Example
-    Real x(start=1.0),y(start=2.0);
+    Real x(start = 1.0), y(start = 2.0);
   equation
-    der(x)=-ExternalFunc1(x);
-    der(y)=-ExternalFunc2(y);
+    der(x) = -ExternalFunc1(x);
+    der(y) = -ExternalFunc2(y);
   end Example;
 
   model OtherExample
-    Real x(start=1.0);
+    Real x(start = 1.0);
   equation
-    der(x)=-ExternalFunc3(x);
+    der(x) = -ExternalFunc3(x);
   end OtherExample;
 
   function ExternalFunc1
     input Real x;
     output Real y;
-    external "C"
-    y=ExternalFunc1_ext(x) annotation(Library="ExternalLib1",
-      Include="#include \"ExternalFunc1.h\"");
+  external "C"
+    y = ExternalFunc1_ext(x)
+      annotation(Library = "ExternalLib1",
+                 Include = "#include \"ExternalFunc1.h\"");
   end ExternalFunc1;
 
   function ExternalFunc2
     input Real x;
     output Real y;
-    external "C" annotation(Library="ExternalLib2",
-      Include="#include \"ExternalFunc2.h\"");
+  external "C"
+      annotation(Library = "ExternalLib2",
+                 Include = "#include \"ExternalFunc2.h\"");
   end ExternalFunc2;
 
   function ExternalFunc3
     input Real x;
     output Real y;
-    external "C" annotation(Include="#include \"ExternalFunc3.c\"");
+  external "C"
+      annotation(Include = "#include \"ExternalFunc3.c\"");
   end ExternalFunc3;
 end ExternalFunctions;
 
@@ -2371,7 +2380,8 @@ \subsubsection{Arbitrary Placement of Output Parameters, No External Function Va
   input Integer y;
   output Real u1;
   output Integer u2;
-  external "C" myfoo(x, u1, y, u2);
+external "C"
+  myfoo(x, u1, y, u2);
 end foo;
 \end{lstlisting}
 This corresponds to the following C prototype:
@@ -2400,7 +2410,8 @@ \subsubsection{External Function with Both Function Value and Output Variable}\l
   input Integer y;
   output Real funcvalue;
   output Integer out1;
-  external "C" funcvalue = myfoo(x, y, out1);
+external "C"
+  funcvalue = myfoo(x, y, out1);
 end foo;
 \end{lstlisting}
 This corresponds to the following C prototype:
@@ -2630,12 +2641,14 @@ \subsection{External Objects}\label{external-objects}
     input String fileName = "";
     input String tableName = "";
     output MyTable table;
-    external "C" table = initMyTable(fileName, tableName);
+  external "C"
+    table = initMyTable(fileName, tableName);
   end constructor;
 
   function destructor "Release storage of table"
     input MyTable table;
-    external "C" closeMyTable(table);
+  external "C"
+    closeMyTable(table);
   end destructor;
 end MyTable;
 \end{lstlisting}
@@ -2656,7 +2669,8 @@ \subsection{External Objects}\label{external-objects}
   input MyTable table;
   input Real u;
   output Real y;
-  external "C" y = interpolateMyTable(table, u);
+external "C"
+  y = interpolateMyTable(table, u);
 end interpolateTable;
 \end{lstlisting}
 The external C functions may be defined in the following way:

preamble.tex

@@ -302,6 +302,7 @@
         else,enum,extern,float,for,goto,if,int,long,register,return,%
         short,signed,sizeof,static,struct,switch,typedef,union,unsigned,%
         void,volatile,while},
+    % henrikt-ma: How about adding some highlighting of 'size_t' as a recognized name?
     sensitive,
     morecomment=[s]{/*}{*/},
     morecomment=[l]//, % nonstandard