Change doc strings to start with uppercase letter and fix spellings of Units.mo

[christiankral]

This change is not applied to Units.mo where lots of doc string start with a lower case letter.

Examples:

• metre
• revolution
• angular
• radian
• cubic
• bar
• second
• minute

are spelled with a lower case letter at the beginning of the doc string.

@MartinOtter I wonder if we shall switch to all upper case letter at the beginning of each doc string.

[beutlich]

How did you do it?

[christiankral]

How did you do it?

Manually ;-)

Search "a, "b, ...

[beutlich]

Thought you have a nice regular expression that can be used as CI job.

[dietmarw]

\[\^\\\]\"\[a-z\] or [^\]"[a-z] depending if it needs to get escaped or not.

[HansOlsson]

This change is not applied to Units.mo where lots of doc string start with a lower case letter.

Examples:

• metre
• revolution
• angular
• radian
• cubic
• bar
• second
• minute

are spelled with a lower case letter at the beginning of the doc string.

I would assume that it is because the variable name is an abbreviation of the doc-string:

 function to_kmh "Convert from metre per second to kilometre per hour"
      extends Modelica.SIunits.Icons.Conversion;
      input Velocity ms "metre per second value";
      output NonSIunits.Velocity_kmh kmh "kilometre per hour value";

An alternative is "Value in metre per second", "Value in kilometre per hour".

@MartinOtter I wonder if we shall switch to all upper case letter at the beginning of each doc string.

[beutlich]

\[\^\\\]\"\[a-z\] or [^\]"[a-z] depending if it needs to get escaped or not.

Too simple. [^\\=\,+]\s+"[a-z] avoids some false matches, but still gives 800 hits in MSL.

[christiankral]

I would assume that it is because the variable name is an abbreviation of the doc-string:

 function to_kmh "Convert from metre per second to kilometre per hour"
      extends Modelica.SIunits.Icons.Conversion;
      input Velocity ms "metre per second value";
      output NonSIunits.Velocity_kmh kmh "kilometre per hour value";

An alternative is "Value in metre per second", "Value in kilometre per hour".

I think is a good proposal. I will incorporate it in this PR.

[christiankral]

I applied the following changes:

• Changed "Kelvin" to "kelvin" according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=112-02-08
• Changed "Celsius" to "degree Celsius" according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=113-04-17
• Changed "Fahrenheit" to "degree Fahrenheit" (which was not found on electropedia) according to https://dictionary.cambridge.org/dictionary/english/fahrenheit
• Changed "Rankine" to "degree Rankine" (which was not found on electropedia) according to https://www.convertunits.com/from/kelvin/to/degree+Rankine

[HansOlsson]

The changes seem good, but the original reference for the spelling is https://www.bipm.org/utils/common/pdf/si-brochure/SI-Brochure-9-EN.pdf
which in 5.3 for unit names states:

In English, the names of units start with a lower-case letter (even when the symbol for the unit
begins with a capital letter), except at the beginning of a sentence or in capitalized material
such as a title. In keeping with this rule, the correct spelling of the name of the unit with the
symbol °C is “degree Celsius” (the unit degree begins with a lower-case d and the modifier
Celsius begins with an upper-case C because it is a proper name).

[christiankral]

The following changes are applied:

• Changed "electrical current" to "electric current"
  according to
  • http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=121-11-13
  • http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=121-11-11
• Changed "electrical potential" to "electric potential"
  according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=121-11-25
• Changed "electrical voltage" to "electric voltage" which makes sense somehow, but this term is not directly listed in electropedia (instead electric tension is listed, see http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=121-11-27, but I think this change makes sense)
• Changed "electrical impedance" to "impedance"
  according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=131-12-43
• Changed "electrical admittance" to "admittance" according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=131-12-51
• Changed "complex electrical power" to "complex apparent power" according to http://www.electropedia.org/iev/iev.nsf/display?openform&ievref=131-11-39

[christiankral]

I think I am done with the changes in Units.mo. I updated the title of this PR to fully match the applied changes

[christiankral]

@beutlich and @dietmarw please re-review Units.mo (all other files are untouched since you carried out your reviews)

[beutlich]

Suggested change

	input Modelica.Units.NonSI.Time_minute minute "Value in minute";
	output SI.Time s "Value in second";
	input Modelica.Units.NonSI.Time_minute minute "Value in minute";
	output SI.Time s "Value in second";

Should it be "Value in seconds" and "Value in minutes"? If yes, when to apply the plural?

[christiankral]

Should it be "Value in seconds" and "Value in minutes"? If yes, when to apply the plural?

I was asking this myself many times when applying all these changes. I thought that the plural form in general sounds more correct than the singular form, but I was reluctant to change it, as it causes a massive change...

One way to overcome this issue were to write "Value in unit second" instead of "Value in second". @beutlich what do you think?

[beutlich]

I am in favour of keeping the singular form.

[christiankral]

Do you mean we keep "Value in second" and do not change it to "Value in unit second"?

[beutlich]

Exactly.

[dietmarw]

@christiankral Are you aware that you will have to redo either this PR after #3480 has been merged or the other way round. I guess the latter is less of a job.

[beutlich]

Can we merge this?

[HansOlsson]

@christiankral Are you aware that you will have to redo either this PR after #3480 has been merged or the other way round. I guess the latter is less of a job.

It should be, the mere splitting should be straightforward with Dymola 2020x; and likely other tools as well. I could help if needed. And the rest just seemed to be running two commands to remove some excess stuff.

[christiankral]

Let's us merge this PR first and I will re-prepare the splitting of Blocks (similar to #3475)