Revisit deprecations for connection line Text annotations?

[henrikt-ma]

When working on the Text annotation for labels on connection lines, https://specification.modelica.org/master/annotations.html#S9.SS4.p3, we have encountered som surprising deprecations in the specification, and we would like to propose that the deprecations are revisited.

Zero vertical extent

This is the main deprecation we would like to undo:

Having a zero size for the extent is deprecated and is handled as if upper part is moved up an appropriate amount.

When fontSize is specified, not specifying a height makes more sense than specifying it . Can anyone explain why this was deprecated?

To neither specify a (positive) fontSize or a positive vertical extent could be a an excellent way to leave the choice of size to the tool, enabling a consistent look of connection line labels across libraries.

Also, I can't see any deprecation of zero vertical extent for the "regular" Text annotation in https://specification.modelica.org/master/annotations.html#S9.SS5.SSS5.p1. It would make sense if the two Text annotations didn't differ in this regard.

As in many other cases of deprecation, we have noticed that not even the MSL has moved away from the deprecated semantics, which we consider another good reason to undo the deprecation. For example, FullRobot is full of these:

extent={{-6,3},{-6,3}})

In fact, all occurrences of Text for connection lines that I found with a quick'n dirty regexp search had 0 by 0 extent.

Automatic horizontal alignment

I'd also like to bring up the deprecation of this default:

  TextAlignment horizontalAlignment =
    if index < 0 then TextAlignment.Right else TextAligment.Left "Note: different default";

While it is clear to me that the default is bad (it makes assumptions about how the connection line is oriented) and that this can be seen as a reason for deprecation, wouldn't it serve us better to undo the deprecation, remove the bad expression for the default, and say it's up to tools to choose a suitable alignment?

[HansOlsson]

1. Zero extent was a response to Text annotation on connect equation needs clarification #2170 I can understand that we update it to require at least one of: non-zero vertical extent or font-size.

2. "Automatic horizontal alignment" I think the critical question isn't if tools choose a suitable alignment, but how and when.

If there's no horizontalAlignment specified tools will have to select a value when rendering, and normally the rendering doesn't update the model - which will give the result of different horizontalAlignment for the texts in different tools. I hope we can agree that it's bad.

To me deprecating the default value instead implies that tools should set a value when creating such an annotation (similarly as for an attribute without default such as extent or string), and as for other attributes tools will generate suitable defaults for that (similarly as for the textColor).

[henrikt-ma]

2. "Automatic horizontal alignment" I think the critical question isn't if tools choose a suitable alignment, but how and when.

If there's no horizontalAlignment specified tools will have to select a value when rendering, and normally the rendering doesn't update the model - which will give the result of different horizontalAlignment for the texts in different tools. I hope we can agree that it's bad.

Of course, rendering should not update the model. I'm sorry, but I can't really agree that tool variations need to be a bad thing when it comes to features like this, at least as long as we don't have the resources and initiative to agree on a "perfect" behavior that we can write down in the specification.

Based on the current default rule, I am guessing that the current default rule is primarily used when a connection line for connect(a.y, b.u) is drawn from a.y to b.u, so that index = 1 results in a nicely left-aligned label, while index = -1 would result in a nicely right-aligned label. Conversely, I would also not expect the horizontalAlignment to currently be left unspecified when the default behavior would give a bad result.

Hence, I think there is a good chance that tools could automatically figure out a nice alignment for all current uses of the annotation, while a more intelligent tool behavior would avoid the need to over-specify horizontalAlignment in most cases.

To me deprecating the default value instead implies that tools should set a value when creating such an annotation (similarly as for an attribute without default such as extent or string), and as for other attributes tools will generate suitable defaults for that (similarly as for the textColor).

An important benefit of not specifying horizontalAlignment is that if the index is changed, the tool cannot know whether a specified horizontalAlignment is the hard-coded result of an intelligent tool behavior, or the result of an explicit user decision. Hence, one horizontalAlignment has been given a value, it becomes impossible for the tool to maintain the intelligent alignment when the label is moved.

[HansOlsson]

An important benefit of not specifying horizontalAlignment is that if the index is changed, the tool cannot know whether a specified horizontalAlignment is the hard-coded result of an intelligent tool behavior, or the result of an explicit user decision. Hence, one horizontalAlignment has been given a value, it becomes impossible for the tool to maintain the intelligent alignment when the label is moved.

I agree that it doesn't matter if it was the result of intelligent tool behavior or explicit user decision; but to me that is because the user assumedly looked at the result and thought it good (or at least acceptable); so always view it as a user decision.

