ReSpec definities

[Gtrouborst]

Issue

ReSpec biedt de mogelijkheid om definities op te nemen. Hier maken we bij Geonovum graag gebruik van. De meeste begrippen staan in het hoofdstuk Gegevensdefinitie, dat Imvertor genereert uit EA. We zijn nog bezig om te bepalen hoe we dit qua styling exact in de documentatie terug willen zien, maar daarvoor is het allereerst nodig om alle begrippen van <dfn> tags te voorzien.

Toelichting

Idealiter, althans zoals bedoeld in de ReSpec-documentatie, staat de definitie direct achter de closing tag </dfn>. Dat is nu (nog) niet haalbaar. Imvertor genereert een tabel waarin het begrip en de definitie elk een aparte rij of kolom zijn. We hechten waarde aan dit format.

Bovendien geven we vanuit het MIM veel meer informatie aan een begrip mee dan alleen een definitie, dus heeft het naar ons idee al meerwaarde als het begrip in de tabel <dfn> tags krijgt. Op die manier kan er zowel intern als extern naar verwezen worden. ReSpec geneert bovendien automatisch een overzicht van alle gedefinieerde termen.

Door <dfn> tags aan een begrip toe te voegen, is het in elk geval mogelijk om naar de tabel te navigeren. Dit brengt een lezer dan tenminste bij het begrip en de bijbehorende metadata, waaronder de definitie. Dit is misschien nog niet het eindstadium, maar al wel een mooie stap voorwaarts.

Voorstel

In overleg met @wilkoquak doen we graag het volgende voorstel: alle begrippen voorzien van <dfn> tags. De tabellen van relaties zien er weliswaar anders uit dan die van objecten en attributen, maar in essentie zien we het als volgt voor ons:

<table style="width: 100%;">
   <colgroup style="width: 30%;"></colgroup>
   <colgroup style="width: 70%;"></colgroup>
   <tbody>
      <tr>
         <th>Naam</th>
         <!-- Op deze plek het begrip voorzien van <dfn> tags -->
         <td><dfn>Bestuurlijk­Gebied</dfn></td>
      </tr>
      <tr>

[ArjanLoeffen]

Even uit IMG:

Rood omcirkeld: dfn?

[Gtrouborst]

Yes! Die term inderdaad.

[ArjanLoeffen]

Moet deze <dfn> voor alle top-constructies worden gegenereerd, dus voor Objecttype, Gegevengroeptype, Referentielijst, etc. (en niet voor attribuutsoorten of relatiesoorten)?

[ArjanLoeffen]

Ik ben er nu vanuit gegaan dat alle "uniek" benoemde constructies een <dfn> krijgen. Effect hiervan is dat de naam bold italic wordt getoond. Dat wordt geregeld in de CSS van Respec, check dat even bij jullie respec implementatie. Voorbeeld:

18 aug beschikbaar in Development.

[Gtrouborst]

Scope toepassing dfn-tag

In principe gaat het om de toepassing van alle modelelementen die volgens MIM een definitie hebben en dus in de documentatie gedefinieerd worden.

Bedoel je met uniek benoemde constructies dat er modelelementen zijn, bijvoorbeeld van het stereotype «Relatiesoort», die dezelfde naam hebben, bijvoorbeeld heeft? Hoe gaat Imvertor daar nu mee om: alleen de eerste keer dat een unieke naam voorkomt?

Styling Bold Italic

Ja ,de styling met bold italic klopt inderdaad. Dat is voor nu ook goed zo. Wij gaan hier verder induiken. Dit is iets dat mogelijk later aangepast wordt in de css. Het kan ook zijn dat er een andere oplossing uitrolt.

[ArjanLoeffen]

Ja, sommige namen komen meermaals voor. Ik weet niet hoe respec met die "dubbele" <dfn> omgaat.

[Gtrouborst]

Dubbele namen geven een foutmelding in ReSpec. In de werkversie van MIM1.2 komt datatype bijvoorbeeld twee maal voor:

• stereotype «Datatype»
• een tagged value Datatype (voor Codelists).

Foutmelding in ReSpec

Index met begrippen gedefinieerd in deze specificatie

Het levert dus een foutmelding op, maar het document wordt wel geladen. Ook kent de index per voorkomen een eigen entry, alleen heb je als lezer geen idee welke je moet hebben.

Persoonlijk vind ik dit een punt van aandacht voor de manier van modelleren en daarmee pleiten voor het hanteren van unieke namen.

[ArjanLoeffen]

Daarom dus alleen dfn opnemen voor top level element, OF namen van elementen uniek maken -- dat lijkt me niet helemaal doenlijk, maar ja, kun je proberen. Denk aan attribuut id, die wil je toch ook niet steeds overal uniek maken?

[Gtrouborst]

Ja je hebt gelijk, daar noem je een heel belangrijk punt. Het element Attribuutsoort hoeft alleen uniek te zijn binnen een Objecttype, maar niet binnen het model. Ik twijfel nu of het meerwaarde heeft om alleen de top level elements op te nemen.

@wilkoquak wat zijn jouw gedachten hierover? Wij waren in onze redenering van unieke begrippen uitgegaan, maar dat is toch complexer.

[Gtrouborst]

Wat mij betreft zitten er op dit moment nog teveel haken en ogen aan om deze wijziging nu te implementeren. Wij weten nu waar de uitdaging zit en gaan terug naar de tekentafel. Is het mogelijk om deze wijziging voorlopig uit te zetten?

@jacobvosimpronotion en ik vroegen ons af waarom deze wijziging ook de BRO-documentatie raakt. Het zou alleen voor Geonovum zou moeten gelden. De BRO heeft toch een aparte folder? In elk geval heeft het voor de BRO op dit moment geen meerwaarde. Bovendien zit hun documentstructuur anders in elkaar dan die van Geonovum, waardoor een eventuele implementatie überhaupt verschilt.