Skip to content

Commit

Permalink
Merge pull request modelica#2681 from HansOlsson/ImproveFormatting
Browse files Browse the repository at this point in the history 
Improve formatting
  • Loading branch information
@HansOlsson
HansOlsson committed Oct 12, 2020
2 parents d3aadcc + ae4484e commit de55f8b
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 49 deletions.
92 changes: 51 additions & 41 deletions chapters/annotations.tex
View file
Expand Up @@ -43,7 +43,8 @@ \section{Annotations for Documentation}\label{annotations-for-documentation}

\begin{lstlisting}[language=grammar]
documentation-annotation:
annotation "(" Documentation "(" "info" "=" STRING ["," "revisions" "=" STRING ] ")" ")"
annotation "(" Documentation "(" "info" "=" STRING
["," "revisions" "=" STRING ] ")" ")"
\end{lstlisting}
The \lstinline!Documentation! annotation can contain the \lstinline!info! annotation
giving a textual description, the \lstinline!revisions! annotation giving a list
Expand Down Expand Up @@ -107,13 +108,13 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation}
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline[language=grammar]!"Evaluate"! & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
\lstinline[language=grammar]!"HideResult"! & Don't show component's simulator result & \Cref{modelica:HideResult}\\
\lstinline[language=grammar]!"Inline"! & Inline function & \Cref{modelica:Inline}\\
\lstinline[language=grammar]!"LateInline"! & Inline after all symbolic transformations & \Cref{modelica:LateInline}\\
\lstinline[language=grammar]!"InlineAfterIndexReduction"! & Inline after index reduction & \Cref{modelica:InlineAfterIndexReduction}\\
\lstinline[language=grammar]!"GenerateEvents"! & Generate events for zero crossings in function & \Cref{modelica:GenerateEvents}\\
\lstinline[language=grammar]!"smoothOrder"! & Function smoothness guarantee & \Cref{modelica:smoothOrder}\\
\lstinline!Evaluate! & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\
\lstinline!Inline! & Inline function & \Cref{modelica:Inline}\\
\lstinline!LateInline! & Inline after all symbolic transformations & \Cref{modelica:LateInline}\\
\lstinline!InlineAfterIndexReduction! & Inline after index reduction & \Cref{modelica:InlineAfterIndexReduction}\\
\lstinline!GenerateEvents! & Generate events for zero crossings in function & \Cref{modelica:GenerateEvents}\\
\lstinline!smoothOrder! & Function smoothness guarantee & \Cref{modelica:smoothOrder}\\
\hline
\end{tabular}
\end{center}
Expand Down Expand Up @@ -224,8 +225,9 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation}

\begin{annotationdefinition}[smoothOrder]
\begin{synopsis}[grammar]\begin{lstlisting}
smoothOrder "=" UNSIGNED-NUMBER ")"
smoothOrder "(" normallyConstant "=" IDENT [ "," normallyConstant "=" IDENT ] ")" "=" UNSIGNED-NUMBER ")"
"smoothOrder" "=" UNSIGNED-NUMBER ")"
"smoothOrder" "(" "normallyConstant" "=" IDENT
{ "," "normallyConstant" "=" IDENT } ")" "=" UNSIGNED-NUMBER ")"
\end{lstlisting}\end{synopsis}
\begin{semantics}
This annotation has only an effect within a function declaration.
Expand Down Expand Up @@ -253,10 +255,10 @@ \section{Annotations for Simulation Experiments}\label{annotations-for-simulatio
{"," experimentOption}] ")" ] ")"

experimentOption:
StartTime "=" [ "+" | "-" ] UNSIGNED-NUMBER |
StopTime "=" [ "+" | "-"] UNSIGNED-NUMBER |
Interval "=" UNSIGNED-NUMBER |
Tolerance "=" UNSIGNED-NUMBER
"StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER |
"StopTime" "=" [ "+" | "-"] UNSIGNED-NUMBER |
"Interval" "=" UNSIGNED-NUMBER |
"Tolerance" "=" UNSIGNED-NUMBER
\end{lstlisting}