However, the discussion about changing index seems odd to me. Normally the index is used for specifying the more specific part of a connection to an expandable connector (as in this example); and that seems unlikely to change. The more common issue would be that the component with that connector is rotated.

Added: And when rotating it doesn't really matter if it was an automatic or deliberate choice, the attributes will still need an update.

[henrikt-ma]

Added: And when rotating it doesn't really matter if it was an automatic or deliberate choice, the attributes will still need an update.

No, if a user has explicitly asked for a certain alignment, the tool shouldn't change it. However, I expect that with just a bit of intelligence in the automatic alignment, there won't be any need for users to force a specific alignment, so tools can simply leave the horizontalAlignment unspecified when making other changes to the label placement.

I just checked the MSL more carefully, and I didn't find a single connection line Text annotation that specifies horizontalAlignment. If this is already working so well, it seems really unnecessary to keep the deprecation.

[HansOlsson]

Added: And when rotating it doesn't really matter if it was an automatic or deliberate choice, the attributes will still need an update.

No, if a user has explicitly asked for a certain alignment, the tool shouldn't change it. However, I expect that with just a bit of intelligence in the automatic alignment, there won't be any need for users to force a specific alignment, so tools can simply leave the horizontalAlignment unspecified when making other changes to the label placement.

What kind of other changes are you thinking of?

From my perspective, I don't see how specifying the alignment for one context for the text matters after changing that context.
(However, the user is likely to manually specify it again if they are into such minor tweaks.)

I just checked the MSL more carefully, and I didn't find a single connection line Text annotation that specifies horizontalAlignment. If this is already working so well, it seems really unnecessary to keep the deprecation.

I believe that is because all of them relies on connecting the more specific bus-part to the left of the component (so the diagram reads left-to-right).

Overall the text-on-connections doesn't seem to be used much. (Also looking at other libraries). I don't know if that indicates that the alignment isn't working, or just that the texts would clutter the diagram. @DagBruck might have more inputs.

[henrikt-ma]

Added: And when rotating it doesn't really matter if it was an automatic or deliberate choice, the attributes will still need an update.

No, if a user has explicitly asked for a certain alignment, the tool shouldn't change it. However, I expect that with just a bit of intelligence in the automatic alignment, there won't be any need for users to force a specific alignment, so tools can simply leave the horizontalAlignment unspecified when making other changes to the label placement.

What kind of other changes are you thinking of?

I'm thinking of changing extent, origin, rotation, index, fontSize, … you name it.

From my perspective, I don't see how specifying the alignment for one context for the text matters after changing that context. (However, the user is likely to manually specify it again if they are into such minor tweaks.)

Again, with a well working default I expect it to rarely be the case that a user feels the urge to override the default, but in the exceptional cases when there has been a manual effort to specify a particular alignment nevertheless, I would be annoyed as a user if a tool thinks it knows better (or that it cannot make an informed decision since it can't distinguish between something it automatically added itself and something manually specified by the user) when I make a small adjustment to, say, the extent.

I just checked the MSL more carefully, and I didn't find a single connection line Text annotation that specifies horizontalAlignment. If this is already working so well, it seems really unnecessary to keep the deprecation.

I believe that is because all of them relies on connecting the more specific bus-part to the left of the component (so the diagram reads left-to-right).

That's possible, but the beauty is that we don't need the current deprecated default to automatically get nice results!

I should also add that the current default for horizontalAlignment suffers from the same DynamicSelect issue as we had with Ellipse.closure in #3646; there is no way to express the current default behavior when using DynamicSelect. Hence, the full solution to horizontalAlignment would involve introducing TextAlignment.Automatic, and then specify that this is the default for horizontalAlignment, and that this value is not allowed for the other Text annotation.

[HansOlsson]

Added: And when rotating it doesn't really matter if it was an automatic or deliberate choice, the attributes will still need an update.

No, if a user has explicitly asked for a certain alignment, the tool shouldn't change it. However, I expect that with just a bit of intelligence in the automatic alignment, there won't be any need for users to force a specific alignment, so tools can simply leave the horizontalAlignment unspecified when making other changes to the label placement.

What kind of other changes are you thinking of?

I'm thinking of changing extent, origin, rotation, index, fontSize, … you name it.

I can understand that is kept when changing extent, fontSize, the text (or origin, even if I don't know why one would change origin), but I find it odd when changing index (especially when changing from one end to the other), or re-routing the connection if the corresponding component is e.g., rotated.

I don't see why it would auto-update alignment just because alignment was previously automatic if the extent, fontSize, or text was changed. I think I would just view that as annoying when tweaking them.