Skip to content

Commit

Permalink
Sentence-based line breaks for Figure-annotation
Browse files Browse the repository at this point in the history
  • Loading branch information
@henrikt-ma
henrikt-ma committed Sep 22, 2023
1 parent 07bdf70 commit ae12c4a
Showing 1 changed file with 45 additions and 61 deletions.
106 changes: 45 additions & 61 deletions chapters/annotations.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,15 +99,12 @@ \subsection{Figures}\label{annotations-for-figures}\label{figures}

A \lstinline!Plot! can contain several \lstinline!curves!, see \cref{plot-curves}, that all share a common \lstinline!x! and \lstinline!y! axis with properties described in \cref{axis-properties}.

Both \lstinline!Figure! and \lstinline!Plot! can have an optional title. When
the \lstinline!Figure! \lstinline!title! is the empty string (the default), the
tool must produce a non-empty title based on the figure content. On the other
hand, the \lstinline!Plot! \lstinline!title! has a tool-dependent default, but
the default may be the empty string. When the \lstinline!Plot! \lstinline!title! is the empty string, no
title should be shown. The plot title is not to be confused with the plot
\emph{label} which is never empty, see below. Variable replacements, as
described in \cref{variable-replacements}, can be used in the
\lstinline!title! of \lstinline!Figure! and \lstinline!Plot!.
Both \lstinline!Figure! and \lstinline!Plot! can have an optional title.
When the \lstinline!Figure! \lstinline!title! is the empty string (the default), the tool must produce a non-empty title based on the figure content.
On the other hand, the \lstinline!Plot! \lstinline!title! has a tool-dependent default, but the default may be the empty string.
When the \lstinline!Plot! \lstinline!title! is the empty string, no title should be shown.
The plot title is not to be confused with the plot \emph{label} which is never empty, see below.
Variable replacements, as described in \cref{variable-replacements}, can be used in the \lstinline!title! of \lstinline!Figure! and \lstinline!Plot!.

The \lstinline!identifier! in \lstinline!Figure! and \lstinline!Plot! is a \lstinline!String! identifier, and is intended to identify the \lstinline!Figure! and \lstinline!Plot! for programmatic access.
The \lstinline!figures! annotation is inherited in the sense that each class has a collection of figures comprised by the contents of the \lstinline!figures! annotation in the class itself, as well as the \lstinline!figures! annotations from any base classes.
Expand All @@ -117,37 +114,25 @@ \subsection{Figures}\label{annotations-for-figures}\label{figures}
If an \lstinline!identifier! is an empty string it cannot be used for programmatic access and is exempt from the uniqueness requirements.

\begin{nonnormative}
For \lstinline!Figure!, this makes it possible to reference the plot from a
tool-specific scripting environment. For \lstinline!Plot!, this makes it
possible to reference the plot in the figure caption, which becomes useful when
the \lstinline!Figure! contains more than one \lstinline!Plot!.
For \lstinline!Figure!, this makes it possible to reference the plot from a tool-specific scripting environment.
For \lstinline!Plot!, this makes it possible to reference the plot in the figure caption, which becomes useful when the \lstinline!Figure! contains more than one \lstinline!Plot!.
\end{nonnormative}

% henrikt-ma 2020-06: Once there is Modelica URI support for referring to a figure in the collection of a class, it will be easier to explain
% the following statement.
Even though a \lstinline!Figure! annotation can be shared through inheritance between classes in a class hierarchy, note that each simulated class provides
its own data to be displayed in the figure.

Every \lstinline!Plot! has an automatically generated \emph{label} which is
required to be shown as soon as at least one \lstinline!Plot! in the
\lstinline!Figure! has an \lstinline!identifier!. A tool is free to choose both
labeling scheme (such as \emph{a}, \emph{b}, \dots, or \emph{i}, \emph{ii}, \dots), placement in the plot,
and styling in the plot itself as well as in other contexts.

When a \lstinline!Figure! defines a non-empty \lstinline!group!, it is used to
organize figures similar to how \lstinline!group! is used in the
\lstinline!Dialog! annotation (see \cref{annotations-for-the-graphical-user-interface}). However, leaving \lstinline!group! at
the default of an empty string does not mean that a group will be created
automatically, but that the figure resides outside of any group. The
\lstinline!group! is both the key used for grouping, and the name of the group
for display purposes.

The \lstinline!preferred! attribute of \lstinline!Figure! indicates whether the figure should be given preference when automatically determining which figures to show,
and a class may define any number of \lstinline!preferred! figures. For example, a tool might choose to automatically show all preferred figures when the class is simulated.

The \lstinline!caption! attribute of \lstinline!Figure! can use the restricted
form of text markup described in \cref{text-markup-in-captions} as well as
the variable replacements described in \cref{variable-replacements}.
Even though a \lstinline!Figure! annotation can be shared through inheritance between classes in a class hierarchy, note that each simulated class provides its own data to be displayed in the figure.

Every \lstinline!Plot! has an automatically generated \emph{label} which is required to be shown as soon as at least one \lstinline!Plot! in the \lstinline!Figure! has an \lstinline!identifier!.
A tool is free to choose both labeling scheme (such as \emph{a}, \emph{b}, \dots, or \emph{i}, \emph{ii}, \dots), placement in the plot, and styling in the plot itself as well as in other contexts.

