Shorten identifier for two reasons #3685
Conversation
- It is too long - It causes problem for HTML it seems Closes modelica#3663
There was a problem hiding this comment.
Looks alright, but we should wait until #3661 is merged to avoid conflicts.
For the record, this was verified in #3661 and the LaTeXML issue has been reported here: |
chapters/functions.tex
Outdated
| {\lstinline!annotation(IncludeDirectory="modelica:/PackageName/Resources/Include")!}\annotationindex{IncludeDirectory}, used to specify a location for header files. | ||
| The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the include directory, see \cref{external-resources}. |
There was a problem hiding this comment.
I realize that something important is being lost regarding the default; it needs to be clear that the default is the name of the current library's top-level package. PackageName isn't making this clear, and the explanation a few paragraphs below the item list is too hard to find.
Something like the following would preserve the meaning and still drastically shorten the \lstinline arguments:
| {\lstinline!annotation(IncludeDirectory="modelica:/PackageName/Resources/Include")!}\annotationindex{IncludeDirectory}, used to specify a location for header files. | |
| The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the include directory, see \cref{external-resources}. | |
| The {\lstinline!annotation(IncludeDirectory="$\mathit{uri}$")!}\annotationindex{IncludeDirectory}, used to specify a URI location (\cref{external-resources}) for header files. | |
| The default location -- not requiring an annotation -- is \filename{modelica:/$L$/Resources/Include}, see below. |
(The use of L for the top-level package name really helps getting nice line breaks in the PDF.)
There was a problem hiding this comment.
There is an explanation for PackageName (changed from the previous name in this PR) after the list.
Obviously we can improve that, but to me that would be a separate PR, as this was just intended to have shorter names to fix two issues.
chapters/functions.tex
Outdated
| @@ -2252,11 +2252,11 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l | |||
| \end{nonnormative} | |||
| \item | |||
| The | |||
There was a problem hiding this comment.
Added back on the correct line in the suggestion below:
| The |
| @@ -2293,7 +2293,7 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l | |||
| The directories may use symbolic links or use a text-file as described below: e.g., a text-file \filename{vs2008} containing the text \emph{../win32/vs2005} (or \emph{vs2005}) suggesting that it is compatible with vs2005. | |||
| \end{nonnormative} | |||
|
|
|||
| The {\lstinline!ModelicaLibraryName!} used for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!} indicates the top-level class where the annotation is found in the Modelica source code. | |||
| The {\lstinline!PackageName!} used for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!} indicates the top-level class where the annotation is found in the Modelica source code. | |||
There was a problem hiding this comment.
To go with suggestion above:
| The {\lstinline!PackageName!} used for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!} indicates the top-level class where the annotation is found in the Modelica source code. | |
| In the default locations for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!}, the $L$ indicates the top-level class where the annotation is found in the Modelica source code. |
There was a problem hiding this comment.
As indicated I think that's a separate PR.
There was a problem hiding this comment.
The reason why I don't think it should be a separate PR is that while this PR is currently reduces very long lines – which looks nice – it is making it harder to see that the default location is tied to the top-level package. This paragraph is too far away from where it applies to cover up for the less informative PackageName compared to the old ModelicaLibraryName.
I also needed to verify that the shorter text fixes the issue in this case, so I had to wait for the CI. (and, yes, it did) |
|
As indicated I think this is good enough on its own to correct the HTML-bug and be more readable, and any improvement in formulations should be a separate PR. |
|
I suggest we wrap up #3661 first, and then return to this PR as a change which is unrelated to working around the LaTeXML bug. |
The reasons are:
Closes #3663