Initial draft for plot axis scale

chapters/annotations.tex

@@ -158,6 +158,7 @@ \subsubsection{Axis Properties}\label{axis-properties}
   Real max "Axis upper bound, in 'unit'";
   String unit = "" "Unit of axis tick labels";
   String label "Axis label";
+  AxisScale scale = Linear() "Mapping between axis values and position on axis"
 end Axis;
 \end{lstlisting}
 
@@ -180,6 +181,63 @@ \subsubsection{Axis Properties}\label{axis-properties}
 Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!label!.
 The Modelica tool is responsible for showing the unit used for values at the axis tick marks, so the axis \lstinline!label! shall not contain the unit.
 
+The type of \lstinline!scale! is defined as an empty partial record:
+\begin{lstlisting}[language=modelica]
+partial record AxisScale
+end AxisScale;
+\end{lstlisting}%
+\annotationindex{AxisScale}
+
+The standardized annotations extending from \lstinline!AxisScale! are \lstinline!Linear! and  \lstinline!Log!, but it is also allowed to use a vendor-specific annotation.
+
+Use \lstinline!Linear! for a linear mapping between axis values and position on axis:
+\begin{lstlisting}[language=modelica]
+record Linear
+  extends AxisScale;
+end Linear;
+\end{lstlisting}%
+\index{Linear@\robustinline{Linear} (axis scale)}
+
+Use \lstinline!Log! for a logarithmic mapping between axis values and position on axis:
+\begin{lstlisting}[language=modelica]
+record Log
+  extends AxisScale;
+  Integer base(min = 2) = 10;
+end Log;
+\end{lstlisting}%
+\index{Log@\robustinline{Log} (axis scale)}
+
+The \lstinline!base! of a \lstinline!Log! scale determines preferred positions of major axis ticks.
+It is not required that the presentation of axis tick labels reflect the \lstinline!base! setting.
+For example, when \lstinline!base! is 10, major axis ticks should preferrably be placed at integer powers of 10, and natural alternatives that a tool may use for major axis tick labels could look like $0.001$ or $10^{-3}$.
+Under some circumstances, such as when the axis range does not span even a single order of magnitude, a tool may disregard the preference in order to get useful axis ticks.
+
+Use \lstinline!dB! for a decibel axis:
+\begin{lstlisting}[language=modelica]
+record dB
+  extends AxisScale;
+  Integer order(min = 1);
+end dB;
+\end{lstlisting}%
+\index{dB@\robustinline{dB} (decibel axis scale)}
+
+The mandatory \lstinline!order! is used to define a tick label conversion according to $y \mapsto \frac{\operatorname{log}_{10}(y)}{\text{\lstinline!order!}}$.
+This mapping shall be applied before presenting values in tick labels.
+It is recommended that value of \lstinline!order! is somehow indicated on the axis or its tick labels, for example by presenting a major tick label as $8\, \mathrm{dB}_{20}$.
+Major axis ticks are preferred at integer converted values, and minor ticks should be placed at evenly distributed converted values (similar to a linear axis scale).
+
+\begin{example}
+A \emph{symmetric log} axis scale is sometimes used for axes spanning across several order of magnitudes of both positive and negative values.
+Details vary, but the mapping from value to linear position along axis is some variation of $y \mapsto \operatorname{sign}(y)\, \operatorname{log}(1 + \frac{\abs{y}}{10^{\alpha}})$.
+A tool may implement this as a vendor-specific axis scale:
+\begin{lstlisting}[language=modelica]
+Axis(
+  min = -1e5, max = 1e5,
+  scale = __NameOfVendor_symlog(3),
+)
+\end{lstlisting}
+\end{example}
+
 \subsubsection{Plot Curves}\label{plot-curves}
 
 The actual data to plot is specified in the \lstinline!curves!\annotationindex{Curve} of a \lstinline!Plot!: