Unspecified HTML anchor in modelica URI needs clarification #2445

beutlich · 2019-11-03T19:04:16Z

It does not seem possible to refer to HTML anchors within the modelica URI, see the following proof of concept, which does not work in Dymola 2020, SimulationX 4.0 or WSM 12.

model Test_Anchor "PoC for HTML anchor"
  annotation(
    Documentation(
      info="<html>
<p>See <a href=\"modelica://ModelicaReference.ModelicaGrammar#import_clause\">import_clause</a> in the Modelica Grammar.
</p></html>"),
    uses(ModelicaReference(version="3.2.3")));
end Test_Anchor;

HansOlsson · 2019-11-04T09:03:42Z

I would say that this wasn't part of the design, since the specification says:

Together with scheme “Modelica” the (URI) fragment specifiers #diagram, #info, #text, #icon may > be used to reference different layers. Example:
<a href="Modelica://MultiBody.Joints.Revolute#info">Revolute</a>

I don't see any indication that other fragments should be supported in the current specification.

Obviously it would still be a good idea to support both layers and parts like this - we just need to avoid ambiguities; and ensure that it goes together with some minor cleanup of Modelica URI schemas that is already planned..

maltelenz · 2019-11-05T16:55:24Z

If you replace the / with . in the example model, it will work in SystemModeler 12.1. We had a bug with anchors in general in 12.0.

I don't see a reason why this shouldn't work.

model Test_Anchor "PoC for HTML anchor"
  annotation(
    Documentation(
      info="<html>
<p>See <a href=\"modelica://ModelicaReference.ModelicaGrammar#import_clause\">import_clause</a> in the Modelica Grammar.
</p></html>"),
    uses(ModelicaReference(version="3.2.3")));
end Test_Anchor;

beutlich · 2019-11-05T18:44:33Z

True, the PoC model needs to be corrected. I edited above.
There are ambiguities if the anchor is named #diagram, #info, #text, or #icon.

maltelenz · 2019-11-06T07:38:15Z

I agree there are ambiguities for #diagram, #info #text and #icon. In my opinion, we would be fine with defining those to always have the specific meaning of referencing the layers. If you want to use anchors in pages, you can then name them something different.

HansOlsson · 2019-11-06T08:55:32Z

I just realized that this is actually a bit more complicated in general:

In Dymola (and several other tools) we also generate HTML-files from the documentation (with several options). That implies that we combine documentation-layers from several classes; and in turn that means that if several classes have identical anchors we would need to do something special.
Not impossible to handle - just something that needs to be considered; and I believe some library developers will in fact use the same anchor-names in many classes (e.g. "references", "asumptions").

Additionally Dymola (don't know about other tools) allow linking to components in diagram, icon and text-layers (the syntax is #diagram$e.f:g,h for selecting components g and h in the sub-component e.f; I'm not saying that the syntax is ideal). It seems as if this sort of corresponds to the anchors in the info-layer in some way - so it would be good if they were considered together.

(And then there are the new figures.)

And finally we have parts of the generated HTML that it may be natural to link to - e.g. table of parameters.

maltelenz · 2019-11-06T10:05:59Z

In SystemModeler, we don't currently export single HTML pages with multiple class documentation layers in it. We currently only do one page per class, like this: https://reference.wolfram.com/system-modeler/libraries/Modelica/Modelica.html
I think if tools combine classes, maybe it needs to be up to the generator in the tool to unique-ify anchors by modifying them in the generated result? I don't see another way around that.

Additionally Dymola (don't know about other tools) allow linking to components in diagram, icon and text-layers (the syntax is #diagram$e.f:g,h for selecting components g and h in the sub-component e.f; I'm not saying that the syntax is ideal). It seems as if this sort of corresponds to the anchors in the info-layer in some way - so it would be good if they were considered together.

I agree.

And finally we have parts of the generated HTML that it may be natural to link to - e.g. table of parameters.

I don't think the specification should get involved in this.

henrikt-ma · 2019-11-06T10:42:18Z

I would say that this wasn't part of the design, since the specification says:

Together with scheme “Modelica” the (URI) fragment specifiers #diagram, #info, #text, #icon may > be used to reference different layers. Example:
<a href="Modelica://MultiBody.Joints.Revolute#info">Revolute</a>

I don't see any indication that other fragments should be supported in the current specification.

Obviously it would still be a good idea to support both layers and parts like this - we just need to avoid ambiguities; and ensure that it goes together with some minor cleanup of Modelica URI schemas that is already planned..

Yes, when cleaning this up, I think it would be best to not use fragments for the layers. First, we have the obvious risk of collisions with user-defined anchor names. Second, a fragment appears at the end of the URI, but the layer (or figure) is a selection directly on the model. Since a colon is allowed in the path of a URI, we could do something like this instead to link to the anchor with name name in the documentation of Foo.Bar:

modelica:///Foo.Bar:info#name

This generalizes nicely to hierarchical documentation in the future:

modelica:///Foo.Bar:info/subtopic.html#name

For figures in the future, the fragment could be defined naturally refer to a figure or plot identifier:

modelica:///Foo.Bar:fig#id

svorkoetter · 2019-11-06T13:45:06Z

In SystemModeler, we don't currently export single HTML pages with multiple class documentation layers in it. We currently only do one page per class, like this: https://reference.wolfram.com/system-modeler/libraries/Modelica/Modelica.html

We do the same in MapleSim. We only export multiple classes per page when generating external documentation (i.e. intended for use in a stand-alone web browser).

maltelenz · 2019-11-06T14:54:22Z

We do the same in MapleSim. We only export multiple classes per page when generating external documentation (i.e. intended for use in a stand-alone web browser).

We only export one class per page in that case as well, but I can see why you would like the single page with everything in some scenarios.

svorkoetter · 2019-11-06T15:03:45Z

We only export one class per page in that case as well, but I can see why you would like the single page with everything in some scenarios.

Specifically, in that case we produce one HTML page per package, so the links to non-package classes within the package are all links to anchors.

HansOlsson · 2020-02-19T08:35:48Z

Could keep anchors, but:

Require that user-anchors for modelica:// are unique per package: 1
Just state that user-anchors for modelica:// might be renamed: 2
And user-anchors are supported. Rest abstain.

HansOlsson · 2020-02-19T08:40:52Z

Henrik: Also change predefined fragments from anchor to something else, to avoid ambiguity for figure-fragments.
That should be coordinated with changing from modelica:// to modelica:/// - due to case-issues, see other issues ...
(But this change is independent.)

Note that "fragment identifier" is the technical name for the id following # https://en.wikipedia.org/wiki/Fragment_identifier Whereas anchor is the anchor-point in the hypertext: https://en.wikipedia.org/wiki/HTML_element#Anchor Closes modelica#2445

* Allow user defined fragments, and state that they may be renamed. Closes #2445 * And follow URI-recommendation and use lower-case ("modelica://") Co-authored-by: Dietmar Winkler <dietmar.winkler@dwe.no>

beutlich mentioned this issue Nov 4, 2019

Update ModelicaReference to latest Modelica specification 3.4 modelica/ModelicaStandardLibrary#2820

Closed

HansOlsson modified the milestones: Design100, Design101 Feb 11, 2020

HansOlsson added the decided A decision has been made (label added before the spec is changed) label Feb 19, 2020

HansOlsson mentioned this issue Mar 16, 2020

Uri clarification #2531

Merged

HansOlsson closed this as completed in #2531 Mar 19, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unspecified HTML anchor in modelica URI needs clarification #2445

Unspecified HTML anchor in modelica URI needs clarification #2445

beutlich commented Nov 3, 2019 •

edited

Loading

HansOlsson commented Nov 4, 2019

maltelenz commented Nov 5, 2019

beutlich commented Nov 5, 2019 •

edited

Loading

maltelenz commented Nov 6, 2019

HansOlsson commented Nov 6, 2019

maltelenz commented Nov 6, 2019

henrikt-ma commented Nov 6, 2019

svorkoetter commented Nov 6, 2019

maltelenz commented Nov 6, 2019

svorkoetter commented Nov 6, 2019

HansOlsson commented Feb 19, 2020

HansOlsson commented Feb 19, 2020

Unspecified HTML anchor in modelica URI needs clarification #2445

Unspecified HTML anchor in modelica URI needs clarification #2445

Comments

beutlich commented Nov 3, 2019 • edited Loading

HansOlsson commented Nov 4, 2019

maltelenz commented Nov 5, 2019

beutlich commented Nov 5, 2019 • edited Loading

maltelenz commented Nov 6, 2019

HansOlsson commented Nov 6, 2019

maltelenz commented Nov 6, 2019

henrikt-ma commented Nov 6, 2019

svorkoetter commented Nov 6, 2019

maltelenz commented Nov 6, 2019

svorkoetter commented Nov 6, 2019

HansOlsson commented Feb 19, 2020

HansOlsson commented Feb 19, 2020

beutlich commented Nov 3, 2019 •

edited

Loading

beutlich commented Nov 5, 2019 •

edited

Loading