search

modelica / ModelicaSpecification

Specification of the Modelica Language
https://specification.modelica.org
Creative Commons Attribution Share Alike 4.0 International
98 stars 42 forks source link

Use of HTML in description strings and general annotations #3051

Open henrikt-ma opened 2 years ago

henrikt-ma commented 2 years ago

Some time ago it was clarified how HTML content can be included in the Documentation annotation (see #2593), but it was missed that the same kind of formulations that were improved then also existed in the Modelica Concrete Syntax chapter: https://github.com/modelica/ModelicaSpecification/blob/35fb5f276a6bd993496d6073b10e3426ff762905/chapters/syntax.tex#L64

This was reported in feedback to https://github.com/modelica/ModelicaSpecification/pull/3045#discussion_r755270942, but it was agreed that it shouldn't be resolved as part of that PR.

Thus, this issue seeks clarification of these questions:

beutlich commented 2 years ago
  • Are there any other annotations than Documentation where HTML tags are supported?

I touched that question for the label annotation in #2915.

HansOlsson commented 2 years ago

One obvious use of html in description string is something like: parameter Real beta2 "<html>The value for &beta;<sup>2</sup></html>";

beutlich commented 2 years ago

One obvious use of html in description string is something like: parameter Real beta2 "<html>The value for &beta;<sup>2</sup></html>";

Which already can be expressed by current Modelica w/o HTML support: parameter Real beta2 "The value for β²";

henrikt-ma commented 2 years ago

One obvious use of html in description string is something like: parameter Real beta2 "<html>The value for &beta;<sup>2</sup></html>";

Sure. For the description strings we just need the same clear rules for how to use the HTML tags as we developed for the Documentation annotation in 18.2.1.

henrikt-ma commented 2 years ago
  • Are there any other annotations than Documentation where HTML tags are supported?

I touched that question for the label annotation in #2915.

Right, so here we have a potential future annotation where HTML could be useful.

What makes me wonder about having a rule about support for HTML in annotations in general is how widely applicative it is – I wonder if there's any tool today that supports all of these:

I probably missed some of the annotations where HTML could be meaningful, but one can also argue whether some of the annotations above would really be meaningful places for HTML content. The unclarity of this situation is what makes me think that it would be better to remove the generic rule about HTML being supported in annotations, and replace it with specific remarks about HTML support for selected annotations where we really want it.

Finally, it would be nice if we could refactor the presentation so that as much as possible about the strings with HTML content is described in one place, and that all places where HTML should be supported then refer to the common description.

HansOlsson commented 2 years ago

Hans: Make a PR for exact same semantics for description-strings (must start with etc).