Add stylesheet.

[HansOlsson]

Closes #1893

I understand that the suggested names could be changed, or even removed from the proposal.
However, Dymola has used them for quite some time - and I believe they are used in some libraries.

[maltelenz]

My assumption would be that tools have their own styling on the kinds of things listed in the current proposal, and any user attempt to write a tool-independent stylesheet to enforce their styling on tool generated content would result in a mess. Most users would also not be expected to have all tools on the market, so they can't even see what their changes will result in, once mixed up with the tool-dependent styling.

I think we should go the other way: The user can give a stylesheet, which will be applied to the thing they write in the info and revisions fields. We reserve some css class and/or id prefix for tool usage, that users should avoid. This way, the tool styling of the autogenerated "stuff around" will not interfere with user content and styling.

[HansOlsson]

Ok, removed those tags.

[maltelenz]

What do you think about the remainder of my comment, reserving some class/id prefix for tool use, and explicitly saying that the info and revisions fields are the fields that will use the provided CSS?

[HansOlsson]

What do you think about the remainder of my comment, reserving some class/id prefix for tool use, and explicitly saying that the info and revisions fields are the fields that will use the provided CSS?

For the first I think we need to consider it more and I'm not sure if needed, so I would prefer you make a separate PR for that.
As for explicitly stating that info and revisions will use it, I agree that it is the intent but I'm not sure exactly how to formulate it.

[maltelenz]

For the first I think we need to consider it more and I'm not sure if needed, so I would prefer you make a separate PR for that.

How else would a tool separate styling on their own generated content from the user-provided content?
I view this as a central issue with this proposal, so I think it should be considered together.

As for explicitly stating that info and revisions will use it, I agree that it is the intent but I'm not sure exactly how to formulate it.

How about:

A top-level package may contain an annotation \lstinline!styleSheet="modelica://Package/Resources/style.css"!, which provides a cascading stylesheet. The given stylesheet is used when displaying the Documentation.info and Documentation.revisions annotations.

[HansOlsson]

For the first I think we need to consider it more and I'm not sure if needed, so I would prefer you make a separate PR for that.

How else would a tool separate styling on their own generated content from the user-provided content? I view this as a central issue with this proposal, so I think it should be considered together.

Well, I don't know and would prefer to see a concrete proposal for that.

As for explicitly stating that info and revisions will use it, I agree that it is the intent but I'm not sure exactly how to formulate it.

How about:

A top-level package may contain an annotation \lstinline!styleSheet="modelica://Package/Resources/style.css"!, which provides a cascading stylesheet. The given stylesheet is used when displaying the Documentation.info and Documentation.revisions annotations.

I added something like that.

[maltelenz]

Well, I don't know and would prefer to see a concrete proposal for that.

Here is a concrete proposal:

class and id selectors starting with __ are reserved for use by vendors, and shall not be used in the provided stylesheet. Similarly, class and id attributes starting with __ in HTML tags in the info and revisions annotations are reserved for use by vendors.

[Vendors can use a __NameOfVendor prefix to style vendor generated HTML content surrounding the user provided documentation.]

Not sure how to best place this information so one can find it when reading about the info and revisions tags as well.

I did just realize this doesn't solve everything, since users can still do:

p {
    background-color: pink;
}

which would destroy any vendor-generated content in p as well.

Maybe more thought and discussion is needed.

Edit: Maybe if we restrict the CSS to only allow class and id selectors, in addition to the reserved things above...

[maltelenz]

My knowledge on HTML and CSS is very old, so if we have anyone with more knowledge that can contribute, that would be great!

One approach would be to require that the user provided stylesheet prefixes each of its rules with a specified id, and tools wrap the user-provided HTML into a div with that id.

Tool generates this (pseudo-code):

<html>
  <head>
    <link rel="stylesheet" href="userstylesheet.css" />
  </head>
  <body>
    <h1>TheClassName</h1>
    <!-- more tool generated content -->
    
    <div id = "info">
      <!-- user provided info annotation goes here -->
    </div>

    <!-- more tool generated content -->
  </body>
</html>

and the user provided stylesheet is required to prefix all of its selectors with the id:

#info p {
  color: green;
}

#info li.special {
  color: orange;
  font-weight: bold;
}

[HansOlsson]

My knowledge on HTML and CSS is very old, so if we have anyone with more knowledge that can contribute, that would be great!

I haven't studied it recently either, and I think that's another reason to delay adding those details, and just accept the current PR until then.

[maltelenz]

