This is the style guide for the Modelica Specification document.
The source format of the document is LaTeX, and the source is processed by both pdfLaTeX and LaTeXML. It is good to be aware of the LaTeXML implications, but for most contributors and contributions it is considered sufficient to only check that the pdfLaTeX output looks good, the idea being that potential problems should be spotted in the pull request review process.
The MSL-specific LaTeX macros and environments described in this style guide are defined in either of these two files:
- preamble.tex – Preamble contents for the main document.
- mlsshared.sty – Extracted parts of the styling to be shared with other documents that should follow the same style, such as many of the figures.
There shall be no trailing spaces, and each line (in particular, the last one in the file) shall be terminated by a newline.
There shall be no empty lines at the beginning or end of a file, and there shall never be more than two empty lines in a row.
Use one or two empty lines before sectioning commands such as \section or \subsubsection, except at the start of a file.
An empty line is recommended also after the non-paragraph sectioning commands.
Be careful about adding empty lines, as they actually are significant in places such as before list environments (itemize, etc).
For example, if the text before a list acts as an introduction, it should be kept tight with the list:
The following holds for slice operations:
\begin{itemize}
\item
…
The document is in ongoing transition to one sentence per line source code formatting. This means that any modified or new text should have each sentence alone on a single physical line in the source file.
When a sentence doesn't fit in one screen line, one may take that as a reminder that long sentences can reduce readability of the specification document, and consider breaking the long sentence into shorter ones. Just keep in mind that the purpose of doing this shall be to improve readability of the specification text, not improve readability of the one sentence per line formatted source code.
Once we have the physical line breaks in the correct places, the diffs of future changes will become clean and easy to grasp, and merge conflicts much more easily resolved.
When indenting the contents of a LaTeX environment, an indentation of 2 spaces is used.
It is recommended to not add indentation before \item:
\begin{itemize}
\item
First are all inputs to the original function, and after all them we will in order append one derivative for each input containing reals.
These common inputs must have the same name, type, and declaration order for the function and its derivative.
\item
The outputs are constructed by starting with an empty list and then in order appending one derivative for each output containing reals.
The outputs must have the same type and declaration order for the function and its derivative.
\end{itemize}
Many environments are used without indenting the contents, including nonnormative and example:
\begin{nonnormative}
This means that the most restrictive derivatives should be written first.
\end{nonnormative}
As a general rule, when a concept is directly related to a construct in the Modelica language with a certain name/keyword, then the language concept is referred to using a hyphenated combination of the language name/keyword in code style, with a qualifying natural language word written as normal text. Annotations are an exception to this rule. Examples:
| Appearance | LaTeX source | Comment |
|---|---|---|
connect-equation |
\lstinline!connect!-equation |
|
inverse annotation |
\lstinline!inverse! annotation |
|
if-equation |
\lstinline!if!-equation |
|
if-expression |
\lstinline!if!-expression |
|
when-clause |
\lstinline!when!-clause |
A branch of a when-equation or when-statement |
import-clause |
\lstinline!import!-clause |
|
for-equation |
\lstinline!for!-equation |
|
for-statement |
\lstinline!for!-statement |
|
for-loop |
\lstinline!for!-loop |
A for-equation or for-statement |
start-attribute |
\lstinline!start!-attribute |
Note that there's often an associated rule in the Modelica grammar, which should only be used in the text on the rare occasions when it is the actual grammar rule – not the entire language concept – that is being referenced:
| Appearance | LaTeX source |
|---|---|
if-equation |
\lstinline[language=grammar]!if-equation! |
Note: The hyphenation may sometimes appear grammatically incorrect, but the consistent use of hyphenation helps readability, and in some contexts the hyphen gives extra safety against reading the language name/keyword as part of the sentence structure. For example, compare:
- If equations are possible to simplify if their condition can be evaluated during translation.
if-equations are possible to simplify if their condition can be evaluated during translation.
Different constructs with expression and call:
| Appearance | LaTeX source | Comment |
|---|---|---|
if-expression |
\lstinline!if!-expression |
Generic language concept |
| parameter-expression | parameter-expression |
Expression with parameter variability |
Real expression |
\lstinline!Real! expression |
Expression of type Real |
| array expression | array expression |
Expression of array type |
| record expression | record expression |
Expression of record type |
y expression |
\lstinline!y! expression |
Expression for something named y |
convertElement call |
\lstinline!convertElement! call |
A call expression with callee convertElement |
In particular, avoid other combinations of inline code and expression than the variants above.
For other needs, try to find a formulation not based on expression to avoid misinterpretations according to the variants above.
For example, instead of saying "… can be dependent on class variables using the DynamicSelect expression", just say "… can be dependent on class variables using DynamicSelect".
Note: There is no need for hyphenation of "convertElement call" since we don't say "Real call" for a call expression of type Real (we have "Real expression" for this purpose).
When referencing a keyword itself, hyphenation is not used, and when possible, a better describing word than keyword is used:
| Appearance | LaTeX source | Comment |
|---|---|---|
the input prefix |
\lstinline!prefix! prefix |
For more prefixes, see class-prefixes, base-prefix, and type-prefix in the grammar. |
the final modifier |
the \lstinline!final! modifier |
|
the each keyword |
the \lstinline!each! keyword |
Depending on context, one can also swap the order, or drop the describing word completely:
| Appearance | LaTeX source |
|---|---|
the keyword each |
the keyword \lstinline!each! |
declared as final |
declared as \lstinline!final! |
When referencing a named function of operator, hyphenation is not used, and it is common to not combine with any describing word:
| Appearance | LaTeX source |
|---|---|
the smooth operator |
the \lstinline!smooth! operator |
where pre is not explicitly used |
where \lstinline!pre! is not explicitly used |
Incomplete list of various terminology with special formatting rules:
| Appearance | LaTeX source | Comment |
|---|---|---|
| start value | start value |
Value of the start-attribute (there could be exceptions!) |
| connection equation | connection equation |
Equation generated from analysis of connect-equations |
| reduction expression | reduction expression |
|
| base class | base class |
Similarly: derived class |
| base-clock | base-clock |
Similarly: sub-cock |
New terminology is either introduced with a definition environment, or as part of the running text.
When part of the running text, the introduced terminology should be marked with \firstuse at the point of the definition.
As a general rule, terminology introduced with \firstuse should appear in the document index, and by default the mandatory argument to \firstuse is automatically passed to \index.
To change the appearance of the index entry, the default may be overridden using an optional argument to \firstuse, for example, \firstuse[array!variable]{array variable}.
This is also useful when capitalization or plural/singular differs; except for things like names, lower case should be used in the index, and terms should typically appear in the singular, for example, \firstuse[vector]{Vectors}.
On rare occasions, one just wants the standardized typesetting of \firstuse but no entry in the index, which can be achieved by passing an em-dash for the optional argument, for example, \firstuse[---]{constant}.
When suppressing the appearnce in the index, it is recommended to add a comment in the source explaining why.
It is common that the use of \firstuse is directly followed by additional calls to \index for adding the terminology in more variants to the document index.
If the new terminology is used before being introduced, it should be marked with \willintroduce (instead of \firstuse) to alert the reader that this is not a term that is expected to be known yet by a first-time reader.
To put emphasis on a word or small piece of text, use \emph.
Italics is used via the semantic macros \firstuse and \willintroduce when new terminology is introduced in the running text instead of the bulkier definition environment.
Refrain from using non-semantical font switching commands for producing italics (\textit, \textsl, \itshape).
Note that the document is full of text set in italics, since this is used for both non-normative text and examples, through the nonnormative and example environments.
Non-semantical font switching commands for producing boldface (\textbf, \bfseries) may only be used for styling as part of higher level semantic constructs such as the amsthm.sty \newtheoremstyle definitions.
For purposes of marking emphasis, see use of \emph instead.
Ordinals are written with th in normal font, possibly combined with a math styled expression for the number:
Fixed ordinals: 1st, 2nd, 3rd.
Symbolic ordinals: $n$th, $(n+1)$th.
Inline code is typically formatted using just the \lstinline macro.
Since the change of type face can be very hard to notice for small code fragments, single quotes may sometimes be used to emphasize the distinction from the surrounding text, unless the code fragment consists of a single identifier (consistent presentation of identifiers is given higher priority than clarity of presentation in this case). For example:
… and prepending the reduction expression with ``\lstinline!functionName(!''.
Avoid overusing quotes around code fragments, especially for multi-letter fragments.
Modelica listings are written with indentation in steps of 2 spaces.
A space is typically added on each side of a binary operator, and after comma.
Code snippets may start with an indented line as long as there's some line in the listing with zero indentation, like this:
Real x(start = 1.0, fixed = true);
equation
der(x) = -x;
Each line should fit within the width of the page. Use hard line breaks and manual additional indentation of continued lines to meet this requirement. A semicolon in a matrix should either be followed by a line break or by a space.
Grammar listings use the language=grammar, and are written with indentation in steps of 3 spaces:
\begin{lstlisting}[language=grammar]
stored-definition :
[ within [ name ] ";" ]
{ [ final ] class-definition ";" }
\end{lstlisting}
When a grammar rule is mentioned in the text, the rule shall be formatted with the grammar language:
The node shall contain a \lstinline[language=grammar]!stored-definition! that…
This section gives guidelines for how the natural language text in English should be written.
The text is written in American English.
Avoid contractions such as isn't or won't; write is not or will/would not instead.
When a sentence starts with inline code,
import-clauses are not inherited.
this may be rewritten using The inserted before the inline code to avoid a lower case letter at the beginning of the sentence:
The
import-clauses are not inherited.
Always use comma (or colon if the following text starts on new line) after "e.g." and "i.e."; and use comma or some other punctuation such as "(", "--", or "." before them. This also avoids the need to guard the space after the dot.