Uri clarification (modelica#2531)

* Allow user defined fragments, and state that they may be renamed. Closes modelica#2445 * And follow URI-recommendation and use lower-case ("modelica://") Co-authored-by: Dietmar Winkler <dietmar.winkler@dwe.no>
otronarp · Mar 19, 2020 · 4179006 · 4179006
1 parent 27884f1
commit 4179006
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 7 deletions.
diff --git a/chapters/annotations.tex b/chapters/annotations.tex
@@ -55,16 +55,19 @@ \section{Annotations for Documentation}\doublelabel{annotations-for-documentatio
 \lstinline!<html>! and \lstinline!</html>! define
 optionally begin and end of content that is HTML encoded. For external
 links see \autoref{external-resources}. Links to Modelica classes may be defined with
-the HTML link command using scheme \lstinline!Modelica!, e.g.,
+the HTML link command using scheme \lstinline!Modelica!
+(using its lower case form in the URI, see \autoref{external-resources}), e.g.,
 \begin{lstlisting}[language=modelica]
-<a href="Modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
+<a href="modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
 \end{lstlisting}
 
 Together with scheme \lstinline!Modelica! the (URI) fragment specifiers
 \lstinline!#diagram!, \lstinline!#info!, \lstinline!#text!, \lstinline!#icon! may be used to reference different
-layers. Example:
+layers. User-defined fragment specifiers (anchors) may also be used, and they may be renamed
+when generating HTML (in particular to avoid collisions).
+Example:
 \begin{lstlisting}[language=modelica]
-<a href="Modelica://MultiBody.Joints.Revolute#info">Revolute</a>
+<a href="modelica://MultiBody.Joints.Revolute#info">Revolute</a>
 \end{lstlisting}
 \begin{lstlisting}[language=grammar]
 preferred-view-annotation:

diff --git a/chapters/packages.tex b/chapters/packages.tex
@@ -244,9 +244,9 @@ \subsection{External resources}\doublelabel{external-resources}
 links and images in html-text) and/or to reference images in the Bitmap
 annotation (see \autoref{bitmap}). URIs should be used, for example
 \filename{file:///} and the URI scheme \filename{modelica://} which can be used to retrieve
-resources associated with a package. {[}\emph{Note scheme names are
-case-insensitive, but the lower-case form should be used, that is} \filename{Modelica://} \emph{is allowed but} \filename{modelica://} \emph{is the
-recommended form.}{]}
+resources associated with a package. According to the URI specification scheme names are
+case-insensitive, but the lower-case form should be used, that is \filename{Modelica://} is allowed but \filename{modelica://} is the
+recommended form.
 
 The Modelica-scheme has the ability to reference a hierarchical
 structure of resources associated with packages. The same structure is