The experiment annotation defines the default start time (StartTime) in
Expand Down Expand Up @@ -1162,11 +1164,12 @@ \section{Annotations for the Graphical User Interface}\label{annotations-for-the

A component declaration or a short replaceable class definition may have the following annotation:
\begin{lstlisting}[language=modelica]
annotation(Dialog(enable = true, tab = "General",
annotation(Dialog(enable = true,
tab = "General",
group = "",
showStartAttribute = false,
colorSelector = false,
groupImage="modelica://MyPackage/Resources/Images/switch.png",
groupImage="modelica://MyPackage/Resources/Images/load.png",
connectorSizing = false));
\end{lstlisting}
For a short replaceable class definition only the fields \lstinline!tab!, \lstinline!group!, \lstinline!enable! and
Expand Down Expand Up @@ -1418,14 +1421,14 @@ \subsection{Version Numbering}\label{version-numbering}
Version numbers are of the forms:
\begin{itemize}
\item
Main release versions: """ \lstinline!UNSIGNED-INTEGER! \{ "." \lstinline!UNSIGNED-INTEGER! \} """\\
Example: "2.1"
Main release versions: \lstinline[language=grammar]!""" UNSIGNED-INTEGER { "." UNSIGNED-INTEGER } """!\\
Example: \lstinline!"2.1"!
\item
Pre-release versions: """ \lstinline!UNSIGNED-INTEGER! \{ "." \lstinline!UNSIGNED-INTEGER! \} " " \{\lstinline!S-CHAR!\} """\\
Example: "2.1 Beta 1"
Pre-release versions: \lstinline[language=grammar]!""" UNSIGNED-INTEGER { "." UNSIGNED-INTEGER } " " {S-CHAR} """!\\
Example: \lstinline!"2.1 Beta 1"!
\item
Un-ordered versions: """ \lstinline!NON-DIGIT! \{\lstinline!S-CHAR!\} """\\
Example: "Test 1"
Un-ordered versions: \lstinline[language=grammar]!""" NON-DIGIT {S-CHAR} """!\\
Example: \lstinline!"Test 1"!
\end{itemize}

The main release versions are ordered using the hierarchical numerical
Expand Down Expand Up @@ -1504,8 +1507,9 @@ \subsection{Version Handling}\label{version-handling}

\subsubsection{Conversion rules}\label{conversion-rules}

% Using mbox to avoid having line starting with ","
There are a number of functions: \lstinline!convertClass!, \lstinline!convertClassIf!,
\lstinline!convertElement!, \lstinline!convertModifiers!, \lstinline!convertMessage! defined as follows. The
\lstinline!convertElement!, \mbox{\lstinline!convertModifiers!,} \lstinline!convertMessage! defined as follows. The
calls of these functions do not directly convert, instead they define
conversion rules as below. The order between the function calls does not
matter, instead the longer paths (in terms number of hierarchical names)
Expand Down Expand Up @@ -1606,7 +1610,8 @@ \subsubsection{Conversion rules}\label{conversion-rules}
\begin{lstlisting}[language=modelica]
convertModifiers("OldClass",
{"OldModifier1=default1", "OldModifier2=default2", ...},
{"NewModifier1=...%OldModifier2%...", "NewModifier2=...", ...} [, simplify=true] )
{"NewModifier1=...%OldModifier2%...", "NewModifier2=...", ...}
[, simplify=true] )
\end{lstlisting}

Normal case; if any modifier among \lstinline!OldModifier! exist then replace all of
Expand Down Expand Up @@ -1672,33 +1677,37 @@ \subsubsection{Conversion rules}\label{conversion-rules}
The conversion
\begin{lstlisting}[language=modelica]
convertClass("Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe",
"Modelica.Thermal.FluidHeatFlow.Components.Pipe")
"Modelica.Thermal.FluidHeatFlow.Components.Pipe")
convertModifiers({"Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe"},
fill("",0), {"useHeatPort=false"})
fill("",0), {"useHeatPort=false"})

convertClass("Modelica.StateGraph.Temporary.NumericValue",
"Modelica.Blocks.Interaction.Show.RealValue")
"Modelica.Blocks.Interaction.Show.RealValue")
convertModifiers("Modelica.StateGraph.Temporary.NumericValue",
{"Value"}, {"number=%Value%"})
{"Value"}, {"number=%Value%"})
convertModifiers("Modelica.StateGraph.Temporary.NumericValue",
{"hideConnector"}, {"use_numberPort=not %hideConnector%"})
{"hideConnector"}, {"use_numberPort=not %hideConnector%"})

