preamble.tex

% This suppresses warnings about most overfull hboxes.
% Clearly it would be better to fix them, but if we anyway want to
% change the layout that can wait
\hfuzz=50pt

\usepackage[english]{babel}

\usepackage{fancyhdr}

% The general view was that parskip without indent was most readable, so use it
\usepackage{parskip}

% Uses some packages:
\usepackage{amsmath}
\allowdisplaybreaks

% For non-floating figures:
\usepackage{float}

% Prefer pdf for pdf
% https://tex.stackexchange.com/questions/1072/which-graphics-formats-can-be-included-in-documents-processed-by-latex-or-pdflat
\usepackage{ifpdf}
\ifpdf
\makeatletter
\let\orig@Gin@extensions\Gin@extensions
\def\Gin@extensions{.pdf,\orig@Gin@extensions} %prepend .pdf before .png
\makeatother
\fi

% Longer section numbers in toc
\ifpdf
\usepackage{tocloft}
\setlength{\cftsecnumwidth}{3em}
\fi

% Need more text:
\usepackage[margin=1in]{geometry}

%\usepackage{t1enc}
\usepackage{graphicx}
\graphicspath{{media/}{../media/}} % so that chapter files can also find the images

% Don't use subfig.sty due to this LaTeXML issue (fixed on master 2020-06-27):
% - https://github.com/brucemiller/LaTeXML/issues/1292 (marked as fixed as of commit 9f5c893b)
% Leaving commented-out code as a hint to anyone who considers using subfig.
%\usepackage{subfig}

\RequirePackage[margin=1em, labelfont=bf,
                singlelinecheck=true, font=sl,
                compatibility=false% Unsupported feature that suppresses the incompatibility checks.
                ]{caption}
\captionsetup[figure]{position=bottom}
\captionsetup[table]{position=top}
\ifpdf
\DeclareCaptionOption{parskip}[]{}% Unclear workaround for conflict between captions, subfig, and parskip.
\else
% The \DeclareCaptionOption leaves a ']' behind in the LaTeXML build, see:
% - https://github.com/brucemiller/LaTeXML/issues/1352
% Since we are currently not using subfig, we work around this issue by simply removing the problematic
% \DeclareCaptionOption call.
\fi

% The fixltx2e that was used for textsubscript is no longer needed for pdf, but is needed by latexml
\ifpdf
\else
\usepackage{fixltx2e} %for textsubscript
\fi

% Allow lot of figures on page:
\renewcommand{\textfraction}{0}
\renewcommand{\topfraction}{1}
\renewcommand{\bottomfraction}{1}

% Some problem with raggedright for latexml
\ifpdf
\renewcommand{\newline}{\hspace*{\fill}\linebreak}
\else
\renewcommand{\newline}{\hspace*{\fill}\raggedright\linebreak}
\fi
\setcounter{totalnumber}{1000}
\raggedbottom

% Load index before hyperref.
\ifpdf
\usepackage{index} % Not supported by LaTeXML.
\else
\usepackage{makeidx} % Poor man's alternative to index.sty.
\fi
\makeindex

% For solving issue with see-also entries in index, see
% - https://tex.stackexchange.com/questions/231840/what-is-the-proper-use-of-several-seealso-in-the-same-index-entry-with-makeinde
% For example, this is how to create a see-also item under "declaration equation":
%   \index{declaration equation!zzzzz@\igobble |seealso{binding equation}}
\def\igobble#1 {}

