Aanroep van Imvertor OS

De add-in roept een gecompileerde release van Imvertor OS aan. Hierbij worden command-line parameters meegegeven. Dit zijn feitelijk properties, die het imvertor proces sturen. Voor uitleg van properties, zie elders.

Een van deze command line parameters (properties) is documentorfile. Dit is het file pad van de ZIPfile of folder waarin de hele modeldoc folder is opgenomen. Dus bijv.

Imvertor -documentorfile=“D:/Imvertor-data/modeldocs/zip/Armatiek.zip” [...meer parms...]

of

Imvertor -documentorfile=“D:/Imvertor-data/modeldocs/Armatiek” [...meer parms...]

Het pad wordt op dezelfde manier door Imvertor OS opgelost als het bepalen van de locatie van de opgeleverde XMI (zip)file.

Dit file Armatiek.zip of de folder bevat een of twee folders: ./modeldoc en eventueel ./sections. De modeldoc folder bevat minimaal één folder met de naam van het model (letterkast gevoelig!). Het volgt de structuur zoals verderop is beschreven.

Het opleveren van deze zipfile of folder is niet relevant wanneer niet is aangegeven dat de documentor module moet worden geactiveerd. Dat doet de gebruiker met een andere property:

createofficevariant = documentor

De Imvertor SaaS add-in leest die properties echter niet uit, maar stelt hoe dan ook een zipfile samen als in de add-in een bestaand pad is opgegeven naar een modeldoc folder. Zie de dialoog in de Imvertor settings:

Properties voor het starten van Documentor

Als je Documentor wilt activeren moet een aantal properties zijn gezet. Dat zijn deze:

Createoffice        = html
Createofficevariant = documentor
Fullrespec          = yes
#optioneel:
Createofficeanchor  = name
Createofficemode    = click
Officename          = index
Passoffice          = none

Dus gebruik de properties: Createoffice, Createofficevariant, Fullrespec, Createofficeanchor, Createofficemode, Officename, Passoffice.

Je kunt deze properties zetten in een properties file, of laten vastleggen op de server, zodat deze voor iedereen standaard worden ingesteld. Vraag in dat laatste geval je Imvertor contactpersoon om dit te laten vastleggen.

Als je niet met de addin (dus niet vanuit EA) werkt moet je ook opgeven:

Documentorfile = [pad naar modeldoc folder] 
# bijv. D:\imvertor-data\modeldocs\armatiek

Of:

Documentorfile = [pad naar zip file]
# bijv. D:\imvertor-data\modeldocs\Armatiek.zip

Je kunt dus een pad naar een folder of een zip meegeven, waarin dan de modeldoc folder staat.

Invoegen van subdocument

In het modeldocument (zoals in alle andere documenten trouwens) kun je een ander document invoegen d.m.v.een include statement. Bijvoorbeeld, een sectie subdocument.docx kun je invoegen met:

Dit subdocument.docx kan zich bevinden in de sections folder of in de hoger gelegen, gemeenschappelijke ..\sections folder. Beide folders worden dus doorzocht bij het ophalen van het subdocument.

Let op: de MsWord stijl van de alinea is “Extension”.

Folder modeldoc

In deze folder wordt per model een folder opgenomen met de naam van dat model. Daarin bevindt zich vervolgens een MsWord bestand met exact dezelfde naam (van het model), dus bijvoorbeeld:

 …\modeldoc\Fietsenwinkel\Fietsenwinkel.docx

Het informatiemodel heeft de naam Fietsenwinkel.

Binnen deze folder kan een folder met de naam sections voorkomen. Deze folder bevat dan hoofdstukken die in een apart document worden beheerd. Dat document kan dan dus ook een eigen versiegeschiedenis hebben. Vanuit het Fietsenwinkel document wordt dan verwezen naar dat document op basis van de documentnaam. Zie elders.

Folder modeldoc/[modelnaam]/exclude

Bij het werken aan een modeldocument worden bestanden gebruikt die niet gepubliceerd moeten worden, maar wel nodig zijn voor de documentatie. Voorbeeld is een grafisch bestand voor bewerking, waar een plaatje uit wordt geëxporteerd dat wél een plek heeft in de documentatie. Dit is de plek waar je deze bestanden kwijt kunt. NB. de dat folder wordt niet uitgelezen door documentor.

Folder modeldoc/[modelnaam]/include

In deze folder kun je bestanden opnemen waarnaar je verwijst vanuit MsWord. Deze bestanden komen ook als zodanig terug in de Respec documentatie.

Als het plaatjes betreft worden deze als plaatje opgenomen i het document.

Als het andere bestanden betreft (zoals zip bestanden) wordt er een referentie naar gemaakt. De lezer kan erop klikken om het te openen of te downloaden.

Folder modeldoc/[modelnaam]/sections

In deze folder neem je secties op (sub-documenten zoals besproken). Deze zijn bedoeld voor het model zelf, en worden niet gedeeld over meerdere modellen. Deze folder bevat typisch documenten die door andere mensen worden bewerkt, die dus geen toegang (mogen) hebben tot het model document zelf.

Folder modeldoc/sections