When a \lstinline!Figure! defines a non-empty \lstinline!group!, it is used to organize figures similar to how \lstinline!group! is used in the \lstinline!Dialog! annotation (see \cref{annotations-for-the-graphical-user-interface}).
However, leaving \lstinline!group! at the default of an empty string does not mean that a group will be created automatically, but that the figure resides outside of any group.
The \lstinline!group! is both the key used for grouping, and the name of the group for display purposes.

The \lstinline!preferred! attribute of \lstinline!Figure! indicates whether the figure should be given preference when automatically determining which figures to show, and a class may define any number of \lstinline!preferred! figures.
For example, a tool might choose to automatically show all preferred figures when the class is simulated.

The \lstinline!caption! attribute of \lstinline!Figure! can use the restricted form of text markup described in \cref{text-markup-in-captions} as well as the variable replacements described in \cref{variable-replacements}.

\subsubsection{Axis Properties}\label{axis-properties}

Expand All @@ -171,8 +156,7 @@ \subsubsection{Axis Properties}\label{axis-properties}
The Modelica tool is responsible for showing that values at the axis tick marks are expressed in \lstinline!unit!, so the axis \lstinline!label! shall not contain this information.

\begin{nonnormative}
When \lstinline!unit! is empty, and axis bounds are to be determined automatically, a natural choice of unit could be the variable's \lstinline!displayUnit!. When axis bounds are specified by the
user, on the other hand, a tool may choose a unit for the variable such that the range of the variable values (expressed in the chosen unit) fit nicely with the range of the unitless axis.
When \lstinline!unit! is empty, and axis bounds are to be determined automatically, a natural choice of unit could be the variable's \lstinline!displayUnit!. When axis bounds are specified by the user, on the other hand, a tool may choose a unit for the variable such that the range of the variable values (expressed in the chosen unit) fit nicely with the range of the unitless axis.
\end{nonnormative}

If a tool does not recognize the \lstinline!unit!, it is recommended to issue a warning and treat the \lstinline!unit! as if it was empty, as well as ignore any setting for \lstinline!min! and \lstinline!max!.
Expand Down Expand Up @@ -308,19 +292,20 @@ \subsubsection{Variable Replacements}\label{variable-replacements}
The variable replacement \lstinline!%{foo . '}bar{'}! makes a valid reference to the variable\linebreak[4] \lstinline!foo.'}bar{'!.
\end{example}

Note that expansion to the final value means that expansion is not restricted to
parameters and constants, so that values to be shown in a caption can be
determined during simulation.
Note that expansion to the final value means that expansion is not restricted to parameters and constants, so that values to be shown in a caption can be determined during simulation.

\begin{nonnormative}
By design, neither \lstinline!%class! nor \lstinline!%name! is supported in this context, as this information is expected to already be easily accessible (when applicable) in tool-specific ways. (Titles making use of \lstinline!%class! or \lstinline!%name! would then only lead to ugly duplication of this information.)
By design, neither \lstinline!%class! nor \lstinline!%name! is supported in this context, as this information is expected to already be easily accessible (when applicable) in tool-specific ways.
(Titles making use of \lstinline!%class! or \lstinline!%name! would then only lead to ugly duplication of this information.)
\end{nonnormative}

\subsubsection{Text Markup in Captions}\label{text-markup-in-captions}

In addition to variable replacements, a very restricted form of text markup is used for the \lstinline!caption!. Note that the text markup escape sequences described in \cref{text-markup-escape-sequences} generally apply inside \lstinline!caption!, with one exception given below for links.
In addition to variable replacements, a very restricted form of text markup is used for the \lstinline!caption!.
Note that the text markup escape sequences described in \cref{text-markup-escape-sequences} generally apply inside \lstinline!caption!, with one exception given below for links.

Links take the form \lstinline!%[$\mathit{text}$]($\mathit{link}$)!, where the \lstinline![$\mathit{text}$]! part is optional, and text markup escape sequences don't apply inside the $\mathit{link}$. The $\mathit{link}$ can be in either of the following forms, where the interpretation is given by the first matching form:
Links take the form \lstinline!%[$\mathit{text}$]($\mathit{link}$)!, where the \lstinline![$\mathit{text}$]! part is optional, and text markup escape sequences don't apply inside the $\mathit{link}$.
The $\mathit{link}$ can be in either of the following forms, where the interpretation is given by the first matching form:
\begin{itemize}
\item
A \lstinline!variable:$\mathit{id}$!, where $\mathit{id}$ is a component reference in the form of \lstinline[language=grammar]!result-reference! in the grammar, such as \lstinline!inertia1.w!.
Expand Down Expand Up @@ -354,38 +339,37 @@ \subsubsection{Text Markup in Captions}\label{text-markup-in-captions}
\end{itemize}
\end{nonnormative}

The styling of the link text, as well as the link action, is left for each Modelica
tool to decide.
The styling of the link text, as well as the link action, is left for each Modelica tool to decide.

