Postprocessing of M2Doc Documents by Visual Basic


descriptions of Capella model elements may contain images. If such descriptions are included in a M2Doc template using M2DocHTMLServices the images do not scale to the page width. They stick out of the page and their size remains unchanged even if the original images in the description are resized. May be this can be changed by improving M2DocHTMLServices?

Another approach to solve this is to use a Visual Basic macro to resize all images in the document to fit the page width. Such kidn of postprocessing may be usable and more feasible also in other situations, that would otherwise be very hard to solve using (today´s) m2doc. Has anybody used this approach already?

Interesting to know would be if and how the people invoked the macro(s). Ideally, they would be invoked automatically just after the actual generation finishes. In manual mode but also if CLI is used to generate the document.


This is a limitation of the M2DocHTMLServices. The pixel size of the HTML image need conversion to the MS Word unit but I’m not sure what unit it should be. There is a TODO in M2DocHTMLServices.

You can also write a Java service that call the fit() service if the MElement is a MImage.

edit: after reading the code no conversion is needed here, all values are in pixels. I will fix that.

The fit() ImageService uses pixels, so I am not sure why you need a conversion to a unit. Could the image be resized to the page width when inserting it? A default page width could be computed using the most common screen DPI (90 or so), screen resolution (may be 1920x1080) and A4 page size. Or a variant of fromHtmlBodyString could be added with an additional parameter – width and height of images in pixels as in fit() ImageService.

You are right, the conversion happens later when inserting the MImage. I’ll fix this so the defined size in the HTML will be applied in the output document.

I made a patch.
The patched version is available using the nightly update site.

Thanks Yvan for the very quick remedy, indeed, we´ll test it. There is still a risk that this approach will not suffice, because if we set a page fitting width (e.g. 500) in the fit()in the template and we use the same value in the Capella description (properties of the image), in the latter our image is too small to be legible.

Also related to this topic (M2DocHTMLServices and postprocessing) are the following 2 issues:

  1. The description of an element can also contain tables, which have caption. The tables are included OK, when fromHTMLBodyString is used. But their caption (attached screenshot) is ignored even if it is visible in the description.
  2. It seems, that the fields of the freshly generated Word document are not updated. E.g. the TOC is not, which would be a problem, of course. Does m2doc automatically update all fields at the end of the generation?

You have an option for this in the .genconf file. You can set the option UpdateFields to true.

When the document will be opened in MS Word the user will be asked if he want to update the document.

Yes, but unfortunately it suffers from another bug: it cannot be changed to true (the default is false, although it should be true imho). Everytime it is edited, a new option is created instead without a name. It also cannot be removed.

I think there is a bug here. As a workaround, you can edit the genconf file using a text editor.

We have installed Nightly Build of 25.02. ( Version ), that includes the patch, doesn´t it? But the images still stick out across the page borders as they did before.

The patch reuse the size of the image defined in the HTML, for instance:

<img src="Mona_Lisa.jpg" width="20" height="60">

But this size can still be too big to be inserted inside the word document.

You either need to write your service that will call fit() for instance on instances of MImage on a List or wait for this feature to be implemented:

So you can write something like:

....fromHTMLBodyString()->select(e | if e.oclIsKindOf(m2doc::MImage) then, 200) else e endif)

OK, and for when the feature (release 3.1.2) is planned?

In our doc we use fit(600,500) for an image of a diagram that fits the page well. In the description the images have image properties containing width 518 and height 480. But they still stick out by more than a half of their size across the page. So there is probably still some issue with the patch or the buiild mentioned does not contain the patch :wink:

Yes, after changing the value of UpdateFields in geconf XML to true, in Capella it is still displayed as false, but when the document is generated a prompt asks about if the fileds should be updated and, if chosen so, they are updated, indeed. (@plm).

The TOC is ok, but, strangely enough, a reference to a Figure works only if not updated - when updated, it simply disappears.

This looks like a bug. Can you open a new issue with a minimal reproduction template here ?

This might not even be related to m2doc, because it occurs also when normal Word references to captions are used, as illustrated in the attached example. The captions do not contain m2doc code. Do you think m2doc is involvedBUG_ReferenceDisappearsAtFieldUpdate.docx (64.0 KB) ?

Any feedback on this topic?

I wrote a test case for this issue and I think M2Doc is removing the fields used by MS Word to identify references. The table of reference is still there but no references a found. I created this bug:

After double checking the new tests, the bug you encounter is not reproduced. You can find a working example here.

If you still have a bug, you can report it with a reproduction test case here.

The working example contains just TOC references. Have you tried the REF references also, as in the example I have uploaded 4 days ago? If they work for you, I will have to investigate more.

Copyright © Eclipse Capella, the Eclipse Capella logo, Eclipse and the Eclipse logo are Trademarks of The Eclipse Foundation.