Poor structure of chapter "Packages"

[henrikt-ma]

The organization of the chapter Packages is very poor, with pretty much all content hiding under the section Motivation and Usage of Packages.

This should be changed by extracting the Motivation part to the chapter introduction (directly under \chapter), and breaking apart the rest of Motivation and Usage of Packages to a sequence of sections.

[HansOlsson]

I see the point-

The "usage part" would be the following sections, I assume:

• Importing Definitions from a Package
• Mapping Package/Class Structures to a Hierarchical File System
• External resources
• The Modelica Library Path - MODELICAPATH

Technically this is still a bit messy, as two of them refer to file system mapping (which isn't that connected to packages, but it still sort of makes sense), and "External resources" is useful in general.

After some thought, I think that if we want to re-order it should be

• Importing Definitions from a Package
• The Modelica Library Path - MODELICAPATH
• Mapping Package/Class Structures to a Hierarchical File System
• External resources This keeps the two sections about file system together, and since "External resources" refers to the file-system mapping it makes sense to have it after that. I see no problem with having MODELICAPATH before file system mapping, as the file system contents is mostly about the hierarchical contents.

[HansOlsson]

In addition the current motivation should only be non-normative text, i.e., the following text should also be non-normative (even though it is currently normal text): "Definitions that are related to some particular topic are typically grouped into a package. This makes those definitions easier to find and the code more understandable. "

[henrikt-ma]

I don't know what others think, but to me, the paragraphs directly under a chapter heading could be understood to be non-normative by mere position in the document, removing the need to put ugly brackets and emphasis which just looks strange when there is no surrounding text with the normal upright font. What do you think?

[HansOlsson]

I don't know what others think, but to me, the paragraphs directly under a chapter heading could be understood to be non-normative by mere position in the document

Interesting idea - I tried to verify if that was true, and mostly it seems correct - but some chapters break this I think:

1. Introduction: Empty
2. Lexical: Overview that could be seen as non-normative I think.
3. Operators&c: Overview that could be seen as non-normative I think.
4. Classes&c: Overview that may contain something normative.
5. Scoping&c: Minimal overview - that can be non-normative.
6. Interface or Type Relationships: Contains some important definitions
7. Inheritance&c: Overview that could be seen as non-normative I think.
8. Equations: Empty
9. Connectors&c: Minimal overview (that could be non-normative), but also normative restrictions on conditional connect-statement (which is also present in 8.3.3 connect-equations).
10. Arrays: Large overview - currently mixing some non-normative text. However, I believe most(or all?) of the normative text is also present in other places.
11. Statements&c: Overview that could be seen as non-normative I think.
12. Functions: Minimal overview - that can be non-normative.
13. Packages: See previous discussion
14. Overloaded operators. Overview that contain some normative text. (And some explicitly non-normative text.)
15. Stream connectors: Overview that could be seen as non-normative I think.
16. Synchronous...: Minimal overview - that can be non-normative.
17. State machines. Overview that is entirely marked as non-normative, that doesn't look nice.
18. Annotations: Overview, but some of the text may be seen as normative.
19. Unit expressions: Overview that could be seen as non-normative I think.
20. MSL: Entire chapter, and entirely non-normative.

[henrikt-ma]

Very nice report. It shows that it wouldn't be too much work to break out the normative parts and place under some section heading.

[HansOlsson]

I would like to see if we can get agreement on the ideas above at the meeting, and hopefully a volunteer to make the minimal changes above.

[HansOlsson]

Stating that chapter-introductions are non-normative in chapter-introductions; and change to be consistent. Favor: 7 Against: 0 Abstain: 2

[HansOlsson]

Added to the agenda for phone-meeting to see if anyone volunteers.