Use of m:bookmark for cross references

Document Generation
1

Hi all,
I am using M2Doc to generated a System Design Document, and I would like to share my experience in the use of m:bookmark.
While generating a traceability matrix of requirements toward Capella elements, I tried to use the pair of tags bookmark and ‘link’, but I was not satisfied by the lack of control of the references.

Please find below a generic section of the document associated to a Logical Component.

image

I am embedding in the section heading a bookmark based on the uuid of the element within the model.
The following template extract generates the traceabilty matrix of the set of requirements

image
image921×474 19.6 KB

Please note the nested fields for generating references to bookmarks

Sec. { ref {m:tgt.target.id} \n\h}

I hope that such hint could be useful for Capella users.

1 Like
2

Thank you for sharing you experience. One can also use the link services to create bookmarks/references/links. bookmarks and references created this way will be checked for duplicated ID and references to missing bookmark.

3

I tried to use link Services, but while using them I was not able to get references to the section and page of the document. There are also some problem with formatting, since link services seem to inherit the style of the bookmarked text.
I hope to avoid references duplication using the Capella element uuid.

4

I found also an issue in the autocompletion feature of the M2Doc interpreter.

The Requirements::Attribute EClass can be selected using autocompletion, while the IncomingRelation has a different naming and is contained in the package CapellaRequirements with autocompletion not working.
My suspect is that this is due to some issue in the deprecation of old Capella Requirements in favour of the Requirement VP addon.

5

You might need to add the nsURI of the CapellaRequirements package to your template using the template properties wizard:

http://www.polarsys.org/capella/requirements

You will need to reload the template in the M2Doc interpreter view using the refresh button to the change to take place.

Also the name of the EClass is CapellaIncomingRelation.

6

Hi Yvan,
I meant CapellaIncomingRelation. I also checked the list of imported nsURI and http://www.polarsys.org/capella/requirements is already added.

image
image592×151 3.47 KB

Please find below the list of suggested completions

image
image620×582 22.7 KB

Regarding link services, a possible improvement would be the capability of generating page, sections, numbered items references.

7

There is an issue open for the section and page number in references.

For the content assist, the CapellaIncomingRelation is not in the Requirements EPackage but in CapellaRequirements. That a bit confusing but you should have it in the list of proposals by typing CapellaRe using the EPackage name or directly CapellaIn using the EClass name.

Let me know if it helps, it could also be a bug…

8

Hi Yvan,
if I write Cap the autocompletion works. However the behaviour is a little bit weird, since autocompletion scans several namespaces while writing re, but not CapellaRequirements.

9

The filter use camel case matching on the EPackage name or the EClassifier name. For instance EDT will match something like E*D*T*. But there is no * at the beginning of the match. The * at the beginning has been added to AQL 8.x but M2Doc is still using AQL 7.x.

1 Like