[details] Open the external documents referenced by an element from the Details view

[kkkk1258999]

Context
When a model is used to trace requirements back to the documents they come from, laws and regulations, internal rules, contracts, design documents, test reports, being able to reach those documents from the model matters as much as the requirements themselves: a requirement without its source cannot be reviewed.

Today a URL can be stored in a model, in the Documentation of an element for instance, but the Details view renders it as plain text in a text area, so it can only be copied and pasted into a browser by hand. There is no widget in SysON rendering a link: LinkDescription does not appear anywhere in SysMLv2PropertiesConfigurer, and searching the repository for a link widget returns nothing.

Expected
From the Details view of an element, being able to open the documents it references, in a new browser tab.

Notes
Sirius Web already provides the widget: FormFactory#createLinkDescription exists in sirius-components-view-form, so this looks like using a widget that is already there rather than building one.

What I am unsure about is where the URL should come from, since SysML v2 has no standard notion of an external link. A few options I can see:

the Documentation of the element, detecting the URLs it contains;
a dedicated attribute, by convention on its name or its type;
a metadata, the way a requirement derivation is identified by the #derivation metadata of the RequirementDerivation library.
I would rather follow whatever you consider right here, or whatever is already planned. If there is a direction you would like to take, I am willing to work on it.

For reference, this comes from using SysON to trace which internal rules and processes satisfy the requirements derived from a law: the requirements and their relations are now fully usable in the diagrams, but the documents they are derived from are still out of reach from the model.

[AxelRICHARD]

Hello @kkkk1258999,

Thank you for raising this issue.
I understand your need.

We would like to let users edit their documentation from the Details view so just replacing the TextArea widget by a Link widget from SiriusWeb is not what we want.
I'm not in favor of a dedicate attribute neither, or a metadata.

SiriusWeb also provides a RichTextEditor widget, which seems more appropriate. It relies on https://lexical.dev/.
The current configuration of the RichTextEditor widget does not enable the "link" capacity in the widget.

If this RichTextEditor widget with the "link" capacity is something that would suit your needs, we could consider proposing an evolution in SiriusWeb and then changing the widget used for the documentation in the Details view from TextArea to RichTextEditor.
First tell me if this would suit your needs, then I will contact the SiriusWeb team to see if it possible to update the widget and will also talk with the rest of the SysON team to see if the RichTextEditor could replace the the TextArea widget for documentation in the Details view.

Regards,

[kkkk1258999]

Thank you for looking at this, and for the counter-proposal.

Yes, a RichTextEditor with the link capability would suit our needs, and I agree it is a better direction than the ones I listed.

Keeping the documentation editable matters to us too: the people writing the traceability model are the ones who know which document a requirement comes from, so they need to add and change those references themselves. Being able to put several links in the documentation of a single element also fits, since a requirement is often justified by more than one document, a law and the internal rule interpreting it for instance. And it does not require inventing an external link concept that SysML v2 does not have, which was what I was least comfortable with in my own suggestions.

One thing I would like to check
The documentation body is serialized into the SysML v2 text as doc /* ... */, so whatever markup the RichTextEditor produces ends up in the exported .sysml file.

We keep the exported text under version control, so the round trip matters to us as much as the Details view does. It would be good to make sure that a documentation containing links survives export and re-import, and that the markup stays readable enough in the text form, since the .sysml file is also read and reviewed by people.

I mention it now because it may be worth raising with the SiriusWeb team at the same time as the link capability, rather than after the widget is changed.

[AxelRICHARD]

@kkkk1258999 you are absolutely right, it is important to have this constraint in mind.

[AxelRICHARD]

Hello @kkkk1258999,
I created an issue (eclipse-sirius/sirius-web#6824) and provided a PR (eclipse-sirius/sirius-web#6825) in SiriusWeb to enable the "link" option in the RichTextEditor widget.
Once merged and released in Sirius Web and this release consumed in SysON, would you be interested in providing a pull request that changes the widget used for the documentation in the SysON Details view (from the current TextArea widget to the RichTextEditor widget)? And the update of the import/export to properly handle markdown characters to escape?

Regards,

[AxelRICHARD]

About the concern of the markdown import/export, I would say that it can be stored in a SysON Documentation body and exported/imported as textual SysML.
It is preserved as plain text inside a SysML block comment:

  doc /* ## Heading

  - **bold**
  - `inline code`
  */

Markdown is not itself interpreted by the SysML exporter/importer; characters such as #, *, _, backticks, brackets, parentheses, quotes, and backslashes do not need escaping.

The important exception is */: it closes the SysML block comment, so it cannot appear literally anywhere in the documentation body. There is currently no automatic escaping for it—rewrite it, for example as * /.

One minor round-trip caveat: import trims whitespace immediately inside the outer comment delimiters, so do not rely on leading or trailing blank space being preserved exactly. Internal newlines and normal Markdown formatting are preserved.

[kkkk1258999]

Thank you for opening eclipse-sirius/sirius-web#6824 and for providing the pull request already, and for the detailed analysis of what survives the round trip.

Yes, I am interested in providing both pull requests.

On the */ escaping
That part does not depend on the SiriusWeb release, so I would rather do it first, in its own issue and pull request, the way the export of the metadata of the inline connector ends (#2419) was done before the tool creating a derivation (#2428).

It is not only a rich text concern: getCommentBody concatenates the body between /* and */ without any escaping, so a documentation containing */ already produces a .sysml file that no longer parses. Documenting a piece of code is enough to run into it today. Switching the widget will make it more likely, but the defect is there already, and fixing it separately keeps that pull request small and reviewable, and lets it land whenever it suits you rather than waiting for the widget.

I would need your opinion on one point though: what the escaped form should be. Rewriting */ as * / changes the text the user typed, which I would rather avoid since the documentation is also read from the exported file. If SysML v2 has nothing for this, I can propose something in the issue and let you decide.

Shall I open an issue for it?

On the widget change
For the change from TextArea to RichTextEditor in the Details view, I will wait until the SiriusWeb release with #6825 is consumed in SysON, and I will follow the issue to know when that happens. Just tell me if you would rather open the issue for it yourself.

Thank you for taking this forward.

[AxelRICHARD]

Hello @kkkk1258999, sounds good to me!
On the */ escaping part, yes this can be done whenever you want.

I would need your opinion on one point though: what the escaped form should be. Rewriting */ as * / changes the text the user typed, > which I would rather avoid since the documentation is also read from the exported file. If SysML v2 has nothing for this, I can propose > something in the issue and let you decide.

Shall I open an issue for it?

yes please

On the widget change
For the change from TextArea to RichTextEditor in the Details view, I will wait until the SiriusWeb release with #6825 is consumed in
SysON, and I will follow the issue to know when that happens. Just tell me if you would rather open the issue for it yourself.

No we can use this issue, it's fine

Thank you!