I don't think we should open pandoras box by just accepting a wholesale stylesheet, since we know that it opens up for way to much flexibility that can't be handled in a good way by tools or users.

We need a clearly defined border that limits the user provided stylesheet effects to the user provided HTML contents, so that at least a well meaning user knows what to put in the stylesheet so it won't destroy anything.

[HansOlsson]

Language group:
Henrik T: Risk of very different look and feel for different libraries, in the same tool.
But libraries also want to control look&feel.
Limit css to specific classes?
Investigate more.
Already possibly today using iframe in html-fragment.
Henrik T: Possibility of having entire HTML as separate file

[HansOlsson]

The issues to decide on are:

• Should we add this?
• What can safely be used in style-sheets to control the styling of the user-contents? Will add other comment about this as well.
• If tools allow styling of the "tool-specific" part (as Dymola does), how shall that be controlled - or is it just up to tools? (Note that some tools have common tool-specific parts; MapleSim and Dymola have similar table of parameters; and Wolfram System Modeler has a slightly different one.) The normal vendor-specific annotation would look weird in css.

[HansOlsson]

My knowledge on HTML and CSS is very old, so if we have anyone with more knowledge that can contribute, that would be great!

One approach would be to require that the user provided stylesheet prefixes each of its rules with a specified id, and tools wrap the user-provided HTML into a div with that id.

Tool generates this (pseudo-code):

<html>
  <head>
    <link rel="stylesheet" href="userstylesheet.css" />
  </head>
  <body>
    <h1>TheClassName</h1>
    <!-- more tool generated content -->
    
    <div id = "info">
      <!-- user provided info annotation goes here -->
    </div>

    <!-- more tool generated content -->
  </body>
</html>

and the user provided stylesheet is required to prefix all of its selectors with the id:

#info p {
  color: green;
}

#info li.special {
  color: orange;
  font-weight: bold;
}

That seems to require that tools do something specific with the generated contents, and that users must know both what the tool does and their own contents - that seems quite complicated. Why not just add the following as documentation in the class:

<html>
<div class="Greeting">
<p>Hello and hi</p>
</div>
Some description
</html>

and then have style.css as follows:

.Greeting {
  color: orange;
  font-weight: bold;
}

We could still say that the ids/classes should conform to some guide.