In deze subfolder van de modeldoc folder worden alle secties (sub-documenten) opgenomen die méérdere modellen gemeenschappelijk hebben. Dat kan bijvoorbeeld een beschrijving van de toegepaste modelleringstechniek betreffen, of informatie over het bedrijf of instelling.

Vanuit een willekeurig document kun je verwijzen naar zo’n MsWord document, opnieuw op basis van de naam van dat file. Het wordt op de plek van verwijzing ingevoegd.

Versies van documenten

De documenten kunnen in meerdere versies beschikbaar komen. Documentor (noch de add-in, noch de Modeldoc folder) is bekend met “versies”. Wanneer twee versies van een document naast elkaar beschikbaar moeten zijn is het raadzaam dit in de naam van een document terug te laten keren. Bijvoorbeeld

Intro-v1.docx
Intro-v1.1.docx

Natuurlijk is het raadzaam de documenten (net als andere beheerde gegevens) in een versiebeheersysteem onder te brengen. Het is bijvoorbeeld mogelijk de documenten in SVN of GIT op te nemen. De add-in is daarvan niet op de hoogte en zal alleen toegang hebben tot je lokale werkversie.

Karakter stijlen

Allerlei soorten karakterstijlen worden ondersteund zoals Bold, italic, bolditalic, en onderstreept. Deze tekst is doorgehaald. Je kunt ook van font wisselen, zoals courier en courier bold. Ook kun je tekst met daarin Programmacode maken. Aan programmacode kan een speciale verwerking worden gebonden; dit is per soort document uit te werken.

Dit is een TODO openstaande taak. (De TODO wordt automatisch gehighlight; we zoeken dan naar de letterlijke karakters “T,O,D,O”.)

Ook kun je lopende tekst typeren, zoals een voorbeeld, programmacode, citaat, of een waarschuwing.

Ook kun je een tekstje als “inline” opmerking markeren. Zoals deze.

Linking en referenties

Het gemakkelijkste is te laten zien hoe links kunnen worden gemaakt en hoe deze worden verwerkt.

• Dit is een link naar internet locatie.

• Dit is een referentie naar het onderdeel in dit document dat gaat over Programmacode (op basis van titel ID). Deze link is gelegd door te kiezen voor Koppeling/Plaats in dit document en dan te kiezen voor de sectie “Programmacode”.

• Dit is een referentie naar het hoofdstuk over secties en subsecties (op basis van in metadata toegekende ID, nl. “Subsecties”.) Deze link is gelegd door te kiezen voor Koppeling/Bestaand bestand of webpagina en dan “#Subsecties” in te voeren. Let op: deze aanpak is vooral van belang als je wilt verwijzen naar een sectie in een ander (sub)document dat een plek krijgt in de Respec publicatie.

Afkortingen kun je door de tool laten oplossen: De KLM gaat hard achteruit. Het MIM is een mooie standaard. En ABBREV? ONB is een onbekende afkorting. Zie elders.

Structuur

Ook hier laten we zien hoe je lijsten kunt maken. Een niet geordend lijstje

• Item 1

• item 2

En een geordend lijstje

1. Item 1

2. item 2

En een geordend lijstje met daarin nog een geordende en een bulleted list.

1. Item 1 heeft bulleted list

   • Item 11

   • Item 12

2. item 2 heeft genummerde lijst

   1. Item 11

   2. Item 12

Een lijst met in een item met meerdere alinea’s is lastig: dat kan alleen als de alinea’s worden gescheiden met een soft return.

• Planstatus
  Vastgesteld

• Uitvoeringstatus
  Nader te bepalen

Dat ziet er zo uit in MsWord:

Programmacode

XML code voorbeeld, rol is example:

Programmacode heeft een formaat (bijv. xml) en een rol (bijv. example). Het formaat is niet verplicht. In ReSpec omgeving wordt het formaat afgeleid van de code die is opgevoerd (d.w.z. herkend). Maar je kunt het ook expliciet maken. Afhankelijk van je configuratie kan ook HighlightJS worden ingezet.[1]

De rol kan worden gebruikt om de programmacode te voorzien van een andere weergave, zoals een “icon” in de marge.

Java code voorbeeld, rol is niet opgegeven:

public class ChainAnalyzer {
 protected static final Logger logger = Logger.getLogger(ChainAnalyzer.class);
 public static void main(String[] args) {
   //more
 }
}

Default code voorbeeld, rol is example:

Default code maar niet als example aangemerkt, maar gewoon als stukje programmacode:

C:/temp/sample.xml

Dit is het eind van dit stukje programmacode.

Plaatjes

Hier nemen we een plaatje op met daarin de bron gekoppeld. Dit is een bestand met daarin het (in dit geval erg grote) plaatje. Het plaatje is geplaatst in de include folder.

De include folder kan ook weer subfolders bevatten. Echter, alle plaatjes (en andere bestanden) moeten daarbinnen altijd een unieke naam hebben. Als twee bestanden dezelfde naam hebben wordt dit als fout gemeld.

Plaatjes kun je ook gewoon met drag-and-drop opnemen in het document, of via copy/paste:

Als een plaatje erg klein is neemt dat niet meer de volledige breedte van de pagina in:

Ergens in je document kun je de lijst van afbeeldingen opvragen. Dat gaat via de extensie:

Het ook mogelijk een plaatje op te nemen zonder de “plaatje” stijl. In dat geval wordt het plaatje niet gecentreerd en geschaald en komt het niet in het overzicht van plaatjes. Er is ook geen onderschrift bij mogelijk.

Een voorbeeld staat hierboven. Omdat dit veelal niet de beoogde wijze van opnemen van plaatjes is, wordt gewaarschuwd door Imvertor als het optreedt.

Tabellen

Hieronder start een tabel met drie kolommen, een header, en één rij. Zoals je ziet kun je speciale constructies plaatsen in de tabel.

C:/temp/Voorbeeld1.xml

Tabellen kun je typeren. Hierdoor kan een speciale afhandeling worden gerealiseerd. Dit met name om tabellen te gebruiken als “tekentool”. We noemen de tabel dan een matrix (een rasterwerk voor plaatsing van gegevens).

Matrix1 is een bepaald type matrix. Dit wordt online weergegeven als:

De lijst van matrices is beschikbaar en uitbreidbaar.

Blokken tekst

Je kunt alinea’s typeren, waardoor deze een speciale weergave of afhandeling krijgen. Deze boxjes kun je niet nesten, omdat zij gebaseerd zijn op alinea-stijlen.

Dit is een opmerking zie geen aandacht mag vragen, een “aside”.

Dit is een voorbeeld-boxje (stijl Voorbeeld):

Dit is een waarschuwing-boxje (stijl LetOp,).

Dit is een waarschuwing-boxje (stijl LetOp, met Format: warning. Er zijn meerdere typen te configureren).

Dit is een citaat (stijl Citaat):

Nu een quote met een internet bron (hidden, zet “alles weergeven” aan).

Secties en subsecties

Introductie van onderdelen door middel van kopjes. Dit hoofdstuk zelf heeft de ID “Subsecties”. Dit is toegekend in een Metadata alinea.

Secties die niet gepubliceerd mogen worden

Je kunt aangeven dat een sectie niet gepubliceerd moet worden. Het gaat dan om tekst die alleen voor de lezers/auteurs van het oorspronkelijke document zelf bedoeld is.

Je kunt zulke secties markeren als “niet verwerken”, als volgt:

Met Proces: remove wordt de sectie vroegtijdig verwijderd.

Invoegen van speciale waarden

Het is ook mogelijk speciale waarden in te voegen, door middel van en extension stijl op een naam. Een voorbeeld is de huidige datum en tijd: 2026-04-08 om 18:53:25 (niet letterkast gevoelig). Hieronder zie je welke waarden je kunt laten invoegen.

NB deze waarden zijn alle zgn. “Xparms”. De waarden van de meeste Xparms vind je in het bestand parms.xml in de opgeleverde Imvertor run ZIP.

Invoegen van afkortingen

Een afkorting kan ter plaatse worden gedefinieerd. Voorbeeld is de afkorting voor KLM en voor MIM.

Alleen de laatst aangetroffen afkorting wordt opgenomen in het respec document. Zo blijkt de afkorting voor MIM overeen te komen met de laatst aangetroffen interpretatie: Metamodel Informatiemodellering.

Je hoeft een afkorting (zoals MIM) maar éénmaal van de abbrev stijl te voorzien; in de rest van het document wordt het dan voorzien van een verklarende titel.

NB zo ziet dit eruit in MsWord.

Let op: de MsWord stijl van de alinea is “Extension”.

Ergens in je document kun je de lijst van afkortingen opvragen. Dat gaat via de extensie:

Invoegen van “downloads”

Het kan zijn dat er downloads zijn die typisch behoren bij het (model)document dat je bewerkt. Je kunt deze opnemen in de modeldoc folder binnen de include folder, zoals bij plaatjes is beschreven. In deze handleiding hebben we dat ook gedaan met de sjablonen voor het documentor model-document en sub-documenten.

Een download heeft de vorm van een koppeling naar dat bestand in de include folder.

Ook hier geldt weer: alle bestanden in de include folder moeten altijd een unieke naam hebben. Als twee bestanden dezelfde naam hebben wordt dit als fout gemeld.

Document publicatie URL

Het document wordt gepubliceerd op de volgende plek:

Deze URL is samengesteld uit de eigenschappen zoals ingevoerd in het Respec klantprofiel en de document eigenschappen zoals hierboven beschreven. Een voorbeeld is:

https://armatiek.nl/doc/imvertor/documentor/0.9

waarbij

• organisationPublishURL = https://armatiek.nl/doc

• publicatie domein = imvertor

• korte naam = documentor

• publicatie versie = 0.9

Document type

Document type keert terug in de kop. De tekstuele waarde kan worden ingesteld. Wordt getoond onder de titel.

Document status

Document status keert terug in kop en linker zijbalk. De tekstuele waarde kan worden ingesteld

Lijst met afkortingen

• KLM Koninklijke Luchtvaart Maatschappij
• MIM Metamodel Informatiemodellering