Upgrade user's guide

[tobolar]

For both Rotational and Translational libraries from Modelica.Mechanics.
This concerns the documentation text itself as well as proper html format (e.g. " instead of ", etc.)

close #2813

[christiankral]

Unifying the documentation of the MSL is a very extensive task. We still have a lot of very different formats applied to variables in the documentation of the MSL models (and User's Guides). However, I think it does make sense to step by step unify the appearance. In Modelica.UsersGuide.Conventions.Documentation.Format.Equations it is stated that variables shall be typeset in italic (emphasized) font. The following changes are thus not in line: c134d73

Everything else looks good.

[christiankral]

Note the following different formatting examples I found in a quick survey of the different packages:

• Modelica.Blocks.Continuous.Integrator uses bold and italic for variables
  
• Modelica.ComplexBlocks.ComplexMath.Gain used <code> for all variables
  
• Modelica.Electrical.Analog.Basic.Resistor is implemented in italic only according to the specification
  
• Modelica.Electrical.Machines.BasicMachines.AsynchronousInductionMachines.AIM_SquirrelCage upright font
  
• Modelica.Mechanics.Rotational.UsersGuide.ModelingOfFriction uses (now) "
  
• Modelica.Mechanics.Rotational.Interfaces.PartialElementaryTwoFlangesAndSupport2 Code segments are written in italic instead of using <code> and only one = is used instead of == as shown in Modelica.UsersGuide.Conventions.Documentation.Format.Cases
  

[tobolar]

@christiankral Modelica.UsersGuide.Conventions.Documentation.Format.Equations says variables shall be in "italic fonts". This can be achieved either by:

• <em> - but this is actually an accentuation of the text,
• <i> - shall be ok, but w3c recommends for HTML5 to use another elements, if possible,
• <var> - according to w3c this defines a variable.

So I would follow the recommendation and simply use <var> for variables.

[christiankral]

Using <var> sounds very reasonable to me. We could even update the MSL User's Guide stating that <var> is recommended and <em> (which is widely used) is accepted, as <var> definitely refers to variables and <em> is intended to emphasize.

Two more comments here:

1. So far, many equations have been put under the <em> tag, such as <em>i*R = v</em> in Modelica.Electrical.Analog.Basic.Resistor. The correct way of implementing equations is shown in https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var, so Ohm's law shall be typeset as <var>i</var> * <var>R</var> = <var>v</var>
2. I am very much in favor of having the documentation of the MSL as uniform as possible, as this makes it look professional and much easier to read. This somehow implies to have more rules being applied to the formatting guidelines of the MSL. Consequently, every new hard rule makes a lot of HTML code of the MSL being "wrong", as may different authors created their documentation in many different ways long time ago. I do not like this either, but it may be the way to go if we stick with HTML. Possibly a markdown language could simplify the text and equation formatting issues, but the conversion effort were tremendous, even if done semi-automatically.

[tobolar]

@christiankral

it is stated that variables shall be typeset in italic (emphasized) font

Shall be done now.

[beutlich]

I resolved the merge conflicts and clean-up the commit history. @christiankral @AHaumer Please review (again)!

@tobolar Is it intentional that Modelica.Mechanics.Translational.UsersGuide.StateSelection speaks about angles as state variables?

[christiankral]

OK, looks all good.

[beutlich]

Is it intentional that Modelica.Mechanics.Translational.UsersGuide.StateSelection speaks about angles as state variables?

[AHaumer]

Well in many components the following is used: SI.AngularVelocity w=der(phi)
Depens on the state selection, but in many cases angles are states (but not the only ones).

[beutlich]

Is it intentional that Modelica.Mechanics.Translational.UsersGuide.StateSelection speaks about angles as state variables?

@tobolar Can you please reply on this open comment?

[beutlich]

Is it intentional that Modelica.Mechanics.Translational.UsersGuide.StateSelection speaks about angles as state variables?

@tobolar Can you please reply on this open comment?

Friendly reminder @tobolar

[tobolar]

@beutlich Fixed now. Thanks!

[beutlich]

OK, going to merge.

The real issue still is mentioned in #2946 and I'd like to see @tobolar's and @MartinOtter's input there.