Too many kinds of definitions

[henrikt-ma]

We should make all definitions use a small number of styles, but currently there is a mix of numbered ones, tables with \firstuse, description lists, and \firstuse placed in normal paragraphs.

The numbered ones are the ones that stand out the worst. These are the ones:

• Local Number of Unknowns
• Local Equation Size
• Locally Balanced
• Globally Balanced
• Plug-compatibility (= restricted subtyping)
• Default connectable
• Function-Compatibility or Function-Subtyping for Functions

Should more definitions be numbered, or should we get rid of the numbering of these in favor of description lists or simply \firstuse?

[HansOlsson]

I agree that this is an issue, and these are the most problematic ones.

The goal should be to make it easy to refer to these definitions.
The simplest solution would then be to make them (sub)subsections and just remove the Definition number. Having a separate numbering scheme for a few definitions seem over-complicated.

There are also description "tables", e.g. start of
https://specification.modelica.org/master/interface-or-type-relationships.html
that should be turned into description lists.

[henrikt-ma]

I think the most important part of a definition that's easy to refer to is that it is defining a term which can't be confused with something else. Numbering plays a more important role in printed media, where one needs to browse the physical pages in order to find a definition (if not going via an index/glossary). For us, I think it is more important that we have a mechanism that allows us to refer to a definition by a key that allows hyperlinking, and I'm sure this is doable if we only decide on one systematic markup for such definitions.

I agree that it would be great if this issue could also resolve how to get rid of the description tables — it would be a good start towards less overuse of complicated tables. Unfortunately, I had some bad luck with description lists in #2567, as the continuous integration system didn't have enumitem.sty. Apart from that, I think description lists could be a good starting point for uniting structured definitions (as opposed to \firstuse-definitions)

[HansOlsson]

I think the most important part of a definition that's easy to refer to is that it is defining a term which can't be confused with something else.

Assuming these are the only definitions in the specification and they are generally useful that would be good - and we should spend more effort on it.

However, if there are more definitions that are not marked as such, or these definitions are just used internally in some sections it would make sense to turn them into plain (sub)sections - which automatically allows hyperlinking. We could even have the name "Definition: Local Number of Unknowns" etc.

The labels for referring to sections would work in this case as well, and I assume that if we later introduced some fancy Definition-section the labels would continue to work in that case as well.

I'll look into the enumitem.sty issue.

[henrikt-ma]

The problem with using plain (sub)sections is that doing so is breaking up the surrounding (sub)section structure; the text that follows the definition is then structurally belonging to the definition rather than the current section before the definition. Besides the impact on things like the table of contents and other automatic tool processing of the document, even a human user would probably find it confusing that some things that look exactly like section titles should not be understood as such.

I think we can do better, and I interpret your comment as a preference for something where each definition is defined separately rather than as an item in a list or a row in a table. I'll give this a try when we are finished with #2567.