Give precedence to special interpretation of 'variable:' and 'plot:' …

…in links

This is needed as the special forms typically take the shape of (often relative) URIs.

chapters/annotations.tex

@@ -270,12 +270,13 @@ \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.
 
-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:
+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}
-% 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!.
+% The 'plt:id' form below should be deprecated in favor of using an improved form of Modelica URI in the future, making 'variable:id' the only non-URI.
 \item A \lstinline!plot:$\mathit{id}$!, where $\mathit{id}$ 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.)
 \end{itemize}
 
 When \lstinline![$\mathit{text}$]! is omitted, a Modelica tool is free to derive a default based on the $\mathit{link}$.
@@ -285,10 +286,10 @@ \subsubsection{Text Markup in Captions}\label{text-markup-in-captions}
 
 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!<id>! 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!.
+\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).
 \end{itemize}
 \end{nonnormative}