Skip to content

Commit

Permalink
Clean up use of quote symbols (#2508)
Browse files Browse the repository at this point in the history
This fixes most of #2364 (carefully avoiding wording that would trigger GitHub action).

Summary of what this PR aims to cover:
- No upright quotes should appear outside of code snippets (`lstlisting` and `lstinline`).
- No quotes around inline code.
- Use `\lstinline` instead of quotes for inline code.
- Use `\emph` when there is a need to remind that something has a special meaning in the context of the specification (when the thing was introduced, it should have been marked with `\firstuse`, see below).
- Titles of publications, chapters, and sections in `\emph` instead of quotes.
- Use matching pairs of double quotes (“conceptual”) when using a word or phrase that is intentionally vague, lacking proper definition, or otherwise calls for the reader's imagination. 
- Single quotes around single special characters where needed to get more clear separation from surrounding text.  Example (somewhat damaged by GitHub's font):
  > …there is an operator ‘`0`’ defining the zero-value
- Filenames in `\filename` (pretty big risk of not having found all occurrences).
- Use of `\firstuse` instead of `\emph` when a term is introduced (pretty big risk of not having found all occurrences).
- Use of the `example` and `nonnormative` environments whenever possible with at most minimal changes to content, in order to avoid misuse of interleaved fragments in `\emph`, making the source code maintainable, avoiding lots of tiny errors in the markup, and correcting many places where formatting was missing between the `\emph` fragments.

Parts of #2364 not covered by this PR:
- Proper handling of references.
- Cleanup inside non-normative text that couldn't be converted to use the `nonnormative` environment due to not being a stand alone sequence of paragraphs.  This requires #2368.

Minor changes:
* Clean up use of ``...''
* Clean up related to " being used outside of code snippets
* Use \filename to markup some filenames
* Get rid of some meaningless uses of \textbf
* Improve markup in simple cases of non-normative text and examples
* More cleanup, with special attention to single quotes
* Typesetting \filename with \textsf instead of \textit
* Remove forgotten \emph inside nonnormative
* Say 'stronger requirement than being balanced'
* Remove LaTeX source comment replaced by #2510
* Don't write math-like equation as Modelica source listing
* Use \emph instead of \lstinline for 'platform' in context of LibraryDirectory
* Wrap 'enabled' in \emph instead of \lstinline
* Add double quotes around fragment of inline code when explaining multiple iterators
* Use '\textgreater{} 2' instead of '$> 2$'
* Write ="Hz" inside \lstinline instead of just 'Hz'
* Write \lstinline!unit="s"! instead of 'unit \emph{s}'
* Fix quoting of opening parenthesis character
* Use \filename instead of \lstinline for some modelica URIs
* Fix encoding of backslashes inside \filename
* Fix matching of single quotes
* Say \lstinline!'+'! instead of just \lstinline!+! when speaking of operator overloading
* Say 'positive edge of' instead of 'when ... becomes ...'
* Wrap content of \filename in \mbox to prevent hyphenation from injecting hyphens

Co-authored-by: HansOlsson <hans.olsson@3ds.com>
  • Loading branch information
henrikt-ma and HansOlsson committed Mar 13, 2020
1 parent 5efb1dd commit 82f050f
Show file tree
Hide file tree
Showing 26 changed files with 2,012 additions and 2,095 deletions.
399 changes: 208 additions & 191 deletions chapters/annotations.tex

Large diffs are not rendered by default.

330 changes: 155 additions & 175 deletions chapters/arrays.tex

Large diffs are not rendered by default.

327 changes: 155 additions & 172 deletions chapters/classes.tex

Large diffs are not rendered by default.

288 changes: 131 additions & 157 deletions chapters/connectors.tex

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion chapters/dae.tex
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ \chapter{Modelica DAE Representation}\doublelabel{modelica-dae-representation}
(e.g. for ideal diodes, Coulomb friction elements) and specialized
algorithms have to be used to solve them.

Due to the construction of the equations by "flattening" a Modelica
Due to the construction of the equations by \emph{flattening} a Modelica
model, the hybrid DAE (\ref{eq:hydrid-dae}) contains a huge number of sparse equations.
Therefore, direct simulation of (\ref{eq:hydrid-dae}) requires sparse matrix methods.
However, solving this initial set of equations directly with a numerical
Expand Down
8 changes: 4 additions & 4 deletions chapters/derivationofstream.tex
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ \subsection{Connection of 2 stream connectors, one to one connections (N=2):}\do
In this case, \lstinline!inStream()! is continuous (contrary to $h_{mix}$) and does not
depend on flow rates. The latter result means that this transformation
may remove nonlinear systems of equations, which requires that either
simplifications of the form ``a*b/a = b'' must be provided, or that this
simplifications of the form $a * b / a = b$ must be provided, or that this
case is treated directly.

\subsection{Connection of 3 stream connectors where one mass flow rate is identical to zero (N=3 and $\dot{m}_3=0$):}\doublelabel{connection-of-3-stream-connectors-where-one-mass-flow-rate-is-identical-to-zero-n-3-and}
Expand Down Expand Up @@ -210,7 +210,7 @@ \subsection{Connection of 3 stream connectors where two mass flow rates are posi

If uni-directional flow is present and an ideal splitter is modelled,
the required flow direction should be defined in the connector instance
with the ``\lstinline!min!'' attribute (the ``\lstinline!max!'' attribute could be also defined,
with the \lstinline!min! attribute (the \lstinline!max! attribute could be also defined,
however it does not lead to simplifications):

\begin{lstlisting}[language=modelica]
Expand Down Expand Up @@ -256,10 +256,10 @@ \subsection{Connection of 3 stream connectors where two mass flow rates are posi
that a solution fulfills the balance equations. Additionally, a
recommendation is given to compute all unknowns in a unique way, by
providing an explicit formula for the \lstinline!inStream! operator. Due to the
definition, that only flows where the corresponding ``min'' attribute is
definition, that only flows where the corresponding \lstinline!min! attribute is
neither zero nor positive enter this formula, a meaningful physcial
result is always obtained, even in case of zero mass flow rate. As a
side effect, non-linear equation systems are automatically removed in
special cases, like sensors or uni-directional flow, without any
symbolic transformations (no equation must be analyzed; only the
``\lstinline!min!''-attributes of the corresponding flow variables).
\lstinline!min! attributes of the corresponding flow variables).

0 comments on commit 82f050f

Please sign in to comment.