Generalize vendor-specific markup in figures

chapters/annotations.tex

@@ -343,7 +343,7 @@ \subsubsection{Plot Curves}\label{plot-curves}
 \subsubsection{Escape Sequences}\label{text-markup-escape-sequences}
 
 In an attribute inside a figure where the variable replacements of \cref{variable-replacements} or the text markup of \cref{text-markup-in-captions} can be used, the following use of \firstuse[text markup escape sequence]{text markup escape sequences}\index{escape sequence!text markup} applies.
-These escape sequences are applied after the application of other markup, and is not applied at all inside some of the other markup, see details for the respective markup.
+These escape sequences are applied after the application of other markup, and are not applied at all inside some of the other markup, see details for the respective markup.
 
 The percent character `\%' shall be encoded \lstinline!%%!.
 The following are all the recognized escape sequences:
@@ -363,6 +363,14 @@ \subsubsection{Escape Sequences}\label{text-markup-escape-sequences}
 With the percent character being encoded as \lstinline!%%!, the behavior of \lstinline!%! appearing in any other way than the escape sequences above, for variable replacement (\cref{variable-replacements}), or for the text markup (\cref{text-markup-in-captions}) is undefined, and thus possible to define in the future without breaking backward compatibility.
 \end{nonnormative}
 
+\subsubsection{Vendor-Specific Markup}\label{vendor-specific markup}
+
+\firstuse{Vendor-specific markup} takes the form \lstinline!__$\mathit{nameOfVendor}_{1}$($\mathit{data}_{1}$)$\ldots$__$\mathit{nameOfVendor}_{n}$($\mathit{data}_{n}$)!, where $n \geq 1$.
+It is only allowed as part of constructs described in \cref{variable-replacements} and \cref{text-markup-in-captions}, where it will be denoted by $\mathit{vendorSpecificMarkup}$.
+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 will always be able to safely ignore all vendor-specific markup.
+
 \subsubsection{Variable Replacements}\label{variable-replacements}
 
 In the places listed in \cref{attributes-with-variable-replacements} where text for display is defined, the final value of a result variable can be embedded by referring to the variable as \lstinline!%{inertia1.w}!.
@@ -404,6 +412,16 @@ \subsubsection{Variable Replacements}\label{variable-replacements}
 (Titles making use of \lstinline!%class! or \lstinline!%name! would then only lead to ugly duplication of this information.)
 \end{nonnormative}
 
+Vendor-specific markup can be added to a variable replacement in the form \lstinline!%$\mathit{vendorSpecificMarkup}${$\mathit{variable}$}!.
+The vendor-specific markup must not fundamentally alter the meaning of the variable replacement, in order to ensure that a tool can safely ignore all vendor-specific markup and still obtain a result that fits the current context.
+
+\begin{example}
+One application of vendor-specific markup for variable replacement is to prototype a feature that can later be turned into standardized format control.
+For example, the replaced variable may have an automatically inferred unit, but no \lstinline!displayUnit!-attribute.
+The tool vendor AVendor could then describe a selection of display unit with \lstinline!%__AVendor(?displayUnit=mm){integrator1.y}!.
+Later, if this would become supported by standard variable replacement, it might take the form of something like \lstinline!%{integrator1.y?displayUnit=mm}! instead.
+\end{example}
+
 \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!.
@@ -458,22 +476,29 @@ \subsubsection{Text Markup in Captions}\label{text-markup-in-captions}
 Once this becomes possible, the URI form of $\mathit{link}$ may be changed into a URI reference.
 \end{nonnormative}
 
+Vendor-specific markup can be added to a link in the form \lstinline!%[$\mathit{text}$]$\mathit{vendorSpecificMarkup}$($\mathit{link}$)!.
+The vendor-specific markup must not fundamentally alter the appearance of the link, in order to ensure that a tool can safefly ignore all vendor-specific markup and still obtain a result that fits the current context.
+
+\begin{example}
+The HTML \lstinline!<a>! tag has several attributes with potential application to links, such as \lstinline!target!.
+This attribute serves a natural purpose if the display of figures is integrated with the display of documentation.
+The tool vendor AVendor could map the HTML feature to Modelica in the form \lstinline!%__AVendor(?target=_blank)(modelica:/Modelica#info)!.
+\end{example}
+
 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}$.
+Vendor-specific markup for alternative content takes the form \lstinline!%$\mathit{vendorSpecificMarkup}$[$\mathit{text}$]!.
+The vendor-specific markup must not fundamentally alter the appearance of the $\mathit{text}$, in order to ensure that a tool can safefly ignore all vendor-specific markup and still obtain a result that fits the current context.
 
 \begin{example}
-One application of vendor-specific markup is to prototype a feature that can later be turned into standardized markup.
+One application of vendor-specific alternative content 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:!).
+In a similar way, vendor-specific alternative content 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}