Use more overview tables for annotations #3628
Conversation
|
I can understand that this helps, but my concern with adding such tables is that it is a form of duplicated information, which adds a maintenance burden. |
Co-authored-by: Hans Olsson <[email protected]>
Co-authored-by: Hans Olsson <[email protected]>
Yes, it is a bit of maintenance burden, but at least to me the burden is easily motivated by the tremendous help it provides me when navigating the document. |
|
Language group: looks good, avoids having annotations at different levels in toc. |
| When creating a component of the given class, and the annotation is specified it gives the recommended component name. | ||
| \end{lstlisting}\end{synopsis} | ||
| \begin{semantics} | ||
| \lstinline!defaultComponentName! is a class annotation giving the recommended component name to use when creating a component of the class. |
There was a problem hiding this comment.
| \lstinline!defaultComponentName! is a class annotation giving the recommended component name to use when creating a component of the class. | |
| The \lstinline!defaultComponentName! is a class annotation giving the recommended component name to use when creating a component of the class. |
Avoid starting a sentence with a lower-case letter.
There was a problem hiding this comment.
There are numerous examples of starting sentences like this with a lower case initial in inline code, so I don't think we should start using another style here.
There was a problem hiding this comment.
Well, there are 109 lines starting with The \lstinline and 124 lines starting with \lstinline, many of which don't start sentences - perhaps half are actual sentences), so I wouldn't say it is a new style - just one that hasn't been followed that well.
There was a problem hiding this comment.
Well, 109 lines starting with The \lstinline, 28 A \lstinline and 4 An \lstinline
And there are only 76 lines starting with \lstinline followed by a lower-case letter - many of them not being real sentences, but just items in a list.
| When creating a component, it is recommended to generate a declaration of the form | ||
| \end{lstlisting}\end{synopsis} | ||
| \begin{semantics} | ||
| \lstinline!defaultComponentPrefixes! is a class annotation giving a whitespace separated list of recommended type prefixes to include in the \lstinline[language=grammar]!type-prefix! part of a \lstinline[language=grammar]!component-clause1! generated when creating a component of the class: |
There was a problem hiding this comment.
| \lstinline!defaultComponentPrefixes! is a class annotation giving a whitespace separated list of recommended type prefixes to include in the \lstinline[language=grammar]!type-prefix! part of a \lstinline[language=grammar]!component-clause1! generated when creating a component of the class: | |
| The \lstinline!defaultComponentPrefixes! is a class annotation giving a whitespace separated list of recommended type prefixes to include in the \lstinline[language=grammar]!type-prefix! part of a \lstinline[language=grammar]!component-clause1! generated when creating a component of the class: |
There was a problem hiding this comment.
Same as above; better to not inject The.
| The default is an empty string. | ||
|
|
||
| \begin{nonnormative} | ||
| In combination with \lstinline!defaultComponentName! it can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below. | ||
| If the prefixes contain \lstinline!inner! or \lstinline!outer! and the default name cannot be used (e.g., since it is already in use) it is recommended to give a diagnostic. | ||
| In combination with \lstinline!defaultComponentName!, \lstinline!defaultComponentPrefixes! can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below. |
There was a problem hiding this comment.
| In combination with \lstinline!defaultComponentName!, \lstinline!defaultComponentPrefixes! can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below. | |
| In combination with \lstinline!defaultComponentName!, the \lstinline!defaultComponentPrefixes! can be used to make it easy for users to create \lstinline!inner! components matching the \lstinline!outer! declarations; see also example below. |
Not sure, but think it is better.
There was a problem hiding this comment.
It would have made more sense if we didn't start sentences without The in front of lower case initials in inline code.
| {\lstinline!defaultComponentPrefixes!} & Default type prefixes for new components & \Cref{modelica:defaultComponentPrefixes}\\ | ||
| {\lstinline!missingInnerMessage!} & Message for unresolved \lstinline!outer! & \Cref{modelica:missingInnerMessage}\\ | ||
| {\lstinline!absoluteValue!} & Quantity is absolute & \Cref{modelica:absoluteValue}\\ | ||
| {\lstinline!defaultConnectionStructurallyInconsistent!} & Relax verification of non-simulation class & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\ |
There was a problem hiding this comment.
| {\lstinline!defaultConnectionStructurallyInconsistent!} & Relax verification of non-simulation class & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\ | |
| {\lstinline!defaultConnectionStructurallyInconsistent!} & Relax verification of connections & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\ |
I think that mentioning non-simulation is more confusing than helping, but I'm not sure if the new text is good.
There was a problem hiding this comment.
How about this?
| {\lstinline!defaultConnectionStructurallyInconsistent!} & Relax verification of non-simulation class & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\ | |
| {\lstinline!defaultConnectionStructurallyInconsistent!} & Suppress certain verification errors & \Cref{modelica:defaultConnectionStructurallyInconsistent}\\ |
There was a problem hiding this comment.
Or, "balancing" instead of "verification"? (The problem is how to describe so that it makes sense - it doesn't mean that the models are less correct overall; just different.)
Co-authored-by: Hans Olsson <[email protected]>
This improves the presentation of some sections in the Annotations chapter, by applying the kind of overview table which is used, for example, in 18.7 Simulations.
This change was triggered by me trying to get an overview of the existing annotations, which isn't easy in in the unstructured sections. More sections could be restructured similarly, but I am keeping down the size of this PR by only taking care of two sections in pressing need, and where the transformation is straight-forward.
Also fixing some minor issues which appear to be results of the recent work on formalizing the notation.