From 395c4f96f072211303a1842e43913f7ef1a155f9 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Thu, 4 Mar 2021 23:56:28 +0100 Subject: [PATCH] Add more rules to style guide --- styleguide.md | 100 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 82 insertions(+), 18 deletions(-) diff --git a/styleguide.md b/styleguide.md index ff7de5a05..c021d662e 100644 --- a/styleguide.md +++ b/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