Add more rules to style guide

styleguide.md

@@ -15,7 +15,8 @@ The document is in ongoing transition to _one sentence per line_ source code for
 This means that any modified or new text should have each sentence alone on a single physical line in the source file.
 Once we have the physical line breaks in the correct places, the diffs of future changes will become clean and easy to grasp.
 
-When indenting the contents of a LaTeX environment, an indentation of 2 spaces used.  It is recommended to not add indentation before `\item`:
+When indenting the contents of a LaTeX environment, an indentation of 2 spaces used.
+It is recommended to not add indentation before `\item`:
 ```
 \begin{itemize}
 \item
@@ -34,37 +35,100 @@ This means that the most restrictive derivatives should be written first.
 \end{nonnormative}
 ```
 
-## Special terminology
+## Formatting of language terminology
 
-**TODO**: Sort out the following situation, reported in https://github.com/modelica/ModelicaSpecification/issues/2713:
+### Things with name/keyword in the language
 
-Space | Hyphen | Inline code | Both
---- | --- | --- | ---
-connect equation (9) | connect-equation (32) | `connect` equation (5) | `connect`-equation (2)
-when clause (5) | when-clause (86) | `when` clause (0) | `when`-clause (11)
-if equation (0) | if-equation (8) | `if` equation (0) | `if`-equation (0)
-start value (24) | start-value (15) | `start` value (5) | `start`-value (2)
+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.
+Examples:
 
+Appearance | LaTeX source
+--- | ---
+`connect`-equation | `\lstinline!connect!-equation`
+`if`-equation | `\lstinline!if!-equation`
+`if`-expression | `\lstinline!if!-expression`
+`when`-clause | `\lstinline!when!-clause`
+`start`-attribute | `\lstinline!start!-attribute`
 
-## Miscellaneous
+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:
 
-### Ordinals
+Appearance | LaTeX source
+--- | ---
+`if-equation` | `\lstinline[language=grammar]!if-equation!`
 
-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.
-```
+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.
+
+### The keywords themselves
+
+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!`
+
+### Named functions and operators
+
+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`
+
+### Other things, special cases
+
+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!)
+base class | `base class` | Similarly: derived class
+base-clock | `base-clock` | Similarly: sub-cock
+
+## Definitions
+
+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.
+(The use of `\firstuse` helps us both produce consistent formatting and keep track of things that should appear in the document index.)
+
+If the new terminology is used before being introduced, the first use should be marked with `\willintroduce` to alert the reader that this is not a term that is expected to be known yet by a first-time reader.
+
+## Miscellaneous
 
 ### Use of `\emph` and italics
 
-**TODO**
+To put emphasis on a word or small piece of text, use `\emph`.
+
+Italics is used when new terminology is introduced in the running text instead of the bulkier `definition` environment, see `\firstuse` and `\willintroduce`.
 
+Non-semantical font switching commands for producing italics (`\textit`, `\textsl`, `\itshape`) should pretty much never be used.
+
+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.
 
 ### Use of boldface
 
-**TODO**
+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
 
+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.
+```
 
 ## Code listings