Skip to content

Latest commit

 

History

History
646 lines (588 loc) · 38.5 KB

VNG-R-WOW.md

File metadata and controls

646 lines (588 loc) · 38.5 KB
Raw

Respec documentatie (under construction)

Generatie m.b.v. Imvertor

Het is mogelijk om met Imvertor Respec documentatie te genereren van een model. Daarbij spelen de volgende configuratieproperties een rol:

Configuratieproperty Mogelijke waarden Uitleg
createoffice html, doc, none Hiermee geef je aan of je een documentatie bestand wil genereren en zo ja in welk formaat (html of MsWord). De defaultwaarde is 'none', behalve in het geval van een SIM, daar is de default 'html'. De 'doc' optie is nog niet geïmplementeerd.
createofficeanchor name, id Geeft aan op welke basis hyperlink anchors moeten worden gegenereerd (op basis van id's of op basis van namen). De default is 'name'. Tussen het genereren van respec als msword treden geen verschillen op. Vooralsnog maakt het dus niet uit welke variant je voor deze property kiest.
createofficemode plain, click Definieert of er in het te genereren bestand hyperlinks moeten worden gegenereert. Bij de waarde 'click' is dat het geval. De defaultwaarde is 'plain'.
createofficevariant respec, msword Definieert het type te genereren document. Een Respec html document of een MsWord html variant.
createimagemap yes, no Definieert of van de Diagrammen een imagemap moet worden gegenereerd. De default is 'yes'.

Voor het genereren van Respec documentatie is het essentieel om in je lokale property bestand de property 'createofficevariant' de waarde 'respec' te geven. Normaliter zal je dan ook de property 'createofficemode' de waarde 'click' geven. Dit resulteert er in dat in de folder 'app/cat' 2 Respec bestanden geplaatst, 1 in html en de ander in xhtml.

Toepassing in GitHub

De acties die in de voorgaande paragraaf staan beschreven leveren alleen het html bestand voor de Respec documentatie op. Respec documentatie bestaat echter uit meer dan dat html bestand. Een deel van de content van de Respec documentatie wordt door het Respec framework in GitHub gegenereerd a.d.h.v. een aantal variabelen en toe te voegen html en/of md bestanden. Daarnaast verzorgt dat framework ook de vormgeving dat essentieel is voor Respec documentatie.

Binnen VNG-R maken we gebruik van een door Logius vervaardigde extensie op het W3C Respec framework. We volgen daarbij andere organisaties in Nederland die hetzelfde doen zoals Geonovum. Van het door Logius beschikbaar gestelde template is een VNG-R versie beschikbaar binnen de VNG-Realisatie GitHub organisatie. Dat geeft de mogelijkheid om te verwijzen naar een VNG-R Respec configuratie waardoor we specifiek voor VNG-Realisatie geldende configuraties, zoals bijv. het VNG-Realisatie logo, kunnen aanbrengen. Deze vind je in de repository 'Respec-Organization-configurations'. Het template zelf kan echter door eenieder worden gebruikt om de eigen Respec documentatie te vervaardigen en daarbinnen bestaan nog mogelijkheden om jouw Respec documentatie een eigen tintje te geven.

Hieronder wordt de werkwijze beschreven waarbij de eerste 7 stappen moeten worden uitgevoerd door een GitHub organisatie administrator. Voorzie hem daarvoor van de gewenste respository naam.

Door administrator uit te voeren acties

  1. Open het VNG-R Respec template en klik in de README op die pagina op de link 'Use this template';
  2. Je komt nu in het menu om een nieuwe repository aan te maken waarbij al een aantal velden is ingevuld. De te maken repository mag niet private zijn want dat maakt het gebruik van GitHub Pages onmogelijk. Geef de van de aanvrager verkregen repository naam in en klik op 'Create repository';
  3. Voer de acties, zoals beschreven in de handleiding voor het initieel inrichten van GitHub repositories, uit;
  4. Verwijder in de root van de repository het 'README.md' bestand en hernoem 'Alt-README.md' naar 'README.md'

Dat bestand moet nog gecreëerd worden in het template;

  1. Activeer GitHub Pages voor de nieuwe repository. Selecteer daarvoor het tabblad 'Settings' en kies daar 'Pages';
  2. Kies daar waar bij Branch 'None' staat voor 'main' en klik op 'Save';
  3. Nadat de build en deployment is uitgevoerd ga je naar het 'Code' tabblad, klikt daar op het tandwieltje bij 'About' en klikt op de checkbox naast 'Use your GitHub Pages website'. Klikken op de resulterende link onder 'About' brengt je naar de standaard gegenereerde Repsec documentatie die nu kan worden aangepast door de eigenaar van de repository;

Door repository eigenaar uit te voeren acties

  1. Je beschikt nu over een repository die je kunt gaan vullen en waarin je je persoonlijke configuratie properties van een waarde kunt voorzien. Plaats daartoe als eerste het in de voorgaande paragraaf gegenereerde html bestand in de root van de repository;
  2. Van het bestand dat we zojuist geplaatst hebben gebruiken we alleen de 'section' met het id 'cat'. Verwijder alle andere content behalve de processing instruction 'DOCTYPE HTML' aan het begin van dit bestand en commit het bestand;
  3. Open het bestand 'index.html' en plaatst daarin op de gewenste plaats het volgende html fragment:

    <section id="XXXX" data-include-format="html" data-include="XXXX.html"></section>

    Waarbij je 'XXXX.html' vervangt door de naam van het zojuist aangepaste bestand en 'XXXX' door een id dat de sectie duidelijk en uniek identificeert. Als je nu op de website link onder 'About' klikt dan vind je de eerste versie van je Respec document;

De content van het Respec document aanpassen

Een Respec document kan op 2 verschillende manier van content worden voorzien:

  • m.b.v. de 'content' configuratie property;
  • door de 'sectie' elementen aan het 'index.html' bestand toe te voegen.

Beide methodes kunnen elkaar aanvullen en kennen eigen functionaliteiten.

Het Respec document zoals dat van het VNG-R Respec template is overgenomen moet nog aangepast worden. Deels kan dat door in de 'index.html' secties aan te passen danwel te vervangen en deels door de configuration property 'content' aan te passen.

M.b.v. de 'content' configuratie property kunnen alleen secties waarvan de content in markdown bestanden staat worden toegevoegd. In deze property kan per bestand worden aangegeven of die sectie informatief is. Is dat het geval dan wordt automatisch de tekst Dit onderdeel is niet normatief. aan het hoofdstuk toegevoegd. Het toevoegen van bestanden aan de 'content' configuratie property doe je door de naam van het bestand (zonder de extensie) en een eventueel relevante CSS class in de property te plaatsen. De volgorde van bestanden binnen content bepaalt de volgorde in het resulterende document.

De code content: {"ch01": "informative", "mermaid": ""}, voegt 2 markdown bestanden toe, te weten:

  • ch01.md met de CSS class informative;
  • mermaid.md zonder CSS class.

Voor een volledige lijst van CSS classes zie de ReSpec Documentation. Deze classes zijn ook binnen de markdown files te gebruiken op de volgende manier:

<div class="example">voorbeeld</div>

Het gebruik van de 'content' properties is niet verplicht, er mag voor worden gekozen nieuwe content alleen toe te voegen door het 'index.html' bestand aan te passen. De 'content' property moet dan wel uit het lokale 'js/config.js' bestand worden verwijderd of worden uitbecommentarieerd.

In tegenstelling tot de methode met de 'content' configuratie property kunnen aan het 'index.html' bestand zowel 'sectie' elementen worden toegevoegd waarvan de content uit markdown bestaat als 'sectie' elementen waarvan de content uit html bestaat. Aangezien het gegenereerde Respec bestand een html bestand is kunnen we het alleen toevoegen aan het Respec document door een 'sectie' element toe te voegen aan het index.html bestand.

Bij de methode met de 'sectie' elementen maken we nog verschil tussen 'sectie' elementen met specifieke waarden voor het 'id' attribuut en 'sectie' elementen die andere waarden voor dat 'id' attribuut hebben of die zelfs helemaal geen 'id' attribuut hebben.

Hieronder volgt per sectie een toelichting.

Secties met 'id' attribuutwaarde 'abstract'

  • Indien de sectie wordt toegevoegd met <sectie id="abstract" data-include-format="markdown" data-include="filenaam.md"> dan krijgt het hoofdstuk de titel Samenvatting zonder hoofdstuknr. als inhoud wordt de inhoud van het bestand 'filenaam.md' toegevoegd.
  • Indien de sectie wordt toegevoegd met <sectie id="nnnnnn" data-include-format="markdown" data-include="filenaam.md"> dan wordt het hoofdstuk gevuld met de inhoud van 'filenaam.md'. Als 'filenaam.md' met een markdown titel start (ongeacht het level en het aantal blanco regels er voor) dan wordt een hoofdstuknummer voor die titel gegenereerd anders wordt de content zonder titel toegevoegd aan het document. Een evt. titel wordt ook opgenomen in de TOC.
  • Indien de sectie wordt toegevoegd met <sectie data-include-format="markdown" data-include="filenaam.md"> dan wijkt het resultaat niet af van die van hierboven. Alleen wordt bij deze variant het 'id' van de sectie en de gerelateerde 'href' in de TOC gegenereerd op basis van de titel van deze sectie.

In alle gevallen is data-include-format="markdown" verplicht.

Secties met 'id' attribuutwaarde 'sotd'

Toe te voegen m.b.v. <section id="sotd"></section>. Leidt ertoe dat het hoofdstuk met de titel 'Status van het document' wordt toegevoegd met als inhoud de, van de waarde van de configuration property 'specStatus' afhankelijke, content van de configuration property 'sotdText'.

Tevens wordt een TOC gegenereerd waarin de titels (incl. evt. hoofdstuk en paragraafnummers) van alle, in het document opgenomen, hoofdstukken en paragrafen worden opgenomen afhankelijk van de configuratie property 'maxTocLevel'. Ook de titels van 'sectie' elementen zonder 'id' attribuut worden daar opgenomen.

Indien de configuration property 'content' bestaat dan worden de daarin gedefinieerde markdown bestanden na de 'sotd' sectie opgenomen. Zo niet dan worden de in de 'content' configuratie property gedefinieerde secties ook niet toegevoegd en wordt er ook geen TOC gegenereerd.

Secties met data-include-format="html"

Dit soort secties wordt direct opgenomen op de plaats waar <section id="nnnn" data-include-format="html" data-include="filenaam.html"></section> is geplaatst.

Het html fragment in het bestand hoeft niet te bestaan uit 1 root element. Sterker nog als dat wel het geval is en het fragment heeft de root 'div' of 'sectie' dan wordt het fragment niet vertaalt naar een separaat hoofdstuk.

Om een separaat hoofdstuk te kunnen starten dient het document wel met een 'hx' element te starten (h1, h2, h3, etc..).

De titel wordt dan ook opgenomen in de TOC.

Dit soort secties mag ook zonder 'id' attribuut worden opgenomen. Die variant geeft geen ander resultaat dan die hiervoorgeschetst. Alleen wordt bij deze variant het id van de sectie en de gerelateerde href in de TOC gegenereerd op basis van de titel van deze sectie.

data-include-format="html" mag worden weggelaten.

Secties met 'id' attribuutwaarde 'conformance'

Door <section id='conformance'></section> wordt een hoofdstuk met als titel 'Conformiteit' toegevoegd.

De inhoud komt waarschijnlijk uit https://github.com/Logius-standaarden/respec. Het is nog niet duidelijk hoe dit hoofdstuk zijn inhoud krijgt.

Secties met 'id' attribuutwaarde 'tof'

<section id='tof'></section> genereert een hoofdstuk met als titel 'Lijst met Figuren' als er in minimaal een van de opgenomen bestanden minimaal een html 'figure' element met een 'figcaption' element is opgenomen of een markdown equivalent daarvan ( '![Tekstueel alternatief voor toegankelijkheid](pad naar iluustratie bestand "Onderschrift")' ). In de markdown variant mag het onderschrift ontbreken.

De titel komt waarschijnlijk uit https://github.com/Logius-standaarden/respec. Het is nog niet duidelijk hoe die titel wordt toegekend.

Secties met 'id' attribuutwaarde 'index'

<section id="index"></section> genereert een hoofdstuk met als titel 'Bijlage N Index' als er in minimaal 1 van de in het document opgenomen bestanden (zowel markdown als html) minimaal 1 'dfn' element is opgenomen. Vanuit de tekst kan naar dat element verwezen worden door een 'a' element op te nemen zonder attributen maar met als inhoud de naam van een 'dfn' element.

Bijlage N Referenties

Wordt alleen opgenomen als er in een van de andere documenten (zowel markdown als html)een referentie is opgenomen in de vorm '[[Ref]]' en die referentie in config.js of organisation-config.js is gedefinieerd.

Secties met een 'id' attribuutwaarde die niet overeenkomt met de hierboven geschetste varianten

Indien het 'id' niet overeenkomt met een van de bekende id's dan wordt de sectie genegeerd.

Lokale Respec configuratie properties

Zoals aangegeven maken we in het Respec framework gebruik van een aantal VNG-R properties. Properties die er voor zorgen dat alle Respec documentatie van VNG-R eenzelfde look en feel heeft. Er zijn echter ook een aantal lokale configuratie properties waarmee voor ieder Respec document eigen keuzes kunnen worden gemaakt. Denk daarbij aan de status die het document heeft, de publicatie datum, de editors, etc...

Alle lokale configuratie properties kun je vinden in 'js/config.js' en mag je naar eigen inzicht aanpassen.

Er moet nog bepaald worden welke properties lokaal moeten zijn en welke globaal (dus welke behoren te staan in de repository 'Respec-Organization-configurations').

Functie Respec configuratie properties

Hieronder vind je de totale lijst van Configuratie properties. De vierde kolom geeft aan of het als een globale of lokale property wordt ingeschat, daar moet echter nog een discussie over gevoerd worden. Voor sommige properties is die inschattinh heel logisch, Zo zijn 'localizationStrings' en 'logos' logischerwijs globaal, 'github' en 'previousPublishVersion' zijn juist lokaal. Een aantal properties worden globaal gedefinieerd maar kunnen lokaal overruled worden zoals 'useLogo'. In de op een na laatste kolom staan vragen of opmerkingen die we moeten bediscusieren en de laatste kolom geeft aan of de omschrijving van de property nog aandacht verdiend of van voldoende kwaliteit is. De laatste 2 kolommen kunnen, als alle properties bediscusieerd zijn, worden verwijderd.

Property Link Type Globaal/Lokaal Vaste globale waarde of default waarde Gerelateerd property Beschrijving Opmerking/Vraag/Actie Documentatie status
addSectionLinks link boolean Globaal false Bepaald of er een paragraafteken (§), met een link naar de paragraaf waar het teken vóór komt te staan, wordt gegenereerd of niet.
Kan handig zijn om anderen de gelegenheid te bieden om links naar specifieke paragrafen in je specificaties te kopiëren en elders te gebruiken.

Kan lokaal overruled worden.		 Te bepalen of we standaard Respec documentatie met of zonder paragraafteken willen genereren en of we wel willen dat dat lokaal overruled kan worden. Gereed
alternateFormats link Array van properties per formaat. Lokaal Hiermee kun je aangeven of je de Respec documentatie ook in een ander formaat dan html aanbiedt. De verantwoordleijkheid voor de creatie van die alternatieve formaten is aan de beheerder van de betreffende Respec repository.
Deze configuratie property zorgt er alleen voor dat een zin gewijd wordt aan het/de betreffende alternatieve formaat/formaten en dat de link er naartoe wordt geplaatst in de Respec documentatie.		 Of zo'n formaat aangeboden wordt lijkt me een lokale configuratie. Niet in de laatste plaats omdat het afhankelijk is van handmatige acties van de beheerder van de betreffende Respec repository.

Blijkbaar is het ook mogelijk met GitHub Actions PDF documenten te genereren. In dat geval is dit niet meer afhankelijk van handmatige acties en zou het opgenomen kunnen worden in de globale configuratie. Dit moet nog onderzocht worden.		 Gereed
authors link Array van properties per naam. Lokaal Bevat 1 of meerdere beschrijvingen van personen die hebben bijgedragen aan de totstandkoming van de specificatie.

Editors hebben de voorkeur boven authors.		 Het verschil tussen editors en authors lijkt duidelijk. Authors hebben bijgedragen aan de initiële content van de specificatie, editors hebben verbeteringen en wijzigingen aangebracht aan die initiële content. Dat wetende begrijp ik echter niet waarom Editors de voorkeur hebben. Wellicht wil men het onderscheid liever niet maken en wordt iedereen als een editor gezien. Gereed
content n.t.b. Array Lokaal Te gebruiken voor het toevoegen van content aan het Respec document. Ik mis deze property in de side bar van https://github.com/Logius-standaarden/respec/wiki Gereed
editors link Array van properties per naam. Lokaal 1 of meerdere beschrijvingen van personen die hebben bijgedragen aan de totstandkoming van de specificatie.

Editors hebben de voorkeur boven authors.		 Het verschil tussen editors en authors lijkt duidelijk. Authors hebben bijgedragen aan de initiële content van de specificatie, editors hebben verbeteringen en wijzigingen aangebracht aan die initiële content. Dat wetende begrijp ik echter niet waarom Editors de voorkeur hebben. Wellicht wil men het onderscheid liever niet maken en wordt iedereen als een editor gezien. Gereed
formerEditors link Array van properties per naam. Lokaal Bevat 1 of meerdere beschrijvingen van personen die in het verleden hebben bijgedragen aan de totstandkoming van de specificatie. Gereed
github link URI of set van 2 properties Lokaal gebruikt voor het genereren van de links in de 'Doe mee' tabel bovenin de Respec documentatie. Kan gevuld worden met
  • een url naar een GitHub repository
  • het deel van de url van een GitHub repository dat komt na 'https://github.com/'
  • en set van properties bestaande uit
    • repoURL: Een van bovenstaande opties
    • branch: de branch waarin de specificaties maar ook issues staan opgeslagen.
Wordt tevens gebruikt voor het genereren van een link naar de GitHub pages van de laatste werkversie. Op basis van de hier gedefinieerde link wordt de GitHib Pages link automatisch bepaald.		 Het is de vraag of de url moet verwijzen naar de GitHub repository waarin de Respec documentatie van een Informatiemodel staat of juist naar de GitHub repository waarmee het Informatiemodel wordt beheerd. Deze twee hoeven nl. niet per definitie gelijk te zijn.
labelColor link Hexadecimale colorcode Globaal n.v.t. Definieert de bij de in 'LocalizationStrings' gedefinieerde waardes horende kleuren. Bij VNG-R zullen we nog de bij onze statussen gewenste kleuren moeten definiëren. Gereed
latestVersion link Combinatie van strings en propertynamen ? Url van de laatst gepubliceerde versie.
Wordt opgebouwd m.b.v. andere gedefinieerde variabelen en '/' tekens.

Indien deze variabele niet wordt verstrekt dan wordt de gerelateerde rubriek in de specificatie ook niet aangemaakt. Volgens mij wordt er dan wel een waarschuwing of foutmelding op de Respec pagina gegenereerd wat natuurlijk ook niet de bedoeling is.		 Willen we dat dit een globale property is of juist een lokale? Indien het een globale wordt moet het dan lokaal overruled kunnen worden?
Bijv. met een lege waarde waardoor de gerelateerde rubriek in de specificatie ook niet wordt aangemaakt. <-- Is dat wel de manier om dit te doen?

Te bepalen hoe deze variabele bij VNG-R opgebouwd moet worden.		 Gereed
license link enumeration Globaal eupl Definieert het licentietype dat van toepassing op de specificatie. VNG-R hanteert de 'EUPL' licentie maar zo gewenst kan ook gekozen worden voor 'CC0', 'CC-BY' of 'CC-BY-ND'. Toegestane waardes 'eupl', 'cc0', 'cc-by', 'cc-by-nd'. Wordt gebruikt om licentie-logo en bijbehorende link in het document te genereren. Nieuwe licentie types en het bijbehorende logo kunnen in de Globale property 'licenses' worden gedefinieerd.

Kan lokaal overruled worden.		 Willen we wel dat deze lokaal overruled kan worden? Gereed
licenses link Array van properties per licentiecode. Globaal n.v.t. Definieert middels een array van configuratie opties de te gebruiken soorten licenties waarnaar middels de code kan worden verwezen in de configuratie-optie 'license'. Bij VNG-R zullen we moeten bepalen welke licenties bij ons van toepassing (zouden kunnen) zijn.
Ik vermoed dat ook deze lokaal te overrulen is maar ik denk dat we dat niet moeten willen.		 Gereed
localBiblio link 1 of meerdere objecten met set van properties. ? n.t.b. Hiermee kan een lijst met referenties in het hoofdstuk 'Referenties' worden gegenereerd. Die referenties bevatten metainformatie (bijv. auteur, publicatiedatum en status) en links naar de betreffende externe referenties. De referenties worden echter alleen opgenomen in dat hoofdstuk als er in het Respec document naar verwezen wordt middels een link in de volgende syntax '[[Referentienaam]]'. Deze syntax geldt voor zowel html als markdown documenten.

Indien een link wordt opgenomen in een normatief documentdeel zal de referentie terecht komen in de subparagraaf 'Normatieve referenties'. Is deze opgenomen in een informatief documentdeel dan komt deze in de subparagraaf 'Informatieve referenties' terecht.

Gerefereerd kan worden aan specrefs die beschikbaar zijn in de SpecRef database https://www.specref.org/ (zie ook https://github.com/tobie/specref) of aan zelf in deze propertty gedefinieerde referenties. De syntax voor de inhoud van de localBiblio property is beschreven in https://github.com/tobie/specref/blob/main/schemas/raw-reference.json.

Deze property kan zowel lokaal als globaal geconfigureerd worden maar het is niet mogelijk deze property zowel lokaal als globaal te definiëren ook al bevatten ze andere inhoud. Hier is wel een verzoek toe ingediend bij Logius (Logius-standaarden/respec#52).		 Aangezien het nog niet mogelijk is deze property zowel lokaal als globaal te definiëren stel ik voor om dit vooralsnog globaal te doen. Als men naar een nieuwe referentie wil kunnen refereren dan moet daarvoor een verzoek worden gedaan deze toe te voegen aan de 'localBiblio' in de 'organisation-config.js'.

Zodra deze property tegelijkertijd zowel lokaal als globaal gedefinieerd kan worden. Hoeft alleen voor referenties waarvan we verwachten dat deze vaker gebruikt gaan worden of waarvan inmiddels duidelijk is dat deze vaker gebruikt worden een verzoek gedaan te worden deze op te nemen in de organisation-config.js. Beheerders van Respec repositories zijn er zelf verantwoordelijk voor dat deze referenties uit de config.js worden verwijderd.		 Gereed
localizationStrings link Array van properties per taalcode Globaal n.v.t. Bevat voor een aantal doelen en talen de te gebruiken codes en de daarbij horende volledige tekst. Nog te bepalen voor welke doelen hier codes gedefinieerd kunnen worden.

Bij VNG-R zullen we moeten bepalen of alle bestaande codes gewenst zijn en of er nieuwe codes toegevoegd moeten worden.
logos link Array van 5 properties per logo Globaal VNG Realisatie logo definieert de src, alternate tekst, url en grootte van het linksboven in de specificatie te plaatsen logo. Lijkt me dat we niet willen dat dit lokaal overruled kan worden. Gereed
maxTocLevel link Integer Lokaal 0 Bepaald het aantal niveau's dat maximaal wordt opgenomen in de inhoudsopgave van het Respec document. Default worden alle niveau's opgenomen. Ik stel voor hier een lokale property van te maken die alleen wordt opgenomen en aangepast als de inhoudsopgave dermate groot is dat het ondoenlijk wordt er doorheen te scrollen. Gereed
nl_organisationName link String Globaal VNG Realisatie Wordt gebruikt om de subtitel en het vertikale label linksboven te genereren.

Kan lokaal overruled worden.		 Willen we wel dat deze lokaal overruled kan worden? Gereed
nl_organisationPublishURL link URL Globaal ? Wordt gebruikt voor het genereren van de link naar de GitHub pages van de huidige, de vorige en de laatst gepubliceerde versie. De laatste gepubliceerde versie is overigens wat anders dan de laatste werkversie.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.		 Er moet bepaald worden welke waarde we als VNG-R hier willen hebben staan. N.m.m. moet dit een globale configuratie optie zijn en er moet dus ook beschreven worden hoe hier procesmatig mee omgegaan moet worden. Daarover moet nog wel een beslissing worden genomen en ook of een lokale variant toegestaan is.

Er moet onderzocht wat precies het verschil is tussen de laatst gepubliceerde versie en de laatste werkversie.
nl_organisationStylesURL link URL Globaal ? ? Moet onderzocht worden of we hiervoor een eigen variant kunnen creëren en zo ja of we dat ook willen.

Vooralsnog ga ik er vanuit dat hiervoor geen lokale variant gebruikt mag worden.
noTOC link boolean Lokaal false Bepaald of er links van de inhoud een frame met de inhoudsopgave gegenereerd wordt. Gereed
otherLinks link Array van properties Lokaal n.v.t. Genereert een sectie in de header van het Respec document met als titel de key van deze property en als inhoud een of meerdere links. Gereed
postProcess link ? ? Bevat een of meer JavaScript functies die achtereenvolgend opgestart worden nadat Respec klaar is met generatie van het Respec document. Bevat nu een functie die mermaid notatie wijze omzet naar graphs. Gereed
previousMaturity link enumeration Lokaal Status van de voorgaande versie.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
previousPublishDate link Datum in het formaat YYYY-MM-DD Lokaal Publicatiedatum van de voorgaande versie.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
previousPublishVersion n.t.b. SemVer notatie Lokaal Versienummer van de voorgaande versie in SemVer notatie (https://semver.org/lang/nl/).

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
prevVersion link Combinatie van strings en propertynamen ? Url van de voorgaande versie.
Wordt opgebouwd m.b.v. andere gedefinieerde variabelen en '/' tekens.

Indien deze variabele niet wordt verstrekt dan wordt de gerelateerde rubriek in de specificatie ook niet aangemaakt.		 Willen we dat dit een globale property is of juist een lokale? Indien het een globale wordt moet het dan lokaal overruled kunnen worden?
Bijv. met een lege waarde waardoor de gerelateerde rubriek in de specificatie ook niet wordt aangemaakt. <-- Is dat wel de manier om dit te doen?

Te bepalen hoe deze variabele bij VNG-R opgebouwd moet worden.
pubDomain link enumeration Lokaal Definieert het domein waarop de specificatie betrekking heeft.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.		 Uitgezocht moet worden hoe we deze bij VNG-R kunnen gebruiken. Er is nog geen lijst met public domains voor VNG-R geconfigureerd. De vraag is of je deze wel kunt definiëren, wellicht is het gewoon een ergens te publiceren lijst met waarden. Overigens niet helemaal duidelijk wat de functie is enhoe je het gebruikt. Wellicht kunnen de te definiëren waarden gebruikt worden als naam van een branch in GitHub.

Mogelijk te definiëren waarden binnen VNG-R:
  • zd (Zaken en Documenten)
  • bk (Basis en Kerngegevens)
  • dv (Dienstverlening)
  • rd (Ruimtelijk domein)
  • sd (Sociaal domein)
  • bv (Bedrijfsvoering)
publishDate link Datum in het formaat YYYY-MM-DD Lokaal Publicatiedatum van de huidige versie.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
publishVersion link SemVer notatie Lokaal Versienummer van de huidige versie in SemVer notatie (https://semver.org/lang/nl/).

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
shortName link String Lokaal Korte naam van de specificatie.

Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.
sotdText link Array van properties per taalcode. Globaal n.v.t. Bevat voor een aantal 'specStatus'sen en talen de te gebruiken codes en de daarbij horende volledige tekst. Bij VNG-R zullen we moeten bepalen welke teksten er bij welke status gegenereerd moeten worden. Gereed
specStatus link enumeration Lokaal Definieert de status van de specificatie. Wordt gebruikt om de subtitel en het vertikale label linksboven te genereren. Bepaald ook de kleur van dat label. Dit dient in de lokale configuratie gedefinieerd te worden.

De kleuren voor de VNG-R statussen kunnen worden gedefinieerd in de globale optie 'labelColor'.

Kan vermoedelijk ook worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.		 Gereed
spectype link enumeration Lokaal Definieert het type van de specificatie. Wordt gebruikt om de subtitel en het vertikale label linksboven te genereren. In het template heeft dit de waarde 'IM' aangezien we bij VNG-R Respec veelal zullen gebruiken om Informatiemodellen mee te publiceren. Gereed
subtitle link String Lokaal n.v.t. String die als subtitel van de titel van het document dient. Wordt geplaatst boven de gegenereerde subtitel waarin de organisatienaam, documenttype, specStatus, versiedatum en een evt. modifiedDatum worden gebruikt. Gereed
testSuiteURI link URL Lokaal n.v.t. Genereert een sectie in de header van het Respec document met als titel 'Test suite' en als inhoud een link naar een testsuite. Wellicht te gebruiken voor het API Testplatform maar alleen als we Respec ook gaan gebruiken voor de API's.
thisVersion link Combinatie van strings en propertynamen ? Url van de huidige versie.
Wordt opgebouwd m.b.v. andere gedefinieerde variabelen en '/' tekens.

Indien deze variabele niet wordt verstrekt dan wordt de gerelateerde rubriek in de specificatie ook niet aangemaakt.		 Willen we dat dit een globale property is of juist een lokale? Indien het een globale wordt moet het dan lokaal overruled kunnen worden?
Bijv. met een lege waarde waardoor de gerelateerde rubriek in de specificatie ook niet wordt aangemaakt. <-- Is dat wel de manier om dit te doen?

Te bepalen hoe deze variabele bij VNG-R opgebouwd moet worden.
title n.t.b. Lokaal De titel van de betreffende specificatie. Ik mis deze property in de side bar van https://github.com/Logius-standaarden/respec/wiki
useLabel link boolean Globaal true Bepaald of het verticale label aan de linker bovenzijde van de inhoudsopgave gegenereerd moet worden.

Kan lokaal overruled worden.		 Willen we wel dat deze lokaal overruled kan worden?

Ik mis deze property in de side bar van https://github.com/Logius-standaarden/respec/wiki		 Gereed
useLogo link boolean Globaal true Bepaald of het VNG-Realisatie logo in de rechter bovenzijde van het document geplaatst moet worden.

Kan lokaal overruled worden.		 Willen we wel dat deze lokaal overruled kan worden? Gereed
useSideBar link URL Property staat wel in de side bar van https://github.com/Logius-standaarden/respec/wiki maar link leidt niet naar een pagina met uitleg.

In dit record voorlopig de link naar de w3c uitleg opgenomen.

Het is de vraag of wij deze property wel zullen gebruiken. Het wordt ten eerste nie geadviseerd om Editors Draft niet te publiceren maar daarnaast is het de vraag of wij de specStatus 'ED' wel kennen bij VNG-R.