[details] Edit the documentation as rich text without rewriting existing bodies

[kkkk1258999]

Follow-up of #2436, where @AxelRICHARD set out the compatibility policy this issue is meant to carry out.

Context

Making the Documentation property of the Details view a rich text editor is what lets a model reach the documents it refers to, which is what #2436 asked for. Swapping TextAreaDescription for RichTextDescription in SysMLv2PropertiesConfigurer#createDocumentationWidget is enough to get the link toolbar, and I have that working on a branch. It is not enough to ship, because the widget also decides how an existing documentation body is read and what is written back.

Documentation bodies written before this change are plain text. Some of them contain characters that markdown gives a meaning to, and nothing in the stored body says whether a * was meant as a character, as a comment decoration, or as a list marker.

Expected behaviour

Existing documentation keeps its stored text until the user deliberately edits it, and editing it as rich text is an explicit choice.

1. Existing and imported bodies are preserved. No automatic migration, no removal of leading *, no insertion of markdown escapes.
2. A Source / Rich text choice. Source edits the stored body directly. Populated documentation opens in Source; the user selects Rich text to have the body interpreted as markdown. This avoids having to detect the format or add an attribute to the model.
3. Viewing never writes. Opening the documentation, switching modes, following a link, or focusing the editor and leaving it must preserve the body exactly. Markdown normalisation on its own must not trigger a save.
4. Rich text edits may normalise markdown, and say so. Entering that mode should make clear that saving can change markdown syntax and layout. Switching back without editing keeps the original source. Choosing Rich text does not silently repair a body such as the Batmobile one.
5. Import and export stay out of it. No markdown escaping or unescaping in those layers. The handling of the block comment terminator from [textual export] A documentation containing */ produces a .sysml file that cannot be parsed #2447 / [2447] Escape the block comment terminator when exporting a comment body #2448 is a separate constraint of the textual syntax and remains as it is.

What I measured

On main (0e5bae8) with Sirius Web 2026.9.2 and the widget swapped locally.

Writing stores markdown. Typing See https://example.org/spec and note * the star stores the body See https://example.org/spec and note \* the star. Per #2436 this is the intended representation and import/export must leave it alone.

The Batmobile template's own documentation is re-read as a list. Its body starts each line with *:

* The book "Dont Panic - The Absolute Beginners Guide to SysML v2" by Tim Weilkiens and Christian Muggeo
     * uses the Batmobile as a fictional example.
     *

The rich text editor parses those as markdown list items and displays six nested bullets instead of the paragraphs that were written. This is the case point 1 and point 4 above are about.

Focusing and leaving the editor does not rewrite the body. I measured this because it is the cheapest way for point 3 to be broken: open the Batmobile package, focus the editor, place the caret in the body, leave without typing. The exported model is byte-identical before and after (140 557 bytes both times), and the body still begins with * The book with no backslash added. So the current widget does not save on blur alone — point 3 is a property to keep, not a defect to fix.

Scope note: the Requirements Table

RTVTableDescriptionProvider edits the same documentation body through newCellTextareaWidgetDescription (RTV-CellDescription-Documentation), so the Requirements Table edits as plain text while the Details view would edit as markdown. Those are the only two paths that write a documentation body, the other being FormMutationElementService#setNewDocumentationValue behind the Details widget.

Whether the table should follow, stay as it is, or be covered by the same mode choice is worth deciding here rather than discovering later. At minimum the difference should be documented.

Dependency

This needs the Source / Rich text choice to exist in the Sirius Web rich text widget. @AxelRICHARD said he would open the Sirius Web issue for it; this issue is the SysON side, to be done once that support is released and consumed in SysON.

Acceptance criteria

• Documentation containing markdown characters, leading *, and links survives export and re-import unchanged.
• Opening documentation, switching between Source and Rich text without editing, and focusing then leaving the editor all leave the stored body byte-identical.
• The Batmobile template's documentation is displayed as written until the user chooses Rich text for it.
• A link inserted in Rich text survives export and re-import, and can be opened, edited and removed.
• The behaviour of the Requirements Table documentation cell is settled and documented.

Out of scope

• Markdown escaping or unescaping in the SysML import/export layers.
• The block comment terminator handling from [textual export] A documentation containing */ produces a .sysml file that cannot be parsed #2447 / [2447] Escape the block comment terminator when exporting a comment body #2448.
• Any automatic migration of existing documentation bodies.

I am happy to provide the SysON pull request once the Sirius Web support is available.