Clarification of some rules within UsersGuide.Conventions

Reviewing Modelica.UsersGuide.Conventions I have found some issues to be discussed/clarified.

Modelica.UsersGuide.Conventions.Documentation

General comments:
1. Change order of the package Modelica.UsersGuide.Conventions.Documentation: "Structure" first, "Format" second.
...Documentation.Format
1. Section "Paragraphs" shall be moved into a separate class for better referencing.
2. Section "Emphasis" shall be moved into a separate class called e.g. "Common text format" for better referencing.
3. Section "Capitalization of Text" shall be splitted and integrated into Modelica.UsersGuide.Conventions.Documentation.Format.Figures and Modelica.UsersGuide.Conventions.Documentation.Format.Tables.
...Documentation.Format.Code
1. Point 3: "Multi line or single line code shall not be indented." I don't really understand this point.
2. What is the difference between point 1 and point 4?
3. Suggestion: Write code additionally within <blockquote> environment to have always the same indention compared to the common text.
...Documentation.Format.Equations
1. Suggestion: Write equations additionally within <blockquote> environment.
...Documentation.Format.Figures
1. Point 1: Place figures within <div> environment for spaces before and after image. This doesn't apply if the figure is placed within the <table> environment.
2. To refer to a figure in a text, a non brakeable space shall be placed between figure name and the figure enumeration, i.e. Fig 1
...Documentation.Format.Hyperlinks
1. Points 2. and 3. seem to be of the same information. Suggestion: Reformulate Point 2 so that the hyperlink text may not necessarilly include the full main package name, since this is often not reasonable, see e.g. Modelica.UsersGuide.Conventions.UsersGuide where this rule is broken.
2. Point 5 can be deleted. Better to describe in the examples themselfs what's going on.
3. Point 6: "No links to commercial web sites are allowed". How to understand this? Found: www.modelon.se, www.dynasim.se, www.amazon.de, www.itisim.com, www.xrg-simulation.de, www.mathworks.com, www.kuka-robotics.com
4. Example 2 not according to rules defined.
...Documentation.Format.References
1. Class shall be renamed to e.g. ReferencesCitation "Citation of references" since it really is about citation.
...Documentation.Format.Tables
1. Point 4: "Table headers and entries start with capital letters." Change to "Table headers shall start with capital letters" only.

Modelica.UsersGuide.Conventions.ModelicaCode

...ModelicaCode.Format
1. Example text shall be better within <pre> environment, instead of <code>.
...ModelicaCode.Naming
1. Quantity entries of table "Variables and names" shall be given literally, e.g. "internal energy" instead of "internalEnergy".

Modelica.UsersGuide.Conventions.UsersGuide

...UsersGuide.References
1. Point 1 shall actually be a part of Modelica.UsersGuide.Conventions.Documentation.Format.References.
...UsersGuide.RevisionHistory
1. There is no class in MSL called RevisionHistory. I have found only several ReleaseNotes classes. So the class shall be renamed accordingly.

Modelica.UsersGuide.Conventions.Icons

...Icons
1. Add an example of a typical name format Text(extent={{-150,150},{150,110}}, textString="%name", lineColor={0,0,255}) into Section "Component Name".

I fully agree to all items which are not commented. Some additional comments are added, however:

Reviewing Modelica.UsersGuide.Conventions I have found some issues to be discussed/clarified.

Modelica.UsersGuide.Conventions.Documentation

1. General comments:

   1. Change order of the package Modelica.UsersGuide.Conventions.Documentation: "Structure" first, "Format" second.

2. ...Documentation.Format

   1. Section "Paragraphs" shall be moved into a separate class for better referencing.
   2. Section "Emphasis" shall be moved into a separate class called e.g. "Common text format" for better referencing.
   3. Section "Capitalization of Text" shall be splitted and integrated into Modelica.UsersGuide.Conventions.Documentation.Format.Figures and Modelica.UsersGuide.Conventions.Documentation.Format.Tables.

3. ...Documentation.Format.Code

   1. Point 3: "Multi line or single line code shall not be indented." I don't really understand this point.

Code shall be displayed as

code

not

    code

No blanks / tab before the first code character = not indented. So this comment may be obsolete, as you proposed blockquote

   2. What it the difference between point 1 and point 4?

I guess point 4 refers refers to code snippets embedded in a text paragraph. It may thus make sense to re-phrase point 4.

   3. Suggestion: Write code additionally within `<blockquote>` environment to have always the same indention compared to the common text.

4. ...Documentation.Format.Equations

   1. Suggestion: Write equations additionally within `<blockquote>` environment.

5. ...Documentation.Format.Figures

   1. Point 1: Place figures within `<div>` environment for spaces before and after image. This doesn't apply if the figure is placed within the `<table>` environment.

I think it makes sense to use

<figure>
 <img src="...">
 <figcaption>Figure caption.</figcaption>
</figure>

instead of the (obsolete) workaround based on tables...

   2. To refer to a figure in a text, a non brakeable space shall be placed between figure name and the figure enumeration, i.e. `Fig&nbsp;1`

6. ...Documentation.Format.Hyperlinks

   1. Points 2. and 3. seem to be of the same information. Suggestion: Reformulate Point 2 so that the hyperlink text may not necessarilly include the full main package name, since this is often not reasonable, see e.g. Modelica.UsersGuide.Conventions.UsersGuide where this rule is broken.
   2. Point 5 can be deleted. Better to describe in the examples themselfs what's going on.
   3. Point 6: "No links to commercial web sites are allowed". How to understand this? Found: [www.modelon.se](http://www.modelon.se), [www.dynasim.se](http://www.dynasim.se), [www.amazon.de](http://www.amazon.de), [www.itisim.com](http://www.itisim.com), [www.xrg-simulation.de](http://www.xrg-simulation.de), [www.mathworks.com](http://www.mathworks.com), [www.kuka-robotics.com](http://www.kuka-robotics.com)

On my opinion, links to the webpage of the companies which are the MSL developers associated with, are OK. I dislike links to amazon and I guess they are not needed. In case of cited literature, the DOI would be good solution.

Probably we should list all link (in a separate ticket) to start a discussion on how we proceed with these links step by step.

   4. Example 2 not according to rules defined.

I suppose 2. is too strong: the full qualified name to be shown as link is not practical. Example 2 is good on my option. Let's remove 2.

7. ...Documentation.Format.References

   1. Class shall be renamed to e.g. ReferencesCitation "Citation of references" since it really is about citation.

8. ...Documentation.Format.Tables

   1. Point 4: "Table headers and entries start with capital letters." Change to  "Table headers shall start with capital letters" only.

Modelica.UsersGuide.Conventions.ModelicaCode

1. ...ModelicaCode.Format

   1. Example text shall be better within `<pre>` environment, instead of `<code>`.

2. ...ModelicaCode.Naming

   1. Quantity entries of table "Variables and names" shall be given literally, e.g. "internal energy" instead of "internalEnergy".

Modelica.UsersGuide.Conventions.UsersGuide

1. ...UsersGuide.References

   1. Point 1 shall actually be a part of Modelica.UsersGuide.Conventions.Documentation.Format.References.

2. ...UsersGuide.RevisionHistory

   1. There is no class in MSL called RevisionHistory. I have found only several ReleaseNotes classes. So the class shall be renamed accordingly.

Modelica.UsersGuide.Conventions.Icons

1. ...Icons

   1. Add an example of a typical name format `Text(extent={{-150,150},{150,110}}, textString="%name", lineColor={0,0,255})` into Section "Component Name".

modelica / ModelicaStandardLibrary