From 8d2f2e74d022052074e1384403b57c8ff0b81278 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 16 Oct 2020 14:29:22 +0200 Subject: [PATCH] Improving specification of escape sequences --- chapters/annotations.tex | 72 +++++++++++++++++++++++++++++----------- 1 file changed, 53 insertions(+), 19 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index f37ce9902..f3ab1b196 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -207,6 +207,27 @@ \subsubsection{Plot Curves}\label{plot-curves} Variable replacements, as described in \cref{variable-replacements}, can be used in the \lstinline!legend! of \lstinline!Curve! +\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 sequences} 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. + +The percent character `\%' shall be encoded \lstinline!%%!. The following are all the recognized escape sequences: +\begin{center} +\begin{tabular}{c c l} +\hline +\tablehead{Sequence} & \tablehead{Encoded character} & \tablehead{Comment}\\ +\hline +\hline +\lstinline!%%! & `\%' & Only way to encode character. \\ +\lstinline!%]! & `]' & Escape sequence only needed in link text. \\ +\hline +\end{tabular} +\end{center} + +\begin{nonnormative} +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 link markup (\cref{text-markup-in-captions}) is undefined, and thus possible to define in the future without breaking backward compatibility. +\end{nonnormative} + \subsubsection{Variable Replacements}\label{variable-replacements} In most places where text for display is defined the final value of a result @@ -214,6 +235,16 @@ \subsubsection{Variable Replacements}\label{variable-replacements} \lstinline!%{inertia1.w}!. This is similar to the \lstinline!Text! graphical primitive in \cref{text}. +In \lstinline!%{$\mathit{variable}$}!, text markup escape sequences don't apply inside the $\mathit{variable}$, which has the form of \lstinline[language=grammar]!component-reference! in the grammar (\cref{expressions1}). This means that a complete \lstinline[language=grammar]!component-reference! shall be scanned before looking for the terminating closing brace. + +\begin{example} +The variable replacement \lstinline!%{'%%'}! references the variable \lstinline!'%%'!, not the variable \lstinline!'%'!. +\end{example} + +\begin{example} +The variable replacement \lstinline!%{foo . '}bar{'}! makes a valid reference to the variable\linebreak[4] \lstinline!foo.'}bar{'!. +\end{example} + \begin{table}[H] \caption{Attributes that can use variable replacements.} \begin{center} @@ -235,32 +266,35 @@ \subsubsection{Variable Replacements}\label{variable-replacements} parameters and constants, so that values to be shown in a caption can be determined during simulation. -The percent character is encoded \lstinline!%%!. 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.) +\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.) +\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!. +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!%[]()!, where the -\lstinline![]! part is optional. The \lstinline!! can be in either -of the following forms: +Links take the form \lstinline!%[$\mathit{text}$]($\mathit{link}$)!, where the \lstinline![$\mathit{text}$]! part is optional. Text markup escape sequences don't apply inside the $\mathit{link}$, which can be in either of the following forms: \begin{itemize} -\item A URI, such as -\lstinline!https://github.com/modelica/ModelicaSpecification! or -\lstinline!modelica://Modelica.Blocks!. -\item A \lstinline!variable:!, where \lstinline!! is a component -reference such as \lstinline!inertia1.w!. -\item A \lstinline!plot:!, where \lstinline!! is the identifier of a -\lstinline!Plot! in the current \lstinline!Figure!. +% Use very short Modelica URI combined with carefull chosen wording below to deal with difficult line breaking. +\item A URI. Well established schemes such as \lstinline[language={[nocomment]modelica}]!https://github.com/modelica/ModelicaSpecification! or \lstinline[language={[nocomment]modelica}]!modelica://Modelica!, as well as lesser known schemes may be used. (A tool that has no special recognition of a scheme can try sending the URI to the operating system for interpretation.) +\item A \lstinline!variable:$\mathit{id}$!, where $\mathit{id}$ is a component reference in the form of \lstinline[language=grammar]!component-reference! in the grammar, such as \lstinline!inertia1.w!. +\item A \lstinline!plot:$\mathit{id}$!, where $\mathit{id}$ is the identifier of a \lstinline!Plot! in the current \lstinline!Figure!. \end{itemize} -When \lstinline![]! is omitted, a Modelica tool is free to derive a default based on -the \lstinline!!. +When \lstinline![$\mathit{text}$]! is omitted, a Modelica tool is free to derive a default based on the $\mathit{link}$. + +\begin{nonnormative} +Note that for the character `]' to appear in $\mathit{text}$, it needs to be encoded as the escape sequence \lstinline!%]!, or it would be interpreted as the terminating delimiter of the \lstinline![$\mathit{text}$]!. + +Similarly, the closing parenthesis `)' must be handled with care in $\mathit{link}$ in order to not be interpreted as the terminating delimiter of the \lstinline!($\mathit{link}$)!. +\begin{itemize} +\item For a URI, a closing parenthesis must be URL encoded in order to not be interpreted as the end of the \lstinline!($\mathit{link}$)!. For example, the URL in \lstinline[language={[nocomment]modelica}]!%(http://bad.org/(tryme))! is just \filename{http://bad.org/(tryme}, and the entire link is followed by a stray closing parenthesis. To make it work, one has to use URL encoding: \lstinline[language={[nocomment]modelica}]!%(http://bad.org/%28tryme%29)! (using URL encoding of the opening parenthesis just for symmetry, and note that the \lstinline!%! of the percent-encoded sequences are not subject to text markup escape sequences). +\item For a \lstinline!variable:!, no special treatment is needed, as the component reference syntax of the \lstinline!! allows parentheses to appear without risk of misinterpretation inside a quoted identifier. For example, \lstinline"%(variable:'try)me!')" has a parenthesis in \lstinline"'try)me!'" that must not be mistaken for the end of the \lstinline!($\mathit{link}$)!. +% The following shortcoming is planned to be addressed by applying URI interpretation of the 'plot:' form. +\item For a \lstinline!plot:!, there is currently no way to reference a plot with `)' in its \lstinline!identifier!. +\end{itemize} +\end{nonnormative} The styling of the link text, as well as the link action, is left for each Modelica tool to decide.