Guidelines for figure authoring

[henrikt-ma]

Guidelines for figures are needed now that we are about to add figures to examples on a large scale, as noted in #4811.

Specifically, #4811 (comment) requested that the guidelines should be introduced in a separate PR (this one).

Note that the use of a right $y$ axis is currently not supported by the specification. This is the topic of modelica/ModelicaSpecification#3938.

[maltelenz]

The guidelines seem sensible to me, but I'll wait for other opinions before leaving an approving review in case there are dissenting opinions.

[AHaumer]

Thanks a lot @henrikt-ma valuable work!
Just one minor change: The destination of this link is not found.
<a href="modelica://Modelica.UsersGuide.Conventions.Documentation.Figures">Figures embedded in HTML documentation</a>
After fixing that (I don't know what you wanted to link) I'll approve it!
Anyhow, I'll try to update my PR #4811 following these recommendations.

[tobolar]

Just one minor change: The destination of this link is not found.
Figures embedded in HTML documentation

I suppose this is a link to line 1848 of the same file Modelica/UsersGuide/Conventions.mo.

[tobolar]

Suggested change

	Figures are defined in the <code>figures</code> sub-annotation of the <code>Documentation</code> annotation, explained in detail in <a href=\"https://specification.modelica.org/maint/3.6/annotations.html#annotations-for-figures\">Section&nbsp;18.2.2 <em>Figures</em> of the Modelica&nbsp;3.6 specification</a>.
	Figures are defined in the <code>figures</code> sub-annotation of the <code>Documentation</code> annotation, explained in detail in
	<a href=\"https://specification.modelica.org/maint/3.6/annotations.html#annotations-for-figures\">Section&nbsp;18.2.2 <em>Figures</em> of the Modelica&nbsp;3.6 specification</a>.

[tobolar]

Is this relevant even when long captions shall be avoided?

[tobolar]

Better to have a code snippet here. (Who wants to search for it in PID_Controller?)

[HansOlsson]

Or both - a code snippet with the paragraphs, and stating is from PID_Controller.
I don't think you need the full plot in the snippet, and thus it makes sense to have a reference for that.

Obviously a code snippet may get out of sync - but I don't think it is too problematic in this case.

[tobolar]

This is just about the code indentation:

Suggested change

	<li><p>
	Conveying the axis unit (not allowed according to the Modelica specification).
	</p></li>
	<li><p>
	As substitute for curve legends, or showing information already present in the curve legends.
	</p></li>
	<li><p>
	Quantity names, for the sake of consistency across the library.
	(Nothing prevents a tool from using <code>quantity</code> attributes of the plotted variables to automatically and consistently present quantity names when no <code>label</code> is given.)
	</p></li>
	<li>
	Conveying the axis unit (not allowed according to the Modelica specification).
	</li>
	<li>
	As substitute for curve legends, or showing information already present in the curve legends.
	</li>
	<li>
	Quantity names, for the sake of consistency across the library.
	(Nothing prevents a tool from using <code>quantity</code> attributes of the plotted variables to automatically and
	consistently present quantity names when no <code>label</code> is given.)
	</li>

[tobolar]

@henrikt-ma Thanks for preparing this valuable guidelines.

My comments

1. The Titles and Captions would be necessary even for one figure with just one plot, right? This seems tough to me.
2. For Identifiers, a possible recommended simple identifiers could be fig-i (i=1,..) and plot-i-j (j=1,...)? (and without index where just one figure)