convertModifiers("Modelica.Blocks.Math.LinearDependency",
{"y0=0", "k1=0", "k2=0"}, {"y0=%y0%", "k1=%y0%*%k1%", "k2=%y0%*%k2%"}, true)
convertClass("Modelica.Electrical.Machines.BasicMachines.QuasiStationaryDCMachines",
"Modelica.Electrical.Machines.BasicMachines.QuasiStaticDCMachines")
convertElement({"Modelica.Electrical.Machines.Interfaces.PartialBasicDCMachine"},
{"y0=0", "k1=0", "k2=0"}, {"y0=%y0%", "k1=%y0%*%k1%", "k2=%y0%*%k2%"},
true)
convertClass(
"Modelica.Electrical.Machines.BasicMachines.QuasiStationaryDCMachines",
"Modelica.Electrical.Machines.BasicMachines.QuasiStaticDCMachines")
convertElement("Modelica.Electrical.Machines.Interfaces.PartialBasicDCMachine",
"quasiStationary", "quasiStatic")
convertElement("Modelica.Electrical.Machines.BasicMachines.QuasiStationaryDCMachines.DC_ElectricalExcited",
"quasiStationary", "quasiStatic")
\end{lstlisting}
converts
\begin{lstlisting}[language=modelica]
Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe pipe1;
Modelica.StateGraph.Temporary.NumericValue tempValue(Value=10, hideConnector=true);
Modelica.StateGraph.Temporary.NumericValue tempValue(Value=10,
hideConnector=true);
Modelica.Blocks.Math.LinearDependency linearDep(y0=2, k2=1);
model A
extends Modelica.Electrical.Machines.BasicMachines.QuasiStationaryDCMachines.DC_ElectricalExcited;
import Modelica.Electrical.Machines.BasicMachines;
extends BasicMachines.QuasiStationaryDCMachines.DC_ElectricalExcited;
end A;
model B
extends A;
Expand All @@ -1711,7 +1720,8 @@ \subsubsection{Conversion rules}\label{conversion-rules}
Modelica.Blocks.Interaction.Show.RealValue(number=10, use_numberPort=not true);
Modelica.Blocks.Math.LinearDependency linearDep(y0=2, k1=0, k2=2);
model A
extends Modelica.Electrical.Machines.BasicMachines.QuasiStaticDCMachines.DC_ElectricalExcited;
import Modelica.Electrical.Machines.BasicMachines;
extends BasicMachines.QuasiStaticDCMachines.DC_ElectricalExcited;
end A;
model B
extends A;
Expand Down Expand Up @@ -1773,12 +1783,12 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
\begin{lstlisting}[language=modelica]
String versionDate "UTC date of first version build (in format: YYYY-MM-DD)";
Integer versionBuild "Larger number is a more recent maintenance update";
String dateModified "UTC date and time of the latest change to the package in the
following format (with one space between date and time):
YYYY-MM-DD hh:mm:ssZ";
String dateModified "UTC date and time of the latest change to the package
in the following format (with one space between date
and time): YYYY-MM-DD hh:mm:ssZ";
String revisionId "Revision identifier of the version management system used
to manage this library. It marks the latest submitted change to
any file belonging to the package";
to manage this library. It marks the latest submitted
change to any file belonging to the package";
\end{lstlisting}

\begin{example}
Expand Down
6 changes: 4 additions & 2 deletions chapters/functions.tex
View file
Expand Up @@ -2243,13 +2243,15 @@ \subsection{Annotations for External Libraries and Include Files}\label{annotati
input Real x;
output Real y;
external "C"
y=ExternalFunc1_ext(x) annotation(Library="ExternalLib1",Include="#include \"ExternalFunc1.h\"");
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
Expand Down
13 changes: 7 additions & 6 deletions chapters/syntax.tex
View file
Expand Up @@ -18,19 +18,20 @@ \section{Lexical conventions}\label{lexical-conventions}
NONDIGIT = "_" | letters "a" to "z" | letters "A" to "Z"
STRING = """ { S-CHAR | S-ESCAPE } """
S-CHAR = see below
Q-CHAR = NONDIGIT | DIGIT | "!" | "#" | "$" | "%" | "&" | "(" | ")" | "*" | "+" | "," |
"-" | "." | "/" | ":" | ";" | "<" | ">" | "=" | "?" | "@" | "[" | "]" | "^" |
"{" | "}" | "|" | "~" | " " | """
Q-CHAR = NONDIGIT | DIGIT | "!" | "#" | "$" | "%" | "&" | "(" | ")"
| "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | ">" | "="
| "?" | "@" | "[" | "]" | "^" | "{" | "}" | "|" | "~" | " " | """
S-ESCAPE = "\'" | "\"" | "\?" | "\\" |
"\a" | "\b" | "\f" | "\n" | "\r" | "\t" | "\v"
DIGIT = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
UNSIGNED-INTEGER = DIGIT { DIGIT }
UNSIGNED-REAL = UNSIGNED-INTEGER "." [ UNSIGNED-INTEGER ]
| UNSIGNED_INTEGER [ "." [ UNSIGNED_INTEGER ] ] ( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER
| "." UNSIGNED-INTEGER [ ( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER ]
| UNSIGNED_INTEGER [ "." [ UNSIGNED_INTEGER ] ]
( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER
| "." UNSIGNED-INTEGER [ ( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER ]
\end{lstlisting}
\textrm{S-CHAR} is any member of the Unicode character set
(\url{http://www.unicode.org}; see \cref{mapping-package-class-structures-to-a-hierarchical-file-system} for storing as UTF-8 on files) except double-quote """, and backslash "\textbackslash{}"
(\url{http://www.unicode.org}; see \cref{mapping-package-class-structures-to-a-hierarchical-file-system} for storing as UTF-8 on files) except double-quote `"', and backslash `\textbackslash{}'.

For identifiers the redundant escapes (`\lstinline!\?!' and `\lstinline!\"!') are the same as the corresponding non-escaped
variants (`\lstinline!?!' and '\lstinline!"!'). The single quotes are part of an identifier. E.g.\ \lstinline!'x'! and
Expand Down

0 comments on commit de55f8b

Please sign in to comment.