\begin{nonnormative}
For example, \lstinline!%(inertia1.w)! could be displayed as the text
\lstinline!inertia1.w! formatted with upright monospaced font, and have a pop-up
menu attached with menu items for plotting the variable, setting its start
value, or investigating the equation system from which it is solved. On the
other hand, \lstinline!%[angular velocity](inertia1.w)! could be formatted in
the same style as the surrounding text, except some non-intrusive visual clue
about it being linked.
For example, \lstinline!%(inertia1.w)! could be displayed as the text \lstinline!inertia1.w! formatted with upright monospaced font, and have a pop-up menu attached with menu items for plotting the variable, setting its start value, or investigating the equation system from which it is solved.
On the other hand, \lstinline!%[angular velocity](inertia1.w)! could be formatted in the same style as the surrounding text, except some non-intrusive visual clue about it being linked.
\end{nonnormative}

\begin{nonnormative}
% This non-normative text explains why we don't want to assume that the 'link' must have a scheme.
Note that $\mathit{link}$ is currently not allowed to be a \emph{URI reference}, i.e., a URI or a \emph{relative reference} such as \lstinline!#foo!. This is due to to the current inability to define a base URI referencing the current figure. Once this becomes possible, the URI form of $\mathit{link}$ may be changed into a URI reference.
Note that $\mathit{link}$ is currently not allowed to be a \emph{URI reference}, i.e., a URI or a \emph{relative reference} such as \lstinline!#foo!.
This is due to to the current inability to define a base URI referencing the current figure.
Once this becomes possible, the URI form of $\mathit{link}$ may be changed into a URI reference.
\end{nonnormative}

A sequence of one or more newlines (encoded either literally or using the \lstinline!\n!
escape sequence) means a paragraph break. (A line break within a paragraph is
not supported, and any paragraph break before the first paragraph or after the last
paragraph has no impact.)
A sequence of one or more newlines (encoded either literally or using the \lstinline!\n! escape sequence) means a paragraph break.
(A line break within a paragraph is not supported, and any paragraph break before the first paragraph or after the last paragraph has no impact.)

\firstuse[vendor-specific markup]{Vendor-specific markup} takes the form \lstinline!%__$\mathit{nameOfVendor}_{1}$($\mathit{data}_{1}$)$\ldots$__$\mathit{nameOfVendor}_{n}$($\mathit{data}_{n}$)[$\mathit{text}$]!, where $n \geq 1$.
The $\mathit{nameOfVendor}$ consists of only digits and letters, and shall only convey the name of the vendor defining the meaning of the associated $\mathit{data}$.
Text markup escape sequences don't apply inside the $\mathit{data}$, implying that it cannot contain the closing parenthesis, `)'.
A tool which does not understand any of the vendor-specific meanings shall only display the mandatory $\mathit{text}$, but the $\mathit{text}$ may also be used together with the vendor-specific $\mathit{data}$.

\begin{example}
One application of vendor-specific markup is to prototype a feature that can later be turned into standardized markup. For example, say that the tool AVendor wants to generalize the variable replacements such that the duration of a simulation can be substituted into a caption. During the development, this could be represented as the vendor-specific markup \lstinline!%__AVendor(?duration)[10 s]!, if the simulation has a duration of 10~seconds at the time of writing the caption. When AVendor renders this, it ignores the text \lstinline!10 s! and just displays the actual duration instead. Later, if this would become supported by standard markup, it might take the form of something like \lstinline!%{experiment:duration}! instead (note that \lstinline!experiment:duration! is not in the form of a component reference, avoiding conflict with current use of variable replacements).

In a similar way, vendor-specific markup can be used to prototype a link for future inclusion in the link markup (either by extending the meaning of Modelica URIs, or by introducing another pseudo-scheme similar to \lstinline!variable:!). This is an example where the vendor-specific markup could make use of the $\mathit{text}$ (for link text) together with the vendor-specific $\mathit{data}$ (describing the actual link).
One application of vendor-specific markup is to prototype a feature that can later be turned into standardized markup.
For example, say that the tool AVendor wants to generalize the variable replacements such that the duration of a simulation can be substituted into a caption.
During the development, this could be represented as the vendor-specific markup \lstinline!%__AVendor(?duration)[10 s]!, if the simulation has a duration of 10~seconds at the time of writing the caption.
When AVendor renders this, it ignores the text \lstinline!10 s! and just displays the actual duration instead.
Later, if this would become supported by standard markup, it might take the form of something like \lstinline!%{experiment:duration}! instead (note that \lstinline!experiment:duration! is not in the form of a component reference, avoiding conflict with current use of variable replacements).

In a similar way, vendor-specific markup can be used to prototype a link for future inclusion in the link markup (either by extending the meaning of Modelica URIs, or by introducing another pseudo-scheme similar to \lstinline!variable:!).
This is an example where the vendor-specific markup could make use of the $\mathit{text}$ (for link text) together with the vendor-specific $\mathit{data}$ (describing the actual link).
\end{example}

\section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{symbolic-processing}
Expand Down

0 comments on commit ae12c4a

Please sign in to comment.