(Yes, that works in Dymola - for the definition of works that doesn't consider readability.)

[maltelenz]

@HansOlsson sounds similar to my previous proposal in a comment above? Quoted the relevant parts here for convenience:

Here is a concrete proposal:

class and id selectors starting with __ are reserved for use by vendors, and shall not be used in the provided stylesheet. Similarly, class and id attributes starting with __ in HTML tags in the info and revisions annotations are reserved for use by vendors.
[Vendors can use a __NameOfVendor prefix to style vendor generated HTML content surrounding the user provided documentation.]

Edit: Maybe if we restrict the CSS to only allow class and id selectors, in addition to the reserved things above...

[HansOlsson]

@HansOlsson sounds similar to my previous proposal in a comment above? Quoted the relevant parts here for convenience:

Here is a concrete proposal:

class and id selectors starting with __ are reserved for use by vendors, and shall not be used in the provided stylesheet. Similarly, class and id attributes starting with __ in HTML tags in the info and revisions annotations are reserved for use by vendors.
[Vendors can use a __NameOfVendor prefix to style vendor generated HTML content surrounding the user provided documentation.]

Edit: Maybe if we restrict the CSS to only allow class and id selectors, in addition to the reserved things above...

Good, but some minor notes.

I was not sure if that vendor part was how it was normally done in CSS; and looking at https://www.w3.org/TR/CSS22/syndata.html#vendor-keywords I'm still unsure, but my conclusion is that we shouldn't use exactly that.
My uncertainty is whether we are "vendors" in the CSS-sense, or that is only for CSS-vendors like browsers.

• If we are "vendors" then it seems it should only be one underscore, not two (hyphen is an alternative).
• If we are not "vendors" we should find some other variant, perhaps "NameOfVendor-...", or something similar; the risk with using a "vendor" name as a non-vendor would be that browsers ignore css for other vendors, or style-checkers detect them.

Added: The second option seems safer, and/or we could tell library writers to have some prefix for their ids.

[maltelenz]

That is some good digging, I wasn't aware of the CSS vendor concept.

I agree we should avoid the underscore, we probably don't count as a vendor in the CSS-sense.

Reserving a prefix for Modelica vendors is probably better than forcing library developers to use a prefix. After all, vendors only need to work with their generated content occasionally, library vendors do that much more often.

NameOfVendor- has the issue that library developers would need to know of all current and future tools and their chosen vendor prefix. However, maybe this isn't a large problem in practice. An alternative might be VendorCSS, literally (not for example WolframSystemModelerCSS). After all, I don't think there is a risk of different vendors CSS identifiers/classes ever to be used in the same document?

Or Vendor-NameOfVendor (example: Vendor-WolframSystemModeler)?

[HansOlsson]

That is some good digging, I wasn't aware of the CSS vendor concept.

I agree we should avoid the underscore, we probably don't count as a vendor in the CSS-sense.

Reserving a prefix for Modelica vendors is probably better than forcing library developers to use a prefix. After all, vendors only need to work with their generated content occasionally, library vendors do that much more often.

On the other hand it may make sense to mix documentation from different libraries when building combined models, and in that case there might be a benefit. Whereas combining the documentation from multiple tools in one document seem less useful.

NameOfVendor- has the issue that library developers would need to know of all current and future tools and their chosen vendor prefix. However, maybe this isn't a large problem in practice. An alternative might be VendorCSS, literally (not for example WolframSystemModelerCSS). After all, I don't think there is a risk of different vendors CSS identifiers/classes ever to be used in the same document?

Or Vendor-NameOfVendor (example: Vendor-WolframSystemModeler)?

I think WolframSystemModeler-... suffices.

[maltelenz]

Looking at the list of CSS selectors here, maybe something like this?

The provided stylesheet shall not use type or universal selectors.
[It is recommended to use class and id selectors with a NameOfLibrary prefix to avoid collisions when the content is included in a larger context.]
Vendors shall use a NameOfVendor prefix to style vendor generated HTML content surrounding the user provided documentation.

[HansOlsson]

To discuss:

• Add stylesheet in general?
• Restrict names for library and/or tool vendors? Is it intended that the CSS override tool CSS?

[maltelenz]

• Is it intended that the CSS override tool CSS?

I very strongly think not. How would users know what they are doing, since they probably don't have all tools available to look at the effects? Each vendor can use vendor annotations to override their specific tool-generated content if they want to offer this feature.

[HansOlsson]

• Is it intended that the CSS override tool CSS?

I very strongly think not. How would users know what they are doing, since they probably don't have all tools available to look at the effects? Each vendor can use vendor annotations to override their specific tool-generated content if they want to offer this feature.

I think it should be reformulated as follows:

• If tools want to give users (of that tool) the possibility to override the tool-specific CSS they can document that. The tool-specific CSS should have a specific prefix to avoid this happening by accident.

[maltelenz]

• Is it intended that the CSS override tool CSS?

I very strongly think not. How would users know what they are doing, since they probably don't have all tools available to look at the effects? Each vendor can use vendor annotations to override their specific tool-generated content if they want to offer this feature.

I think it should be reformulated as follows:

* If tools want to give users (of that tool) the possibility to override the tool-specific CSS they can document that. The tool-specific CSS should have a specific prefix to avoid this happening by accident.

Sure, that works together with my suggestion:

Vendors shall use a NameOfVendor prefix to style vendor generated HTML content surrounding the user provided documentation.

[HansOlsson]

This should now be updated.

[HansOlsson]

Phone meeting:

• Cascaded in order if multiple ones in one definition. (Similarly as Include etc).
• Only defined once in the top-level library.
• Move to Documentation.

[HansOlsson]

Phone meeting:

• Cascaded in order if multiple ones in one definition. (Similarly as Include etc).
• Only defined once in the top-level library.
• Move to Documentation.

All of that is now handled.

[henrikt-ma]

My primary concern is about how we use the record style definition of the annotation syntax when there could be both a single string and an array of strings. In the long run, I think we'll be happier if making the array case the primary one, and just describe the single string case as a syntactic sugar for an array with a single element. This means that the rest of the text can be written as if there was always an array, rather than describing the array as something exceptional.

[HansOlsson]

My primary concern is about how we use the record style definition of the annotation syntax when there could be both a single string and an array of strings. In the long run, I think we'll be happier if making the array case the primary one, and just describe the single string case as a syntactic sugar for an array with a single element. This means that the rest of the text can be written as if there was always an array, rather than describing the array as something exceptional.

I have done that, even if I don't think it makes it clearer and easier to understand.

[henrikt-ma]

Looks good to me, and in agreement with #3409 (comment).