% Providing command that other authors seem to take for granted.
\newcommand*\seealso[2]{\emph{\alsoname} #1}

\ifpdf
\usepackage[pdfusetitle]{hyperref}
\else
\usepackage[pdfusetitle,backref=page]{hyperref} % Need backref, since we can't use biblatex.
\fi
\hypersetup{pdfkeywords={Modelica, modeling, object-oriented, multi-domain}}
% The bookmarks are used as table-of-contents in Acrobat
% The default (magenta for urls and red for internal links) isn't nice
\hypersetup{bookmarksnumbered=true, hidelinks, urlcolor=blue, linkcolor=blue}

% Commands for styling \index page references.
\newcommand{\hyperpageit}[1]{\textit{\hyperpage{#1}}}% Not the main entry for this index term.
\newcommand{\hyperpagebf}[1]{\textbf{\hyperpage{#1}}}% (Over?) emphasized entry for this index term.  Use with caution!

% Rudimentary fallback solution when \lstinline can't be used.  For example, in the argument of \index.
\newcommand{\robustinline}[1]{\texttt{#1}}

\ifpdf
\usepackage[
  style=authoryear,
  backref=true,
  maxnames=6
]{biblatex}
\setlength\bibitemsep{0.5\baselineskip}
\setlength\bibhang{0pt}
\else
% Use BibTeX due to LaTeXML problems with biblatex.
\usepackage[round,authoryear]{natbib}
\bibliographystyle{plainnat}
% Define macro aliases with the names used by bibliatex:
\let\textcite\citet
\let\parencite\citep
\fi

\usepackage{multirow} % for multirow entries in tables

% When producing PDF, the ttfamily looks better in size \small, but with LaTeXML this becomes too small,
% and the size is applied deep down on the HTML elements, making it hard to adjust using CSS.
% Thus, the problem has to be addressed already when a listings language's 'basicstyle' is defined.
% This needs to go before mlsshared.sty is loaded.
\ifpdf
\let\smallifpdf\small
\else
\let\smallifpdf\normalsize
\fi

\ifpdf
% Don't load cleveref yet.
\else
% The LaTeXML 'listings' support in cleveref is broken (fixed on master 2020-12-29), so we need to load cleveref before
% listings (which is loaded inside mlsshared.sty), so that the broken support doesn't get loaded, see
% - https://github.com/brucemiller/LaTeXML/issues/1400 (marked as fixed as of commit 4c3d0018ec)
\usepackage[nameinlink,noabbrev]{cleveref}
\fi

% There seems to be some major issue with using this as a package in LaTeXML messing up font in listing
% See https://github.com/brucemiller/LaTeXML/issues/1713
\ifpdf
\usepackage{mlsshared}
\else
\include{mlsshared.sty}
\fi

\ifpdf
% This is the preferred load order for listings and cleveref, so that cleveref is aware of listings, see above.
\usepackage[nameinlink,noabbrev]{cleveref}
\fi

\def\autoref#1{\errmessage{You are not supposed to use \autoref; use \cref or \Cref instead.}}

% Settings in addition to those in mlsshared.sty.
\lstset{%
  xleftmargin=\fboxsep,
  xrightmargin=-\fboxsep,
}

% Convenience for adding a term to the index, formatted with \robustinline.
\newcommand{\indexinline}[1]{\index{#1@\robustinline{#1}}}

% Similar to \indexinline, but specifically for adding annotation to the index.
% This makes it easy to change the presentation of annotations in the index.
\newcommand{\annotationindex}[1]{\index{#1@\robustinline{#1}}}
% Like \annotationindex, but also outputting the formatted name of the annotation.
\newcommand{\fmtannotationindex}[1]{\lstinline{#1}\annotationindex{#1}}

\def\S0#1#2{\hypertarget{#2}\chapter{#1}\label{#2}}
\def\S1#1#2{\hypertarget{#2}\section{#1}\label{#2}}
\def\S2#1#2{\hypertarget{#2}\subsection{#1}\label{#2}}
\def\S3#1#2{\hypertarget{#2}\subsubsection{#1}\label{#2}}
\def\S4#1#2{\hypertarget{#2}\paragraph{#1}\label{#2}}
\def\S5#1#2{\hypertarget{#2}\subparagraph{#1}\label{#2}}

% Simple numbering of lists, should preferably use \usepackage{enumitem}
% https://stackoverflow.com/questions/2007627/latex-how-can-i-create-nested-lists-which-look-this-1-1-1-1-1-1-1-2-1-2
%\usepackage{enumitem} % Package not available for continuous integration builds.
\renewcommand{\labelenumi}{\arabic{enumi}.}
\renewcommand{\labelenumii}{\labelenumi\arabic{enumii}.}
\renewcommand{\labelenumiii}{\labelenumii\arabic{enumiii}.}
\renewcommand{\labelenumiv}{\labelenumiii\arabic{enumiv}.}

% Non-normative content without paragraph breaks at beginning and end.
% In most cases, one should use the 'nonnormative' environment instead.
\newenvironment{nonnormative*}[0]{%
{[}\itshape\ignorespaces
}{%
\unskip\upshape{]}%
}

% Non-normative content with paragraph breaks at beginning and end.
\newenvironment{nonnormative}[0]{%
\par\begin{nonnormative*}%
}{%
\end{nonnormative*}\par%
}

% Example environment, as a special case of non-normative content.
\newenvironment{example*}[1][\unskip]{%
\begin{nonnormative*}Example #1:
}{%
\end{nonnormative*}
}
\newenvironment{example}[1][\unskip]{%
\begin{nonnormative}Example #1:
}{%
\end{nonnormative}
}

% Like \emph, but marking this as the place where new terminology is introduced.
% By default, the argument is added to the document index as is, but this can be overridden using the optional argument.
\makeatletter% As long as this file isn't a normal package included with \usepackage...
\newcommand{\firstuse}[2][\@nil]{%
  \emph{#2}%
  \def\tmp{#1}%
  \def\skipindex{---}% Special string for saying "don't add to index"
  \ifx\tmp\@nnil
    % Default case: Use mandatory argument also for document index.
    \index{#2}%
  \else
    \ifx\tmp\skipindex
      % Don't add anything to document index; \firstuse is only used for purposes of typesetting.
    \else
      % Add custom entry to document index.
      \index{#1}%
    \fi%
  \fi%
}
\makeatother% As long as this file isn't a normal package included with \usepackage...

% Like \firstuse, but when speaking of a term that hasn't been introduced.
% Produces same appearance as \firstuse, but doesn't add anything to the index.
\newcommand{\willintroduce}[1]{\firstuse[---]{#1}}

% Formatting of table headings.
\newcommand{\tablehead}[1]{\textit{#1}}

% Environment for definitions.
\usepackage{amsthm}
\newtheoremstyle{mlsdefinition}
  {\topsep}   % ABOVESPACE
  {\topsep}   % BELOWSPACE
  {}          % BODYFONT
  {}          % INDENT (empty value is the same as 0pt)
  {\bfseries} % HEADFONT
  {.}         % HEADPUNCT
  {.75em}     % HEADSPACE
  {#1~#2. \firstuse[---]{#3}}        % CUSTOM-HEAD-SPEC
\theoremstyle{mlsdefinition}
% In order to show where the definition ends, we put a \qed at the end.  This can't be done using \newtheoremstyle,
% so instead we make the 'definition' environment a wrapper around the amsthm-base environment.
\makeatletter
\newtheorem{definition@inner}{Definition}[chapter]
\crefname{definition@inner}{definition}{definitions}
\Crefname{definition@inner}{Definition}{Definitions}
\newenvironment{definition}{\begin{definition@inner}}{\qed\end{definition@inner}}
\makeatother

\setcounter{secnumdepth}{5}
% Note: Toc changed for appendex
\setcounter{tocdepth}{1}

% Warning: The way of adding \label inside the theoremstyle below is currently working at LaTeXML version 0.8.4,
% but was broken for a while on their master branch, see
% - https://github.com/brucemiller/LaTeXML/issues/1351
% TODO: Remove this comment once it has been verified that this is working once we have upgraded from 0.8.4.
\newtheoremstyle{modelicadefinition}
  {\topsep}   % ABOVESPACE
  {\topsep}   % BELOWSPACE
  {}          % BODYFONT
  {}          % INDENT (empty value is the same as 0pt)
  {\bfseries} % HEADFONT
  {\\}        % HEADPUNCT
  {.75em}     % HEADSPACE
  {#1~#2 \texttt{#3}\label{modelica:#3}\index{#3@\robustinline{#3}}} % CUSTOM-HEAD-SPEC {#1~#2. \texttt{#3}}
\theoremstyle{modelicadefinition}
\newtheorem{operatordefinition}{Operator}[chapter]
\crefname{operatordefinition}{operator}{operators}
\Crefname{operatordefinition}{Operator}{Operators}
\newtheorem{functiondefinition}{Function}[chapter]
\crefname{functiondefinition}{function}{functions}
\Crefname{functiondefinition}{Function}{Functions}
\newtheorem{annotationdefinition}{Annotation}[chapter]
\crefname{annotationdefinition}{annotation}{annotations}
\Crefname{annotationdefinition}{Annotation}{Annotations}

\newtheoremstyle{modelicadefinition*}
  {\topsep}   % ABOVESPACE
  {\topsep}   % BELOWSPACE
  {}          % BODYFONT
  {}          % INDENT (empty value is the same as 0pt)
  {\bfseries} % HEADFONT
  {\\}        % HEADPUNCT
  {.75em}     % HEADSPACE
  {#1~#2 \texttt{#3}} % CUSTOM-HEAD-SPEC {#1~#2. \texttt{#3}}
\theoremstyle{modelicadefinition*}
\newtheorem{operatordefinition*}[operatordefinition]{Operator} % Note: Not using \theoremstyle*, only difference is not adding \label.
\crefname{operatordefinition*}{operator}{operators}
\Crefname{operatordefinition*}{Operator}{Operators}
\newtheorem{functiondefinition*}[functiondefinition]{Function}
\crefname{functiondefinition*}{function}{functions}
\Crefname{functiondefinition*}{Function}{Functions}
\newtheorem{annotationdefinition*}{Annotation}[chapter]
\crefname{annotationdefinition*}{annotation}{annotations}
\Crefname{annotationdefinition*}{Annotation}{Annotations}

\lstdefinelanguage[synopsis]{modelica}[]{modelica}{% Language for use inside the 'synopsis' environment.
  basicstyle=\upshape\ttfamily,              % Same size as \lstinline
  frame=none,
  aboveskip=0pt,
  xleftmargin=2em
}

\lstdefinelanguage[synopsis]{grammar}[]{grammar}{% Language for use inside the 'synopsis[grammar]' environment.
  basicstyle=\upshape\ttfamily,              % Same size as \lstinline
  frame=none,
  aboveskip=0pt,
  xleftmargin=2em
}

\lstdefinelanguage[synopsis]{C}[]{C}{% Language for use inside the 'synopsis[C]' environment.
  basicstyle=\upshape\ttfamily,              % Same size as \lstinline
  frame=none,
  aboveskip=0pt,
  xleftmargin=2em
}

\newenvironment{synopsis}[1][modelica]{%
\lstset{language=[synopsis]#1}%
~\vspace{-\parskip}\par
}{%
}
\newenvironment{semantics}{%
\list{}{%
\setlength{\leftmargin}{1.5em}%
\setlength{\rightmargin}{1.5em}%
}\item[]%
}{%
\endlist
}

% Change all \cref and \Cref variants below chapter to use "section"
\crefname{subsection}{section}{sections}
\Crefname{subsection}{Section}{Sections}
\crefname{subsubsection}{section}{sections}
\Crefname{subsubsection}{Section}{Sections}
\crefname{paragraph}{section}{sections}
\Crefname{paragraph}{Section}{Sections}
\crefname{subparagraph}{section}{sections}
\Crefname{subparagraph}{Section}{Sections}

% We can't use cleveref.sty the way we want for equations until this LaTeXML has been fixed:
% - https://github.com/brucemiller/LaTeXML/issues/1306 -- fixed on 'master'
% In the meantime, we use \eqref to achieve the same result.
%\crefname{equation}{}{}
%\Crefname{equation}{}{}

\ifpdf
\newcommand{\crefnameref}[1]{\cref{#1}~\emph{\nameref*{#1}}}
\newcommand{\Crefnameref}[1]{\Cref{#1}~\emph{\nameref*{#1}}}
\else
% Don't use \nameref* while waiting for LaTeXML issue to get fixed:
% - https://github.com/brucemiller/LaTeXML/issues/1348 -- fixed on 'master'
% At the same time, there are also problems with the normal \nameref:
% - https://github.com/brucemiller/LaTeXML/issues/1350 -- fixed on 'master'
% Since the excessive output of \nameref only replaces the need for \cref for some labels,
% we can't rely on just \nameref, meaning we can't use it at all.
\let\crefnameref\cref
\let\Crefnameref\Cref
\fi

% Make all description lists break the line after each key.
% henrikt-ma: Commenting out use of the enumitem package, see above.
%\setlist[description]{
%  style=nextline,
%  labelwidth=0pt,
%  leftmargin=15pt,
%  itemindent=\dimexpr-5pt-\labelsep\relax,
%}

\newenvironment{contributors}{%
\list{}{%
\setlength{\leftmargin}{1.5em}%
\setlength{\itemsep}{-\parskip}%
\addtolength{\itemsep}{2pt}%
}%
}{%
\endlist
}