From df7b98f1ed5b5cfefd4f2be0b1e6693c27a105c0 Mon Sep 17 00:00:00 2001 From: Wilko Quak Date: Fri, 27 Sep 2024 17:15:12 +0200 Subject: [PATCH] kleine verbeteringen --- docs/GitHub-Inleiding.md | 133 ++-- docs/GitHub.md | 402 ++++++------ docs/ReSpec.md | 1336 +++++++++++++++++++------------------- docs/index.md | 210 +++--- mkdocs.yml | 2 +- 5 files changed, 1030 insertions(+), 1053 deletions(-) diff --git a/docs/GitHub-Inleiding.md b/docs/GitHub-Inleiding.md index ff93bd7..7986442 100644 --- a/docs/GitHub-Inleiding.md +++ b/docs/GitHub-Inleiding.md @@ -1,77 +1,56 @@ -# Inleiding Github - -Bij Geonovum worden documenten (standaarden, onderzoeken, rapporten, enz) web-based gepubliceerd. Ook worden de documenten vaak in een werkgroep gemaakt, waarbij ieder werkgroeplid meeschrijft aan het document. Om dit te kunnen gebruiken we een aantal tools: GitHub, Respec en Markdown. - -Deze introductie gaat over Github. - -Waarschijnlijk wil je weten wat GitHub is, anders was je nu niet deze handleiding aan het lezen. Je gaat hier meer over GitHub lezen en waarom het handig is. Er zijn een aantal GitHub termen die alvast handig zijn om te weten. Tot slot lees je hoe je zelf aan de slag kan gaan met GitHub. - -## Meer over Github - -Veel programmeurs wereldwijd maken gebruik van de website GitHub. Zelf zal je er misschien ook wel van gehoord hebben. Als programmeur is het handig om te weten wat GitHub is en hoe je er gebruik van maakt. - -GitHub bestaat uit twee woorden, namelijk Git + Hub. Laten we beginnen met Git. *Git is een open source versiebeheersysteem. De website GitHub is gemaakt op basis van het versiebeheersysteem Git. Met GitHub heb je alle mogelijkheden van Git + extra features. - -In een versiebeheersysteem kunnen programmeurs projecten beheren met code. Het is mogelijk om verschillende versies te beheren en eventueel terug te vallen op een oude versie, mocht er iets misgaan. - -Stel dat je met een team een app wilt programmeren. Dan is het handig als iedereen bij het project kan met daarin alle code van de app. Ook is het handig dat iedereen de laatste code wijzigingen ziet van teamleden en daar eventueel op kan reageren en/of het aanpassen. - -Bij Geonovum gebruiken we Github op een andere manier. Namelijk voor het voor werken aan documentatie voor geostandaarden. Per project is een repository aangemaakt. Een Repository is eenvoudig gezegd een werkmap/projectomgeving. - -## Andere mogelijkheden van Github - -Je weet nu dat het mogelijk is om in een team projecten (Waarin code staat) te beheren op GitHub. Het is natuurlijk ook mogelijk om je eigen projecten op GitHub te beheren. Zo heb je een goed overzicht van de aanpassingen en verschillende versies. - -Daarnaast staat je project online. Als je een belangrijk project bijvoorbeeld alleen lokaal op je eigen computer opslaat en je computer houdt ermee op, dan ben je zwaar de pineut. Op GitHub kan je er gewoon altijd bij. - -Maar welke mogelijkheden heeft GitHub nog meer? Hier staan een aantal belangrijke mogelijkheden op een rijtje: - -- Een project maken gebaseerd op een project dat al bestaat -- Discussie starten over een project -- Code reviewen -- Aparte branches maken, waarin je bijvoorbeeld code aanpassingen doet om te testen, die niet gelijk in de “productieversie” komen -- Code van branch samenvoegen met andere branch -- Tags meegeven aan verschillende versies, zoals V1.0 en V2.0 -- Kwetsbaarheden in de code makkelijker ontdekken, GitHub stuurt ook een mail als het kwetsbaarheden ontdekt -- Een website hosten - -## Voordelen van GitHub - -GitHub zorgt ervoor dat een individueel of een project in teamverband erg overzichtelijk is. *Je hebt een goed overzicht van de laatste aanpassingen en welke persoon dat heeft gedaan.* - -Je kan eenvoudig meerdere versies maken en eenvoudig terugvallen op een vorige versie, mocht het misgaan. *Door de verschillende branches loop je geen enkel risico bij het aanpassen en testen van nieuwe code.* Meer over branches in “Betekenissen van GitHub termen”. - -Voor programmeurs maakt GitHub het werken een stuk makkelijker en leuker. Stel dat je als programmeur niet aan versiebeheer zou doen of dat zou doen met een slecht versiebeheersysteem, dan ga je vroeg of laat in de problemen komen. - -GitHub is een centrale plek waar heel veel programmeurs en teams hun projecten beheren. Veel projecten zijn open source en kunnen door iedereen worden ingezien en aangepast. - -*Het is erg leerzaam om naar projecten van anderen te kijken.* Als je wat meer ervaring hebt, kan je misschien wel verbeteringen voorstellen en meedoen aan gave projecten! - -Met GitHub gaat er als programmeur een wereld voor je open. Het is goed om projecten te beheren en je kan er ook heel veel leren. - -Betekenis van Github termen? - -Op GitHub zijn er een aantal termen die handig zijn om alvast te weten. Als je meer gebruik gaat maken van GitHub, dan leer je de betekenis van deze termen vanzelf kennen. - -Hieronder staan belangrijke GitHub termen en de betekenis ervan: - -| GitHub term | Betekenis | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Repository | Een repository kan je zien als de hoofdmap van je project. Hierin staan alle bestanden van je project en de historie van wijzigingen die je hebt gedaan. | -| Branch | Aparte plek binnen je repository, waar je bijvoorbeeld nieuwe code kan testen, zonder dat te hoeven doen op de 'productversie'. | -| Master | Dit is de hoofdbranch, oftewel de “productversie” van je project. Nieuwe code die is getest en goedgekeurd, wordt samengevoegd met de Master branch. | -| Fork | Een fork is een kopie van een repository. Hierdoor kan je werken aan een project van iemand anders, zonder het origineel aan te passen. | -| Commit | Git commando dat veranderingen toevoegt aan je lokale repository. | -| Push | Git commando om aanpassingen naar je (remote) repository te sturen, die staat op GitHub. | -| Pull | Git commando om aanpassingen van je (remote) repository naar je lokale bestanden te sturen. | -| Merge | Git commando om aanpassingen van een branch samen te voegen met een andere branch. Bijvoorbeeld aanpassingen die getest en goedgekeurd zijn in de “Develop” branch samenvoegen met de “Master” branch. | -| Checkout | Deze Git commando wordt vaak gebruikt om te switchen tussen branches. Je checkt als het ware uit bij een branch en gaat aan de slag in een andere branch. | - - -## Zelf aan de slag met Github - -Hopelijk heb je een beter beeld over wat GitHub is. Ben je een gebruiker of wil je programmeur worden en werk je nog niet met een (goed) versiebeheersysteem? Dan is het zeker aan te raden om te beginnen met GitHub. - -Als je een account hebt aangemaakt kun je zelf een repository aanmaken. Zie hiervoor: [Aanmaken GitHub Account](GitHub#installatie-en-inrichting) - -Stuur een mail naar account@geonovum.nl om toegevoegd te worden aan deze repository. Je moet dan wel eerst een account aangemaakt hebben op github \ No newline at end of file +# Inleiding Github + +Bij Geonovum worden documenten (standaarden, onderzoeken, rapporten, enz) web-based gepubliceerd. Ook worden de documenten vaak in een werkgroep gemaakt, waarbij ieder werkgroeplid meeschrijft aan het document. Om dit te kunnen gebruiken we een aantal tools: GitHub, Respec en Markdown. + +## Meer over Github + + +GitHub bestaat uit twee woorden, namelijk Git + Hub. Laten we beginnen met Git. *Git is een open source versiebeheersysteem. De website GitHub is gemaakt op basis van het versiebeheersysteem Git. Met GitHub heb je alle mogelijkheden van Git + extra features. + +In een versiebeheersysteem kunnen programmeurs projecten beheren met code. Het is mogelijk om verschillende versies te beheren en eventueel terug te vallen op een oude versie, mocht er iets misgaan. + +Stel dat je met een team een app wilt programmeren. Dan is het handig als iedereen bij het project kan met daarin alle code van de app. Ook is het handig dat iedereen de laatste code wijzigingen ziet van teamleden en daar eventueel op kan reageren en/of het aanpassen. + +Bij Geonovum gebruiken we Github voor het voor werken aan documentatie voor geostandaarden. Per project is een repository aangemaakt. Een Repository is een werkmap/projectomgeving. + +## Andere mogelijkheden van Github + +Je weet nu dat het mogelijk is om in een team projecten (Waarin code staat) te beheren op GitHub. Het is natuurlijk ook mogelijk om je eigen projecten op GitHub te beheren. Zo heb je een goed overzicht van de aanpassingen en verschillende versies. + +Daarnaast staat je project online. Als je een belangrijk project bijvoorbeeld alleen lokaal op je eigen computer opslaat en je computer houdt ermee op, dan ben je zwaar de pineut. Op GitHub kan je er gewoon altijd bij. + +Maar welke mogelijkheden heeft GitHub nog meer? Hier staan een aantal belangrijke mogelijkheden op een rijtje: + +- Een project maken gebaseerd op een project dat al bestaat +- Discussie starten over een project +- Code reviewen +- Aparte branches maken, waarin je bijvoorbeeld code aanpassingen doet om te testen, die niet gelijk in de “productieversie” komen +- Code van branch samenvoegen met andere branch +- Tags meegeven aan verschillende versies, zoals V1.0 en V2.0 +- Kwetsbaarheden in de code makkelijker ontdekken, GitHub stuurt ook een mail als het kwetsbaarheden ontdekt +- Een website hosten + +## Voordelen van GitHub + +- Je hebt een goed overzicht van de laatste aanpassingen en welke persoon dat heeft gedaan. +- Je kan eenvoudig meerdere versies maken en eenvoudig terugvallen op een vorige versie, mocht het misgaan. Door de verschillende branches loop je geen enkel risico bij het aanpassen en testen van nieuwe code. +- GitHub is een centrale plek waar heel veel programmeurs en teams hun projecten beheren. Veel projecten zijn open source en kunnen door iedereen worden ingezien en aangepast. + + +Hieronder staan belangrijke GitHub termen en de betekenis ervan: + +| GitHub term | Betekenis | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Repository | Een repository kan je zien als de hoofdmap van je project. Hierin staan alle bestanden van je project en de historie van wijzigingen die je hebt gedaan. | +| Branch | Aparte plek binnen je repository, waar je bijvoorbeeld nieuwe code kan testen, zonder dat te hoeven doen op de 'productversie'. | +| Master | Dit is de hoofdbranch, oftewel de “productversie” van je project. Nieuwe code die is getest en goedgekeurd, wordt samengevoegd met de Master branch. | +| Fork | Een fork is een kopie van een repository. Hierdoor kan je werken aan een project van iemand anders, zonder het origineel aan te passen. | +| Commit | Git commando dat veranderingen toevoegt aan je lokale repository. | +| Push | Git commando om aanpassingen naar je (remote) repository te sturen, die staat op GitHub. | +| Pull | Git commando om aanpassingen van je (remote) repository naar je lokale bestanden te sturen. | +| Merge | Git commando om aanpassingen van een branch samen te voegen met een andere branch. Bijvoorbeeld aanpassingen die getest en goedgekeurd zijn in de “Develop” branch samenvoegen met de “Master” branch. | +| Checkout | Deze Git commando wordt vaak gebruikt om te switchen tussen branches. Je checkt als het ware uit bij een branch en gaat aan de slag in een andere branch. | + +## Zelf aan de slag met Github + +Als je een account hebt aangemaakt kun je zelf een repository aanmaken. Zie hiervoor: [Aanmaken GitHub Account](GitHub#installatie-en-inrichting) diff --git a/docs/GitHub.md b/docs/GitHub.md index fe3874d..1b3cbc5 100644 --- a/docs/GitHub.md +++ b/docs/GitHub.md @@ -1,201 +1,201 @@ -# GitHub - -In dit hoofdstuk komen zowel GitHub als GitHub desktop client aan de orde. Geonovum heeft op github een eigen ‘onderkomen’ op: [https://github.com/Geonovum](https://github.com/Geonovum). In dit hoofdstuk staat beschreven wat je moet doen om “up-and-running” te komen voor het uitvoeren van je beheertaken op GitHub. Hoe je een account aanmaakt, en hoe je de benodigde software installeert. - -## Installatie en inrichting - -### Aanmaken GitHub account - -Als je nog geen GitHub account hebt, of als je een apart GitHub account wil -maken voor je Geonovum werkzaamheden, ga naar: - . - -Dan zie je het scherm dat hiernaast staat. Maak in dat scherm een usernaam aan -waarmee je op GitHub gaat werken. - -**Tip**: als je met meerdere accounts gaat werken, zorg er dan voor dat aan -de accountnaam kan zien waarvoor die dan gebruikt moet worden. (Bijvoorbeeld -door die naam te eindigen op –GNM). Verplicht is dit niet. - -Vul in het veld username je nieuwe GitHub naam in. - -Vul je Geonovum email in - -![media/image3.png](media/image3.png) - -Klik vervolgens op “Create Account” en dan wordt je account aangemaakt. - -Kies in dit scherm je persoonlijke plan. Bij Geonovum gebruiken we de gratis -versie, dus selecteer die. - -![media/image4.png](media/image4.png) - -### Installeren GitHub desktop - -Ga in je internet browser naar - -Klik daar op download for Windows (64bit). - -Nu wordt de installer gedownload, en dat zie je linksonder in je browser zoals in het plaatje rechts: - -![media/image6.png](media/image6.png) -![media/image7.png](media/image7.png) - -Na starten van de installer verschijnt het scherm hiernaast - -Het volgende scherm zal nu openen - -we hebben in de vorige stap al een account aangemaakt dus klik op Sign Into Github.com - -![media/image8.png](media/image8.png) - -Na Klikken op Sign into Github.com, verschijnt dit scherm. Hier hoeft verder niks ingevuld te worden, dus klik op continue. - -In dit scherm kan je desgewenst het vinkje bij het versturen van anonieme data uitzetten. Daarna klikken op Finish. - -GitHub Desktop is nu geïnstalleerd. - -![media/image9.png](media/image9.png) - -### Opties voor GitHub desktop - -![media/image10.png](media/image10.png) - -GitHub Desktop kan worden aangepast aan persoonlijke voorkeuren. Dat doe je door in het hoofdscherm van de GitHub Desktop op het menu “File” te klikken en vervolgens voor “Opties” te kiezen. - -![media/image11.png](media/image11.png) -In het Accounts scherm staat hoe je bent ingelogd bij GitHub. Hier kan je uitloggen en opnieuw inloggen als je meerdere GitHub Accounts hebt. - -![media/image12.png](media/image12.png) -In het tabblad “Git” kan je je Github Naam eventueel aanpassen. De GitHub Email is de email die intern binnen Github wordt gebruikt. Die hoeft niet gewijzigd te worden. - -![media/image13.png](media/image13.png) -In het tabblad “Appearance” kan je ervoor kiezen om in Light of Dark modus te werken. Hiermee verander je alleen de achtergrondkleur van de GitHub Desktop omgeving. - -![media/image14.png](media/image14.png) - -In dit scherm kan je de voorkeurs editor instellen. Default wordt gekeken naar de reeds aanwezige tekst editors. Omdat GitHub van nature een samenwerkomgeving is voor het ontwikkelen van programmatuur, gaat het hier om “platte tekst” editors. - -## Werkwijze Geonovum - -### De Geonovum GitHub pagina - -Geonovum heeft een eigen GitHub Bedrijfspagina: . - -Voor alle projecten die een product maken of beheren wordt een repository aangemaakt. - -Het aanmaken van een repository staat beschreven in paragraaf 2.3.1. - -### Mappenstructuur in de respository - -![media/image16.png](media/image16.png) -In de Repository maak je indien nodig submappen aan. Submappen zijn handig als er in je Repository meer dan één ReSpec document komt te staan. Over ReSpec meer in hoofdstuk 3. - -Hiernaast een afbeelding van de GitHub Repository voor MIM. Twee mappen omdat MIM twee documenten bevat. - -Ook maakt GitHub standaard een readme.md aan. De readme staat in het “Markdown” formaat, waarover in de volgende paragraaf meer. - -### Readme.md - -In de readme.md file staat nog eens beschreven Wat de inhoud van de Repository is. Neem ook de link naar de webversie van de documenten hier op, dan is het voor bezoekers gemakkelijker om het document te openen in een browser. - -Neem altijd een link naar https://docs.geostandaarden.nl/ op, en in het geval het technische documenten betreft zoals UML’s, XSD’s, GML’s, XML’s een link naar http://register.geostandaarden.nl/ in het Readme bestand op. - -![media/image17.png](media/image17.png) - -## Aan de slag met GitHub - -In deze paragraaf een beschrijving van hoe je in GitHub een nieuwe repository aanmaakt, en hoe je die synchroniseert met je lokale GitHub client. - -### Het maken van een nieuwe repository - -Een nieuwe repository maak je aan in de Centrale GitHub omgeving. - -Klik in de banner bovenaan de pagina, naast je profielfoto op “+” en kies “Create Repository” - -Nadat je op “+” hebt geklikt, verschijnt het scherm hieronder. - -![media/image19.png](media/image19.png) - -Vul hier de naam van de repository in. Gebruik een naam die kort en bondig is. Zie ook verderop in dit document voor de naamgevingsconventies. - -Vul ook de beschrijving in van het project. - -Geef als local path de naam van de GitHub map op. GitHub zal dan de naam van de standaard als mapnaam aanmaken onder de lokale GitHub map. - -Het is wel zo netjes om een readme file aan te maken, hierin zet je een korte omschrijving van de repository. Klik vervolgens op “Create Repository” - -### GitHub Clone: eerste keer ophalen van de centrale repository - -![media/image20.png](media/image20.png) - -Start de GitHub Client, en kies in het menu File voor Clone Repository. En kies de Repository die je wil clonen (in dit geval Geonovum/MIM). Als Local Path kies je een logische plek op je PC/Laptop. (Tip: het is handig om één plek voor je Github Repositories te maken, bijvoorbeeld C:. Na het aanklikken van de knop clone wordt een lokale kopie gemaakt. Github weet welke versie je hebt opgehaald, en zal de wijzingen die je maakt netjes voor je bijhouden. - -In de map die je als local path hebt opgegeven komt de mappen structuur te staan zoals hierboven beschreven. - -### GitHub Pull origin: ophalen van wijzigingen - -Een pull commando werkt de lokale versie van je GitHub Repository bij. Wijzigingen die zijn gedaan in de centrale repository (dus op Github.com) worden ook doorgevoerd in je lokale kopie. Het uitvoeren van een pull doe je door in het menu Repository op pull te klikken. - -NB: Voer dit commando regelmatig uit als er meerdere mensen in de repository werken, om conflicterende wijzigingen te voorkomen. - -### GitHub Commit to Master: wijzigingen opslaan - -Met de knop Commit to master zet je de wijzigingen die je hebt gedaan klaar om te uploaden naar de Centrale GitHub Repository. GitHub maakt daartoe een versie aan, - -die je verplicht voorziet van een summary en optioneel van een Description Let op: met - -het committen heb je dus nog niks ge-upload. - -### GitHub Push origin of Pull request: wijzigingen uploaden - -Nadat je de wijzigingen hebt gecommit, moeten ze richting de centrale repository. Nu zijn er twee mogelijkheden. Ofwel je hebt schrijfrechten op de Centrale Repository, of je hebt ze niet. In het eerste geval kan je een Push Origin uitvoeren, dan worden de wijzigingen meteen in de Centrale GitHub Repository verwerkt. In het tweede geval doe je een Pull request bij de eigenaar van de Repository om de wijzigingen door te voeren. Github maakt dan een eigen versie voor je aan (dat heet een fork) en vraagt aan de eigenaar van de Repository om die fork te verwerken in de Centrale Repository. - -## Enkele regels over GitHub binnen Geonovum - -- Geonovum heeft binnen github een team: . - -### Github beheer - -- Github teamleden met beheerders rechten zijn te vinden via: -- Daarnaast zijn er nog drie inhoudelijk beheerders vanuit Geonovum: Arnoud de Boer, Frank Terpstra en Linda vd Brink. - -### Github gebruikers - -- Een overzicht van de gebruikers is te vinden op: . -- In principe geldt de regels: als je lid bent van Geonovum Teams dan hoor je ook bij de Geonovum GitHub organisatie. De inhoudelijk beheerders kunnen besluiten daar van af te wijken. -- Er is geen bezwaar tegen het gebruiken van een privé account binnen de github omgeving. -- Bij vertrek wordt je omgezet naar 'External Collaborator'. - -### GitHub teams - -- Er is een aantal teams gemaakt binnen Geonovum. Deze zijn te vinden op: . -- Ieder repository moet aan een team worden toegekend. Het team is aanspreekpunt voor het repository. -- Team namen eindigen op ' team'. Bijvoorbeeld 'DSO team'. - -### GitHub repositories - -- Dit zijn de Geonovum repositories: . -- Er is ook een dashboard met een overzicht van publieke git repositories: [DashboardGit](https://geonovum.github.io/DashboardGit/). -- Richtlijnen voor het inrichten van repositories zijn er nog niet. Wel is er een template voor respec documenten: [NL-ReSpec-GN-template](https://github.com/Geonovum/NL-ReSpec-GN-template) - -### GitHub organisaties - -Een GitHub Organization is een verzamelplaats van repositories, die allemaal van dezelfde eigenaar, zijnde een bedrijf of instelling, zijn. Geonovum heeft twee GitHub organisaties: -- https://github.com/Geonovum: hierin staan de repositories voor onze standaarden en andere gerelateerde producten. -- https://github.com/Geonovum-labs: hierin staan enkele repositories met open source code, demo's, voorbeelden en experimenten ter ondersteuning van standaarden. - -https://github.com/Geonovum heeft een README.md introtekst met summiere informatie over Geonovum, hoe wij met github werken en verwijzingen naar meer informatie. Deze tekst wordt beheerd in een aparte github repository: https://github.com/Geonovum/.github. - -Daarnaast wordt een landingspagina getoond op https://geonovum.github.io. Dit is (een kopie van) dezelfde tekst. Deze staat ook in een README.md, die wordt beheerd in een andere github repository: https://github.com/Geonovum/geonovum.github.io. - -#### Naamgevingsconventies GitHub - -- Voor repositories met een ReSpec document zijn aparte naamgevingsconventies. -- Kies korte betekenisvolle namen die in lijn zijn met bestaande repositories. -- Veelgebruikte prefixes zijn: - - **dso-** digitale ondersteuning omgevingswet. - - **ow-** omgevingswet. Dit lijkt wel een duplicaat. Laten opgaan in dso-? - - **KP-APIs-** kennisplatform API's. - - **xml\_** Dit was een prefix voor dso repositories maar wordt voor nieuwe repositories niet meer gebruikt. - - **disgeo-** DisGeo +# GitHub + +In dit hoofdstuk komen zowel GitHub als GitHub desktop client aan de orde. Geonovum heeft op github een eigen ‘onderkomen’ op: [https://github.com/Geonovum](https://github.com/Geonovum). In dit hoofdstuk staat beschreven wat je moet doen om “up-and-running” te komen voor het uitvoeren van je beheertaken op GitHub. Hoe je een account aanmaakt, en hoe je de benodigde software installeert. + +## Installatie en inrichting + +### Aanmaken GitHub account + +Als je nog geen GitHub account hebt, of als je een apart GitHub account wil +maken voor je Geonovum werkzaamheden, ga naar: + . + +Dan zie je het scherm dat hiernaast staat. Maak in dat scherm een usernaam aan +waarmee je op GitHub gaat werken. + +**Tip**: als je met meerdere accounts gaat werken, zorg er dan voor dat aan +de accountnaam kan zien waarvoor die dan gebruikt moet worden. (Bijvoorbeeld +door die naam te eindigen op –GNM). Verplicht is dit niet. + +Vul in het veld username je nieuwe GitHub naam in. + +Vul je Geonovum email in + +![media/image3.png](media/image3.png) + +Klik vervolgens op “Create Account” en dan wordt je account aangemaakt. + +Kies in dit scherm je persoonlijke plan. Bij Geonovum gebruiken we de gratis +versie, dus selecteer die. + +![media/image4.png](media/image4.png) + +### Installeren GitHub desktop + +Ga in je internet browser naar + +Klik daar op download for Windows (64bit). + +Nu wordt de installer gedownload, en dat zie je linksonder in je browser zoals in het plaatje rechts: + +![media/image6.png](media/image6.png) +![media/image7.png](media/image7.png) + +Na starten van de installer verschijnt het scherm hiernaast + +Het volgende scherm zal nu openen + +we hebben in de vorige stap al een account aangemaakt dus klik op Sign Into Github.com + +![media/image8.png](media/image8.png) + +Na Klikken op Sign into Github.com, verschijnt dit scherm. Hier hoeft verder niks ingevuld te worden, dus klik op continue. + +In dit scherm kan je desgewenst het vinkje bij het versturen van anonieme data uitzetten. Daarna klikken op Finish. + +GitHub Desktop is nu geïnstalleerd. + +![media/image9.png](media/image9.png) + +### Opties voor GitHub desktop + +![media/image10.png](media/image10.png) + +GitHub Desktop kan worden aangepast aan persoonlijke voorkeuren. Dat doe je door in het hoofdscherm van de GitHub Desktop op het menu “File” te klikken en vervolgens voor “Opties” te kiezen. + +![media/image11.png](media/image11.png) +In het Accounts scherm staat hoe je bent ingelogd bij GitHub. Hier kan je uitloggen en opnieuw inloggen als je meerdere GitHub Accounts hebt. + +![media/image12.png](media/image12.png) +In het tabblad “Git” kan je je Github Naam eventueel aanpassen. De GitHub Email is de email die intern binnen Github wordt gebruikt. Die hoeft niet gewijzigd te worden. + +![media/image13.png](media/image13.png) +In het tabblad “Appearance” kan je ervoor kiezen om in Light of Dark modus te werken. Hiermee verander je alleen de achtergrondkleur van de GitHub Desktop omgeving. + +![media/image14.png](media/image14.png) + +In dit scherm kan je de voorkeurs editor instellen. Default wordt gekeken naar de reeds aanwezige tekst editors. Omdat GitHub van nature een samenwerkomgeving is voor het ontwikkelen van programmatuur, gaat het hier om “platte tekst” editors. + +## Werkwijze Geonovum + +### De Geonovum GitHub pagina + +Geonovum heeft een eigen GitHub Bedrijfspagina: . + +Voor alle projecten die een product maken of beheren wordt een repository aangemaakt. + +Het aanmaken van een repository staat beschreven in paragraaf 2.3.1. + +### Mappenstructuur in de respository + +![media/image16.png](media/image16.png) +In de Repository maak je indien nodig submappen aan. Submappen zijn handig als er in je Repository meer dan één ReSpec document komt te staan. Over ReSpec meer in hoofdstuk 3. + +Hiernaast een afbeelding van de GitHub Repository voor MIM. Twee mappen omdat MIM twee documenten bevat. + +Ook maakt GitHub standaard een readme.md aan. De readme staat in het “Markdown” formaat, waarover in de volgende paragraaf meer. + +### Readme.md + +In de readme.md file staat nog eens beschreven Wat de inhoud van de Repository is. Neem ook de link naar de webversie van de documenten hier op, dan is het voor bezoekers gemakkelijker om het document te openen in een browser. + +Neem altijd een link naar https://docs.geostandaarden.nl/ op, en in het geval het technische documenten betreft zoals UML’s, XSD’s, GML’s, XML’s een link naar http://register.geostandaarden.nl/ in het Readme bestand op. + +![media/image17.png](media/image17.png) + +## Aan de slag met GitHub + +In deze paragraaf een beschrijving van hoe je in GitHub een nieuwe repository aanmaakt, en hoe je die synchroniseert met je lokale GitHub client. + +### Het maken van een nieuwe repository + +Een nieuwe repository maak je aan in de Centrale GitHub omgeving. + +Klik in de banner bovenaan de pagina, naast je profielfoto op “+” en kies “Create Repository” + +Nadat je op “+” hebt geklikt, verschijnt het scherm hieronder. + +![media/image19.png](media/image19.png) + +Vul hier de naam van de repository in. Gebruik een naam die kort en bondig is. Zie ook verderop in dit document voor de naamgevingsconventies. + +Vul ook de beschrijving in van het project. + +Geef als local path de naam van de GitHub map op. GitHub zal dan de naam van de standaard als mapnaam aanmaken onder de lokale GitHub map. + +Het is wel zo netjes om een readme file aan te maken, hierin zet je een korte omschrijving van de repository. Klik vervolgens op “Create Repository” + +### GitHub Clone: eerste keer ophalen van de centrale repository + +![media/image20.png](media/image20.png) + +Start de GitHub Client, en kies in het menu File voor Clone Repository. En kies de Repository die je wil clonen (in dit geval Geonovum/MIM). Als Local Path kies je een logische plek op je PC/Laptop. (Tip: het is handig om één plek voor je Github Repositories te maken, bijvoorbeeld C:. Na het aanklikken van de knop clone wordt een lokale kopie gemaakt. Github weet welke versie je hebt opgehaald, en zal de wijzingen die je maakt netjes voor je bijhouden. + +In de map die je als local path hebt opgegeven komt de mappen structuur te staan zoals hierboven beschreven. + +### GitHub Pull origin: ophalen van wijzigingen + +Een pull commando werkt de lokale versie van je GitHub Repository bij. Wijzigingen die zijn gedaan in de centrale repository (dus op Github.com) worden ook doorgevoerd in je lokale kopie. Het uitvoeren van een pull doe je door in het menu Repository op pull te klikken. + +NB: Voer dit commando regelmatig uit als er meerdere mensen in de repository werken, om conflicterende wijzigingen te voorkomen. + +### GitHub Commit to Master: wijzigingen opslaan + +Met de knop Commit to master zet je de wijzigingen die je hebt gedaan klaar om te uploaden naar de Centrale GitHub Repository. GitHub maakt daartoe een versie aan, + +die je verplicht voorziet van een summary en optioneel van een Description Let op: met + +het committen heb je dus nog niks ge-upload. + +### GitHub Push origin of Pull request: wijzigingen uploaden + +Nadat je de wijzigingen hebt gecommit, moeten ze richting de centrale repository. Nu zijn er twee mogelijkheden. Ofwel je hebt schrijfrechten op de Centrale Repository, of je hebt ze niet. In het eerste geval kan je een Push Origin uitvoeren, dan worden de wijzigingen meteen in de Centrale GitHub Repository verwerkt. In het tweede geval doe je een Pull request bij de eigenaar van de Repository om de wijzigingen door te voeren. Github maakt dan een eigen versie voor je aan (dat heet een fork) en vraagt aan de eigenaar van de Repository om die fork te verwerken in de Centrale Repository. + +## Enkele regels over GitHub binnen Geonovum + +- Geonovum heeft binnen github een team: . +- Geonovum heeft ook het team + +### Github beheer + +- Github teamleden met beheerders rechten zijn te vinden via: +- Daarnaast zijn er nog drie inhoudelijk beheerders vanuit Geonovum: Arnoud de Boer, Frank Terpstra en Linda vd Brink. + +### Github gebruikers + +- Een overzicht van de gebruikers is te vinden op: . +- Als je lid bent van Geonovum Teams dan hoor je ook bij de Geonovum GitHub organisatie. De inhoudelijk beheerders kunnen besluiten daar van af te wijken. +- Er is geen bezwaar tegen het gebruiken van een privé account binnen de github omgeving. +- Werk je niet meer bij Geonovum wordt je omgezet naar 'External Collaborator'. + +### GitHub teams + +- Er is een aantal teams gemaakt binnen Geonovum. Deze zijn te vinden op: . +- Ieder repository moet aan een team worden toegekend. Het team is aanspreekpunt voor het repository. +- Team namen eindigen op ' team'. Bijvoorbeeld 'DSO team'. + +### GitHub repositories + +- Dit zijn de Geonovum repositories: . +- Richtlijnen voor het inrichten van repositories zijn er nog niet. Wel is er een template voor respec documenten: [NL-ReSpec-GN-template](https://github.com/Geonovum/NL-ReSpec-GN-template) + +### GitHub organisaties + +Een GitHub Organization is een verzamelplaats van repositories, die allemaal van dezelfde eigenaar, zijnde een bedrijf of instelling, zijn. Geonovum heeft twee GitHub organisaties: +- https://github.com/Geonovum: hierin staan de repositories voor onze standaarden en andere gerelateerde producten. +- https://github.com/Geonovum-labs: hierin staan enkele repositories met open source code, demo's, voorbeelden en experimenten ter ondersteuning van standaarden. + +https://github.com/Geonovum heeft een README.md introtekst met summiere informatie over Geonovum, hoe wij met github werken en verwijzingen naar meer informatie. Deze tekst wordt beheerd in een aparte github repository: https://github.com/Geonovum/.github. + +Daarnaast wordt een landingspagina getoond op https://geonovum.github.io. Dit is (een kopie van) dezelfde tekst. Deze staat ook in een README.md, die wordt beheerd in een andere github repository: https://github.com/Geonovum/geonovum.github.io. + +#### Naamgevingsconventies GitHub + +- Voor repositories met een ReSpec document zijn aparte naamgevingsconventies. +- Kies korte betekenisvolle namen die in lijn zijn met bestaande repositories. +- Veelgebruikte prefixes zijn: + - **dso-** digitale ondersteuning omgevingswet. + - **ow-** omgevingswet. Dit lijkt wel een duplicaat. Laten opgaan in dso-? + - **KP-APIs-** kennisplatform API's. + - **xml\_** Dit was een prefix voor dso repositories maar wordt voor nieuwe repositories niet meer gebruikt. + - **disgeo-** DisGeo diff --git a/docs/ReSpec.md b/docs/ReSpec.md index 3cb4327..a07ece9 100644 --- a/docs/ReSpec.md +++ b/docs/ReSpec.md @@ -1,669 +1,667 @@ -# Inleiding ReSpec - -Binnen Geonovum gebruiken we ReSpec voor het maken van standaarden. ReSpec maakt -gebruik van input bestanden om HTML te genereren. Deze inputbestanden (de -content) wordt gemaakt in het Markdown formaat. Deze Markdown bestanden kunnen -worden aangemaakt met text editor. GitHub wordt gebruikt als de 'repository' -waarin alle bestanden die bij een standaard horen, beheerd worden. - -Deze handleiding beschrijft hoe je een GitHub Account maakt, hoe je GitHub -Desktop Client installeert en gebruikt, hoe je een Respec mappenstructuur -opbouwt, welke bestanden er nodig zijn voor een standaard, en hoe je de -verschillende versies van een standaard genereert. Ook wordt uitgelegd hoe je de -Markdown plugin in Microsoft Word installeert en gebruikt. - -ReSpec is een tool van W3C die het schrijven van specifications makkelijker -maakt. ReSpec zorgt voor een uniforme styling in het document, onderhoudt -referenties en verwijzingen naar andere documentatie, verzorgt de inhoudsopgave, -zorgt voor links naar vorige en meest recente versies, en heeft een integratie -met Github issues. - -Geonovum gebruikt een fork van ReSpec die door Logius beheerd wordt. Dit -document bevat een globale instructie over hoe snel aan de start te gaan. Meer -documentatie is op andere plaatsen te vinden: - -- Er is een gedetailleerde (Engelstalige) - [gebruikershandleiding](https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide) - beschikbaar. -- Er is ook een - [ontwikkelaarshandleiding](https://github.com/w3c/respec/wiki/Developers-Guide) - te vinden. -- De Geonovum [wiki over ReSpec](https://github.com/Geonovum/respec/wiki) is - een fork van de w3c ReSpec met aanpassingen voor Geonovum. Deze is - achterhaald omdat we nu van de Logius Respec gebruik maken. (TODO aanpassen) - -## Een nieuwe document maken - -ReSpec documenten worden beheerd in een [GitHub](/GitHub) repository. Als je een -nieuw ReSpec document wilt maken gebruik dan de -[Geonovum ReSpec template](https://github.com/Geonovum/NL-ReSpec-GN-template) -als startpunt en druk op de 'Use this template' knop om een nieuw repository aan -te maken. - -Zoek in dit repository op de tekst 'TODO' om de plaatsen te vinden waar -aanpassen van de template vereist is. - -## De URL van een publicatie op docs.geonovum.nl - -ReSpec documenten worden gepubliceerd op -[docs.geostandaarden.nl](https://docs.geostandaarden.nl). Iedere gepubliceerde -versie van een document heeft een eigen URL. Voor de laatst gepubliceerde versie -is een aparte URL. - -De URL van iedere publicatie wordt als volgt bepaald: - -```text -https://docs.geostandaarden.nl/[pubdomain]/[specStatus]-[spectype]-[shortName]-[publishDate]/ -``` - -De laatst gepubliceerde versie is OOK te vinden op: - -```text -https://docs.geostandaarden.nl/[pubdomain]/[shortName]/ -``` - -De namen van de variabelen staan verderop uitgelegd. - -## De mapindeling van een ReSpec repository - -Dit levert een nieuw repository op met de onderstaande mappenstructuur. - -| hoofdmap | map | file | omschrijving | -| -------- | ---------- | --------- | ------------------------------------------------------ | -| Hoofdmap | | | naam van de hoofdmap | -| | media | | Map met mediabestanden | -| | | Style.css | File met vaste naam, bevat de styling van het document | -| | | \*.png | Afbeeldingsbestanden | -| | index.html | | File met de vaste naam `Index.html` | -| | js | | | -| | | config.js | File met de vaste naam `config.js` | -| | \*md | | Tekstbestanden (Markdown) die de content bevatten | - -Hieronder staat een voorbeeld van zo’n mappenstructuur. - -![media/image22.png](media/image22.png) - -## Het bestand 'index.html' - -Het bestand index.html zorgt ervoor dat het ReSpec document automatisch wordt -geladen in de browser. Bij het laden wordt ook automatisch de -geonovum-ReSpec-code geladen en uitgevoerd. Deze code zorgt ervoor dat het -document zijn standaard layout krijgt. - -Het bestand 'index.html' heeft een vaste indeling. Hieronder de structuur uit de -template: - -```html - - - - - - - - - - - TODO: Vul hier de titel in - - - - - -
-
- - - -
-
-
- -
-
-
- - -``` - -In de HTML-header wordt de js-ReSpec bibliotheek geladen. Het enige dat in de -header mag worden aangepast is de title (tussen \ en \. Andere -aanpassingen die nodig zijn in de header mogen alleen worden gedaan in overleg -met de ReSpec beheerders. Een overzicht van de ReSpec beheerders staat in -Hoofdstuk 6 - -In de HTML-Body geldt _vrijheid in gebondenheid_ De `
` en/of `
` -regels mogen worden gekopieerd en toegevoegd. Wel belangrijk om de structuur -over te nemen, dus als volgt: - -``` -
- -
\Inleiding\\ -``` - -Een `
` is een sectie plus bijbehorend document, dat niet in de -inhoudsopgave terechtkomt. Deze gebruik je bijvoorbeeld voor een Toelichting, -een Colofon of een Voorwoord. - -Een `
` komt wél in de inhoudsopgave terecht. Deze heeft daarom behalve -de data-include van het document, ook (verplicht!) een `

` tag. De tekst -tussen `

` en `

` komt in de inhoudsopgave te staan. - -## Het bestand 'config.js' - -In config.js wordt een stuurvariabele voor ReSpec gevuld. De waarden in deze -variabele worden door ReSpec gebruikt om de layout te bepalen, en bevatten een -aantal document-eigenschappen. - -### SpecStatus - -De SpecStatus in de configuratie geeft de keuze uit 4 waarden, deze waarden zijn -vastgesteld, en mogen niet zomaar uitgebreid of aangepast worden. Elke status -hoort bij een formele fase van een ReSpec document. Zie ook de Geonovum ReSpec -[wiki](https://github.com/Geonovum/respec/wiki). - -- **WV**, Werkversie: Dit is de versie van het document waaraan wordt - gewerkt. Deze versie is continu 'under-construction'. -- **CV**, Consultatieversie: Dit is een 'snapshot' van de versie die 'in - consultatie' wordt gezet. Aan deze versie wordt niks meer gedaan totdat de - consultatie is afgelopen. Daarna worden alle op en aanmerkingen uit de - consultatieronde verwerkt. -- **VV**, Vaststellingsversie: Dit is een 'snapshot' van de versie na het - verwerken van de op en aanmerkingen uit de consultatieronde is ontstaan. - Deze versie wordt aangeboden aan de programma-raad van Geonovum, om te - wordern 'vastgesteld'. -- **DEF**, Definitieve versie: Dit is de definitieve versie van het document, - zoals vastgesteld door de programma-raad. Van deze versie wordt opnieuw een - 'snapshot' gemaakt in ReSpec. Het resultaat van die snapshot wordt op - http://docs.geonovum.nl - neergezet. -- **LD**, Levend document: Geschikt voor handreikingen en dergelijke die regelmatig gewijzigd worden en waarvoor niet een consultatie- en goedkeuringsproces gevolgd hoeft te worden -- **basis**, document zonder officiële status. - -### SpecType - -Het SpecType in de configuratie is een vaste lijst met waarden, deze waarden -zijn vastgesteld, en mogen niet zonder overleg met de Technische ReSpec -beheerders uitgebreid of aangepast worden. - -Onderstaande beschrijvingen komen uit het generiek -beheerplan[5] Zie: -https://www.geonovum.nl/uploads/documents/Geonovum%20GENERIEK%20Beheerplan%20geo-standaarden%20v1.1.pdf -
. - -- **NO** Norm: Een norm is bij een officieel standaardisatie instituut - ondergebracht en bevat bindende afspraken. Naast het gebruik van normen is - NEN 3610 de enige norm waar Geonovum een inhoudelijke verantwoordelijkheid - heeft. Het formele beheer en beslissingen worden genomen in de NEN - normcommissie 351 240 waar Geonovum de voorzitter van is. - -- **ST** Standaard: Een document met (bindende) afspraken. - -- **IM** Informatiemodel: Een standaard waarbij door de term informatiemodel - te hanteren wordt aangegeven dat het een abstractie (het model) vormt van de - werkelijkheid zoals beschreven binnen een bepaalde sector/domein. - Informatiemodellen zijn een semantische invulling van normen voor sectoren - zoals ruimtelijke ordening, kabels en leidingen, water, etc.. - -- **PR** Praktijkrichtlijn: Praktijkrichtlijnen zijn producten die informatie - geven, vaak met een technisch karakter, die nodig is voor het toepassen van - standaarden. Een praktijkrichtlijn hoort altijd bij een standaard/norm. - -- **HR** Handreiking: Op zichzelf staande documentatie dat als doel heeft een - hulpmiddel te zijn, niet verplichtend maar ondersteunend. - -- **WA** Werkafspraak: Legt uit hoe wetgeving moet worden toegepast bij - onduidelijkheden, discrepanties of fouten in de standaarden. - -- **BD** Beheerdocumentatie: Documentatie met betrekking tot het beheerproces - van de standaard. Deze documentatie betreft niet een standaard of onderdeel - daarvan, zoals een handreiking of werkafspraak. - -- **AL** Algemeen: Op zichzelf staande algemene documentatie over standaarden. - De documentatie betreft niet een specifieke standaard of onderdeel daarvan, - het is ook geen beheerdocumentatie van een specifieke standaard. - -## pubDomain - -pubDomain bepaalt bij publicatie een deel van de URL waarop het document wordt -gepubliceerd. Het zorgt voor een groepering van de documenten op -docs.geostandaarden.nl Omdat je de URL van gepubliceerde documenten niet wilt -veranderen is moet je hier goed over nadenken en alleen in overleg nieuwe -toevoegen. - -De actuele lijst van pubDomains staat in de tabel hieronder. De herkomst van -deze lijst is als volgt: - -1. Lijst op github : - [respec-utils](https://github.com/Geonovum/respec-utils/blob/master/src/autodeploy/config/pubDomainList.json). -2. docs.geostandaarden.nl. -3. register.geostandaarden.nl. - -Naamgevinsregels voor pubDomain: - -- Lowercase -- Geen spaties - -| Pubdomain | Omschrijving | Herkomst | status | GitHub Team | Beslissing | -| -------------- | -------------------------------------------------------- | -------------------------- | ------------------------- | ------------------------------------------------------------- | --------------------------------------- | -| 3dbv | 3D basisvoorziening | docs.geostandaarden.nl | inactief (gemigreerd) | | mag niet meer gebruikt worden | -| api | Kennisplatform APIs | respec utils | | [API team](https://github.com/orgs/Geonovum/teams/api-team) | OK | -| basisgeometrie | Informatiemodel Basisgeometrie | register.geostandaarden.nl | zit op docs bij nen3610 | | niet gebruiken eigenlijk xsd redirecten | -| bgt | Basisregistratie grootschalige topografie | docs.geostandaarden.nl | | [BGT team](https://github.com/orgs/Geonovum/teams/bgt-team) | Arnoud vragen | -| brt | Informatiemodellen Basisregistratie Topografie | register.geostandaarden.nl | | [BRT team](https://github.com/orgs/Geonovum/teams/brt-team) | OK | -| crs | Coördinaatreferentiesystemen | docs.geostandaarden.nl | | [CRS team](https://github.com/orgs/Geonovum/teams/crs-team) | OK | -| cvgg | Informatiemodel Geluid | docs.geostandaarden.nl | duplicaat van img | | OK | -| disgeo | DisGeo | respec utils | | | OK | -| dsgo | Digitaal Stelsel Gebouwde Omgeving | docs.geostandaarden.nl | | | OK (rare uri) | -| dso | Digitaal Stelsel Omgevingswet | respec utils | duplicaten: tpod imow ow | [DSO team](https://github.com/orgs/Geonovum/teams/dso-team) | OK | -| eu | | docs.geostandaarden.nl | | [EU team](https://github.com/orgs/Geonovum/teams/eu-team) | OK (rare uri en werkversie weg) | -| g4w | | docs.geostandaarden.nl | | | groeperen? | -| gbd | | docs.geostandaarden.nl | | | groeperen? | -| geobag | | docs.geostandaarden.nl | | | OK | -| gsw | | docs.geostandaarden.nl | | | groeperen? | -| imaer | Informatiemodel AERIUS | register.geostandaarden.nl | | | OK | -| imev | Informatiemodel Externe Veiligheid | docs.geostandaarden.nl | | [IMEV team](https://github.com/orgs/Geonovum/teams/api-team) | OK | -| img | Informatiemodel Geluid | respec utils | duplicaat: cvgg | [IMG team](https://github.com/orgs/Geonovum/teams/img-team) | redirecten naar cvgg | -| imgeo | Informatiemodel Grootschalige Geografie | docs.geostandaarden.nl | | | Arnoud vragen | -| imka | Informatiemodel Klimaatadaptatie | docs.geostandaarden.nl | | | OK | -| imkad | Informatiemodel Kadaster | register.geostandaarden.nl | | [IMKA team](https://github.com/orgs/Geonovum/teams/imka-team) | OK | -| imkl | Informatiemodel Kabels en Leidingen | register.geostandaarden.nl | duplicaat: kl | [IMKL team](https://github.com/orgs/Geonovum/teams/imkl-team) | Zou kl moeten worden | -| imle | | docs.geostandaarden.nl | | | OK (niet netjes gepubliceerd) | -| imro | Informatiemodel Ruimtelijke Ordening | register.geostandaarden.nl | duplicaat: ro | | liefst naar RO | -| imow | Informatiemodel Omgevingswet | register.geostandaarden.nl | duplicaten: tpod ow dso | | liefst weg | -| kl | IMKL | respec utils | duplicaat: imkl | | OK | -| md | Metadata | respec utils | duplicaat: metadata | | OK | -| mim | Metamodel Informatie Modellering (MIM | respec utils | | | OK | -| metadata | Nederlandse metadata profielen voor datasets en services | register.geostandaarden.nl | duplicaat: md | | verplaatsen naar md?? | -| nen3610 | NEN3610-Linkeddata | respec utils | | | OK | -| ngii | | docs.geostandaarden.nl | | | OK | -| oov | | docs.geostandaarden.nl | | | OK | -| ow | Standaarden omgevingswet | respec utils | duplicaten: tpod imow dso | | OK | -| ro | RO Standaarden | respec utils | duplicaat: imro | | OK | -| rwgs | Raamwerk van Geo-standaarden | respec utils | | | groeperen? | -| serv | Services | respec utils | | | groeperen? | -| tpod | Toepassingsprofiel omgevingsdocumenten | respec utils | duplicaten: ow imow dso | | OK | -| vg | Informatiemodel Vastgoedgebruik | respec utils | | | OK | -| visu | Visualisatie | respec utils | | | groeperen? | -| vtm | | docs.geostandaarden.nl | is eigenlijk metadata | | verhuizen naar MD | -| wp | Whitepaper Geostandaarden | respec utils | ook een raar pubdomain | | verhuizen naar ngii | - -## LocalBiblio - -In de localBiblio variabele worden Referenties naar andere documenten gezet. -Voordat je hier citaten toevoegt, loont het de moeite om eerst in de -[https://www.specref.org/](SpecRef) van ReSpec zelf te kijken. Pas als je een -verwijzing niet vindt in SpecRef voeg je hem hier toe! - -Verwijzen naar een bibliografieelement gebeurt als volgt `[[ID]]`. De dubbele -haakjes zorgen ervoor dat er blokhaken om de verwijzing staan in de tekst. Je -kunt ook aangeven dat een verwijzing normatief is door er een uitroepteken voor -te zetten `[[!ID]]` - -## Voorbeeld config.js - -``` -let respecConfig = { - useLogo: true, - useLabel: true, - // title is verplicht! Neem hier de titel van het document op ---------------------- - title: "[Neem titel op in config.js]", - //-- specStatus is verplicht! (activeer 1 van de volgende) -------------------------- - specStatus: "wv", // Werkversie - - //-- specType is verplicht bij alle andere dan BASIS --------------------------------- - specType: "HR", // HandReiking - - //-- pubDomain is verplicht! (komt in de URL) ------------------------------------- - pubDomain: "TODO", - //-- license: voor de geldende gebruiksvoorwaarden. Default is cc-by. - //licence: "cc-by-nd", // bronvermelding, geen afgeleide werken (default) - //licence: "cc0", // Public Domain Dedication - licence: "cc-by", // Attribution, met bronvermelding - //-- shortName is verplicht! (komt in de URL: kies logische afkorting)-------------- - shortName: "NL-ReSpec-GN-template", - //-- publishDate is verplicht ------------------------------------------------------- - //-- NB: in de werkversie uitzetten, want dan pakt Respec de pushdate --------------- - //publishDate: "2023-03-28", - //eventueel is het mogelijk een versienummer mee te geven, maar bij Geonovum werken we gewoonlijk alleen met datum als onderdeel van de permanente URI. - //publishVersion: "0.0.2", - //previousVersion: "0.0.1", - //-- Voor dit blok geldt: alleen als er eerdere versies zijn en altijd beiden aan/uit! - //previousPublishDate: "2014-05-01", - //previousMaturity: "CV", - //-- de namen van de Editor(s) / Redacteur(en)--------------------------------------- - //-- vul in: per Editor: name:, company:, companyURL: ------------------------------- - editors: - [ - { - name: "voornaam achternaam", - company: "Geonovum", - companyURL: "https://www.geonovum.nl", - } - ], - //-- de namen van de auteur(s) ------------------------------------------------------ - //-- vul in: per auteur: name:, company:, companyURL: ------------------------------- - authors: - [ - { - name: "voornaam achternaam", - company: "Geonovum", - companyURL: "https://www.geonovum.nl", - } - ], - //neem hier de URL van de github repository op waar het respec document in staat - github: "https://github.com/Geonovum/NL-ReSpec-GN-template", - // Create PDF and link to file in header (optional): - alternateFormats: [ - { - label: "pdf", - uri: "template.pdf", - }, - ], -}; -``` - -De file config.js is een stukje javascript (JSON) code, het bevat alle mogelijke -waarden voor de verschillende versies die wij hanteren bij Geonovum. In de file -zelf staat aangegeven welke waarden verplicht zijn, en uit welke waarden te -kiezen is. In bovenstaand voorbeeld gaat het om een 'Werkversie van een -standaard'. - -### Content: bestanden '\*.md' - -De 'echte' content wordt gemaakt in het formaat 'Markdown'. Er is een aantal -editors beschikbaar die dat formaat ondersteunen. Zie hiervoor -Hoofdstuk 3. Het is handig om voor elk hoofdstuk -een aparte Markdown file te maken, want dan blijven de bestanden beperkt in -grootte, en zijn er gemakkelijker werkafspraken te maken over wie wanneer in -welke file aan het editen is. - -### Content: Afbeeldingen '\*.png' - -Afbeeldingen worden als '.png' of '.svg' bestand neergezet in de map 'media'. In -je Markdown document neem je gewoon een plaatje op zoals je in Word gewend bent. -Writage en ReSpec zorgen ervoor dat de plaatjes worden getoond. - -## ReSpec Frontend - -### De knop 'ReSpec' - -De knop 'ReSpec' rechtsboven in de frontend van ReSpec, bevat een aantal handige -functies. Als je klikt op de knop, verschijnt het vervolgscherm met een viertal -functies. - -Elk van de functies wordt hieronder uitgelegd. - -![media/image25.png](media/image25.png) - -### Bewaar snapshot - -![media/image26.png](media/image26.png) - -### Doorzoek SpecRef - -![media/image27.png](media/image27.png) ![media/image28.png](media/image28.png) - -De gevonden zoekresultaten kunnen worden overgenomen in het ReSpec document. - -### Lijst van definities - -Zie: [definitielijst maken](ReSpec-definitielijst-maken.md) - -## HTML ingebed in ReSpec - -Omdat wij ervoor hebben gekozen om documenten te schrijven in Markdown, -gebruiken wij niet alle ReSpec functionaliteit. In dit hoofdstuk worden de -speciale ReSpec functies beschreven die als HTML code in het Markdown document -kunnen wordnen opgenomen, of die in de door respec gegenereerde HTML file kunnen -worden neergezet. Het gebruik van deze functionaliteit vereist dus wel HTML -kennis. - -## HTML voor Afbeeldingen - -Een lijst van afbeeldingen kan door ReSpec automatisch worden gegenereerd, maar -dan moet er wel aan een aantal ReSpec specifieke voorwaarden worden voldaan: - -In Index.html komt ergens te staan: - -```html -
- -
The water flows from bucket A to bucket B.
-
-``` - -In de documenten worden de afbeeldingen op de volgende manier neergezet: - -```html -
- -
The water flows from bucket A to bucket B.
-
-``` - -NB: `
` inclusief uniek ID en een ge-embedde `
` zijn -verplicht! - -Eventuele referenties naar plaatjes doe je op e volgende manier: - -```html -

The flowchart shown in is quite impressive.

-
-``` - -## Referentie naar GitHub issues - -ReSpec ondersteunt ook een koppeling naar issues die zijn gemeld op GitHub. Jek -kan referenties opnemen naar individuele issues. Ook is het mogelijk om een -lijst met alle issues op te nemen in je document. - -Om GitHub issues op te nemen moet je in 'config.js' een referentie opnemen naar -de GitHub repository. - -``` -issueBase: "https://github.com/Geonovum/MIM-Werkomgeving/issues/" -``` - -Een referentie naar een issue neem je als volgt op: - -``` -
-``` - -Waarbij data-number het issuenummer is. - -Een lijst met issues kan je toevoegen met de volgende HTML code: - -``` -
- -
- -``` - -## Foutmeldingen en waarschuwingen - -![media/image29.png](media/image29.png) ![media/image30.png](media/image30.png) - -In dit geval is er een tikfout gemaakt bij de naam van de Markdownfile die -ge-include wordt. Het moet natuurlijk `H2-Testcases.md` zijn. - -![media/image31.png](media/image31.png) - -Een voorbeeld van een waarschuwing. Klikken hierop geeft je je de waarschuwing. - -In het onderstaande voorbeeld meldt ReSpec dat er een `

` header ontbreekt in -het Markdown document. - -![media/image32.png](media/image32.png) - -# Publiceren in ReSpec - -In dit hoofdstuk staan checklists die je kan gebruiken als je vanuit GitHub en -ReSpec “Versies” gaat aanmaken. Bijvoorbeeld hoe maak je een nieuwe GitHub -repository aan, of hoe maak je vanuit een werkversie een consultatieversie aan, - -## Controles voor publicatie - -Controleer de volgende onderwerpen voor iedere publicatie: - -- Controleer op **WCAG** regels. Bij het pushen van een ReSpec document naar - GitHub wordt automatisch een WCAG rapport geschreven. Dit is te vinden onder - 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar - 'Check/WCAG'). -- Controleer op **Broken links**. Bij het pushen van een ReSpec document naar - GitHub wordt automatisch op broken links gechecked. Dit is te vinden onder - 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar - 'Check/Links'). -- Controleer of de **HTML correct** is: maak een snapshot aan en biedt het aan - aan de [W3C validator](https://validator.w3.org) -- C - -## Consultatie versie (CV) maken - -1. Edit en controleer config.js - configureer alles goed voor een - consultatieversie - - `specStatus`:`"GN-CV"` - - `publishDate`: moet ingevuld zijn met de datum van publicatie van de - consultatieversie. `"jjjj-mm-dd"`, - - `Shortname`: moet ingevuld zijn met korte naam voor het document. Dit - wordt onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van - versies). - - Als er al eerder een versie gepubliceerd is (stabiele versie, dus - afgezien van de werkversie in github), kan Respec bovenin een document - de navigatie naar vorige versie goed genereren. Daarvoor moet je ook - invullen: - - `Previousmaturity`: wat de status toen was. - - `Previousmaturity`: wat de status toen was. -1. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) -1. Kies “HTML” en noem dit bestand “snapshot.html” -1. Commit het en push het naar dezelfde folder als waar `index.html` staat in je - Github-repository - -### Consultatieverise met ftp - -> **Note**: uitwerken - -Omdat de webhook nogal eens problemen oplevert is er ook een proces voor het -publiceren met ftp. In het kort is het als volgt: - -1. Zet alles klaar in github (zoals bij de webhook). -2. Vraag een beheerder om de boel naar docs.geostandaarden.nl om te zetten. - -### Consultatieversie maken met behulp van webhook - -[Klik hier](/Publiceren/) voor een beschrijving over hoe je een webhook eenmalig -configureert voor een repository. over het toepassen van de webhook. - -1. Maak een release tag conform de naamgevingsconventie: - `\{specStatus\}-\{specType\}-\{shortName\}-\{publishDate\}` -1. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd - zijn als ‘webhook’ in de github repository!) het `snapshot.html` en de - bijbehorende afbeeldingen naar - [docs.geostandaarden.nl]). -1. Na succesvolle publicatie: - - zet de `specStatus` in `config.js` terug op `"GN-WV"` - - Vul `previousMaturity` in met `"GN-CV"` - - Vul `previousPublishDate` in met de datum van de zojuist gepubliceerde - consultatieversie - - - -## Vaststellingsversie (VV) maken - -1. Edit en controleer config.js - configureer alles goed voor een - vaststellingsversie - - specStatus: "GN-VV" - - publishDate: moet ingevuld zijn met de datum van publicatie van de - consultatieversie. "jjjj-mm-dd", - - Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt - onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van - versies). - - Als er al eerder een versie gepubliceerd is (stabiele versie, dus - afgezien van de werkversie in github), kan Respec bovenin een document - de navigatie naar vorige versie goed genereren. Daarvoor moet je ook - invullen: - - Previousmaturity: wat de status toen was. - - Previousmaturity: wat de status toen was. -2. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) -3. Kies “HTML” en noem dit bestand “snapshot.html” -4. Commit het en push het naar dezelfde folder als waar index.html staat in je - Github repository -5. Maak een release tag conform de naamgevingsconventie: - \{specStatus\}-\{specType\}-\{shortName\}-\{publishDate\} -6. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd - zijn als ‘webhook’ in de github repository!) het snapshot.html en de - bijbehorende afbeeldingen naar -7. Na succesvolle publicatie: - - zet de specStatus in config.js terug op GN-WV - - Vul previousMaturity in met GN-CV - - Vul previousPublishDate in met de datum van de zojuist gepubliceerde - consultatieversie - -## Definitieve versie (DEF) maken - -1. Edit en controleer config.js - configureer alles goed voor een definitieve - versie - - specStatus: "GN-DEF", - - publishDate: moet ingevuld zijn met de datum van publicatie van de - definitieve versie. "jjjj-mm-dd", - - Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt - onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van - versies). - - Als er al eerder een versie gepubliceerd is (stabiele versie, dus afgezien - van de werkversie in github), kan Respec bovenin een document de navigatie - naar vorige versie goed genereren. Daarvoor moet je ook invullen: - - Previousmaturity: wat de status toen was. - - previousPublishDate: vorige publicatiedatum (jjjj-mm-dd) -2. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) -3. Kies “HTML” en noem dit bestand “snapshot.html” -4. Commit het en push het naar dezelfde folder als waar index.html staat in je - Github repository -5. Maak een release tag conform de naamgevingsconventie: - {specStatus}-{specType}-{shortName}-{publishDate} -6. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd - zijn als ‘webhook’ in de github repository!) het snapshot.html en de - bijbehorende afbeeldingen naar Hoe dit werkt - is beschreven in: -7. Na succesvolle publicatie: - - zet de specStatus in config.js terug op GN-WV - - Vul previousMaturity in met GN-DEF - - Vul previousPublishDate in met de datum van de zojuist gepubliceerde - definitieve versie +# Inleiding ReSpec + +Binnen Geonovum gebruiken we ReSpec voor het maken van standaarden. ReSpec maakt +gebruik van input bestanden om HTML te genereren. Deze inputbestanden (de +content) wordt gemaakt in het Markdown formaat. Deze Markdown bestanden kunnen +worden aangemaakt met text editor. GitHub wordt gebruikt als de 'repository' +waarin alle bestanden die bij een standaard horen, beheerd worden. + +Deze handleiding beschrijft hoe je een GitHub Account maakt, hoe je GitHub +Desktop Client installeert en gebruikt, hoe je een Respec mappenstructuur +opbouwt, welke bestanden er nodig zijn voor een standaard, en hoe je de +verschillende versies van een standaard genereert. Ook wordt uitgelegd hoe je de +Markdown plugin in Microsoft Word installeert en gebruikt. + +ReSpec is een tool van W3C die het schrijven van specifications makkelijker +maakt. ReSpec zorgt voor een uniforme styling in het document, onderhoudt +referenties en verwijzingen naar andere documentatie, verzorgt de inhoudsopgave, +zorgt voor links naar vorige en meest recente versies, en heeft een integratie +met Github issues. + +Geonovum gebruikt een fork van ReSpec die door Logius beheerd wordt. Dit +document bevat een globale instructie over hoe snel aan de start te gaan. Meer +documentatie is op andere plaatsen te vinden: + +- Er is een gedetailleerde (Engelstalige) + [gebruikershandleiding](https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide) + beschikbaar. +- Er is ook een + [ontwikkelaarshandleiding](https://github.com/w3c/respec/wiki/Developers-Guide) + te vinden. +- De Geonovum [wiki over ReSpec](https://github.com/Geonovum/respec/wiki) is + een fork van de w3c ReSpec met aanpassingen voor Geonovum. Deze is + achterhaald omdat we nu van de Logius Respec gebruik maken. (TODO aanpassen) + +## Een nieuwe document maken + +ReSpec documenten worden beheerd in een [GitHub](/GitHub) repository. Als je een +nieuw ReSpec document wilt maken gebruik dan de +[Geonovum ReSpec template](https://github.com/Geonovum/NL-ReSpec-GN-template) +als startpunt en druk op de 'Use this template' knop om een nieuw repository aan +te maken. + +Zoek in dit repository op de tekst 'TODO' om de plaatsen te vinden waar +aanpassen van de template vereist is. + +## De URL van een publicatie op docs.geonovum.nl + +ReSpec documenten worden gepubliceerd op +[docs.geostandaarden.nl](https://docs.geostandaarden.nl). Iedere gepubliceerde +versie van een document heeft een eigen URL. Voor de laatst gepubliceerde versie +is een aparte URL. + +De URL van iedere publicatie wordt als volgt bepaald: + +```text +https://docs.geostandaarden.nl/[pubdomain]/[specStatus]-[spectype]-[shortName]-[publishDate]/ +``` + +De laatst gepubliceerde versie is OOK te vinden op: + +```text +https://docs.geostandaarden.nl/[pubdomain]/[shortName]/ +``` + +De namen van de variabelen staan verderop uitgelegd. + +## De mapindeling van een ReSpec repository + +Dit levert een nieuw repository op met de onderstaande mappenstructuur. + +| hoofdmap | map | file | omschrijving | +| -------- | ---------- | --------- | ------------------------------------------------------ | +| Hoofdmap | | | naam van de hoofdmap | +| | media | | Map met mediabestanden | +| | | Style.css | File met vaste naam, bevat de styling van het document | +| | | \*.png | Afbeeldingsbestanden | +| | index.html | | File met de vaste naam `Index.html` | +| | js | | | +| | | config.js | File met de vaste naam `config.js` | +| | \*md | | Tekstbestanden (Markdown) die de content bevatten | + +Hieronder staat een voorbeeld van zo’n mappenstructuur. + +![media/image22.png](media/image22.png) + +## Het bestand 'index.html' + +Het bestand index.html zorgt ervoor dat het ReSpec document automatisch wordt +geladen in de browser. Bij het laden wordt ook automatisch de +geonovum-ReSpec-code geladen en uitgevoerd. Deze code zorgt ervoor dat het +document zijn standaard layout krijgt. + +Het bestand 'index.html' heeft een vaste indeling. Hieronder de structuur uit de +template: + +```html + + + + + + + + + + + TODO: Vul hier de titel in + + + + + +
+
+ + + +
+
+
+ +
+
+
+ + +``` + +In de HTML-header wordt de js-ReSpec bibliotheek geladen. Het enige dat in de +header mag worden aangepast is de title (tussen \ en \. Andere +aanpassingen die nodig zijn in de header mogen alleen worden gedaan in overleg +met de ReSpec beheerders. Een overzicht van de ReSpec beheerders staat in +Hoofdstuk 6 + +In de HTML-Body geldt _vrijheid in gebondenheid_ De `
` en/of `
` +regels mogen worden gekopieerd en toegevoegd. Wel belangrijk om de structuur +over te nemen, dus als volgt: + +``` +
+ +
\Inleiding\\ +``` + +Een `
` is een sectie plus bijbehorend document, dat niet in de +inhoudsopgave terechtkomt. Deze gebruik je bijvoorbeeld voor een Toelichting, +een Colofon of een Voorwoord. + +Een `
` komt wél in de inhoudsopgave terecht. Deze heeft daarom behalve +de data-include van het document, ook (verplicht!) een `

` tag. De tekst +tussen `

` en `

` komt in de inhoudsopgave te staan. + +## Het bestand 'config.js' + +In config.js wordt een stuurvariabele voor ReSpec gevuld. De waarden in deze +variabele worden door ReSpec gebruikt om de layout te bepalen, en bevatten een +aantal document-eigenschappen. + +### SpecStatus + +**Bron:** + +De SpecStatus in de configuratie geeft de keuze uit 4 waarden, deze waarden zijn +vastgesteld, en mogen niet zomaar uitgebreid of aangepast worden. Elke status +hoort bij een formele fase van een ReSpec document. Zie ook de Geonovum ReSpec +[wiki](https://github.com/Geonovum/respec/wiki). + +- **WV**, Werkversie: Dit is de versie van het document waaraan wordt + gewerkt. Deze versie is continu 'under-construction'. +- **CV**, Consultatieversie: Dit is een 'snapshot' van de versie die 'in + consultatie' wordt gezet. Aan deze versie wordt niks meer gedaan totdat de + consultatie is afgelopen. Daarna worden alle op en aanmerkingen uit de + consultatieronde verwerkt. +- **VV**, Vaststellingsversie: Dit is een 'snapshot' van de versie na het + verwerken van de op en aanmerkingen uit de consultatieronde is ontstaan. + Deze versie wordt aangeboden aan de programma-raad van Geonovum, om te + worden 'vastgesteld'. +- **DEF**, Definitieve versie: Dit is de definitieve versie van het document, + zoals vastgesteld door de programma-raad. Van deze versie wordt opnieuw een + 'snapshot' gemaakt in ReSpec. Het resultaat van die snapshot wordt op + neergezet. +- **LD**, Levend document: Geschikt voor handreikingen en dergelijke die regelmatig gewijzigd worden en waarvoor niet een consultatie- en goedkeuringsproces gevolgd hoeft te worden +- **basis**, document zonder officiële status. + +### SpecType + +**Bron:** + +Het SpecType in de configuratie is een vaste lijst met waarden, deze waarden +zijn vastgesteld, en mogen niet zonder overleg met de Technische ReSpec +beheerders uitgebreid of aangepast worden. + +- **NO** Norm: Een norm is bij een officieel standaardisatie instituut + ondergebracht en bevat bindende afspraken. Naast het gebruik van normen is + NEN 3610 de enige norm waar Geonovum een inhoudelijke verantwoordelijkheid + heeft. Het formele beheer en beslissingen worden genomen in de NEN + normcommissie 351 240 waar Geonovum de voorzitter van is. + +- **ST** Standaard: Een document met (bindende) afspraken. + +- **IM** Informatiemodel: Een standaard waarbij door de term informatiemodel + te hanteren wordt aangegeven dat het een abstractie (het model) vormt van de + werkelijkheid zoals beschreven binnen een bepaalde sector/domein. + Informatiemodellen zijn een semantische invulling van normen voor sectoren + zoals ruimtelijke ordening, kabels en leidingen, water, etc.. + +- **PR** Praktijkrichtlijn: Praktijkrichtlijnen zijn producten die informatie + geven, vaak met een technisch karakter, die nodig is voor het toepassen van + standaarden. Een praktijkrichtlijn hoort altijd bij een standaard/norm. + +- **HR** Handreiking: Op zichzelf staande documentatie dat als doel heeft een + hulpmiddel te zijn, niet verplichtend maar ondersteunend. + +- **WA** Werkafspraak: Legt uit hoe wetgeving moet worden toegepast bij + onduidelijkheden, discrepanties of fouten in de standaarden. + +- **BD** Beheerdocumentatie: Documentatie met betrekking tot het beheerproces + van de standaard. Deze documentatie betreft niet een standaard of onderdeel + daarvan, zoals een handreiking of werkafspraak. + +- **AL** Algemeen: Op zichzelf staande algemene documentatie over standaarden. + De documentatie betreft niet een specifieke standaard of onderdeel daarvan, + het is ook geen beheerdocumentatie van een specifieke standaard. + +## pubDomain + +pubDomain bepaalt bij publicatie een deel van de URL waarop het document wordt +gepubliceerd. Het zorgt voor een groepering van de documenten op +docs.geostandaarden.nl Omdat je de URL van gepubliceerde documenten niet wilt +veranderen is moet je hier goed over nadenken en alleen in overleg nieuwe +toevoegen. + +De actuele lijst van pubDomains staat in de tabel hieronder. De herkomst van +deze lijst is als volgt: + +1. Lijst op github : + [respec-utils](https://github.com/Geonovum/respec-utils/blob/master/src/autodeploy/config/pubDomainList.json). +2. docs.geostandaarden.nl. +3. register.geostandaarden.nl. + +Naamgevinsregels voor pubDomain: + +- Lowercase +- Geen spaties + +| Pubdomain | Omschrijving | Herkomst | status | GitHub Team | Beslissing | +| -------------- | -------------------------------------------------------- | -------------------------- | ------------------------- | ------------------------------------------------------------- | --------------------------------------- | +| 3dbv | 3D basisvoorziening | docs.geostandaarden.nl | inactief (gemigreerd) | | mag niet meer gebruikt worden | +| api | Kennisplatform APIs | respec utils | | [API team](https://github.com/orgs/Geonovum/teams/api-team) | OK | +| basisgeometrie | Informatiemodel Basisgeometrie | register.geostandaarden.nl | zit op docs bij nen3610 | | niet gebruiken eigenlijk xsd redirecten | +| bgt | Basisregistratie grootschalige topografie | docs.geostandaarden.nl | | [BGT team](https://github.com/orgs/Geonovum/teams/bgt-team) | Arnoud vragen | +| brt | Informatiemodellen Basisregistratie Topografie | register.geostandaarden.nl | | [BRT team](https://github.com/orgs/Geonovum/teams/brt-team) | OK | +| crs | Coördinaatreferentiesystemen | docs.geostandaarden.nl | | [CRS team](https://github.com/orgs/Geonovum/teams/crs-team) | OK | +| cvgg | Informatiemodel Geluid | docs.geostandaarden.nl | duplicaat van img | | OK | +| disgeo | DisGeo | respec utils | | | OK | +| dsgo | Digitaal Stelsel Gebouwde Omgeving | docs.geostandaarden.nl | | | OK (rare uri) | +| dso | Digitaal Stelsel Omgevingswet | respec utils | duplicaten: tpod imow ow | [DSO team](https://github.com/orgs/Geonovum/teams/dso-team) | OK | +| eu | | docs.geostandaarden.nl | | [EU team](https://github.com/orgs/Geonovum/teams/eu-team) | OK (rare uri en werkversie weg) | +| g4w | | docs.geostandaarden.nl | | | groeperen? | +| gbd | | docs.geostandaarden.nl | | | groeperen? | +| geobag | | docs.geostandaarden.nl | | | OK | +| gsw | | docs.geostandaarden.nl | | | groeperen? | +| imaer | Informatiemodel AERIUS | register.geostandaarden.nl | | | OK | +| imev | Informatiemodel Externe Veiligheid | docs.geostandaarden.nl | | [IMEV team](https://github.com/orgs/Geonovum/teams/api-team) | OK | +| img | Informatiemodel Geluid | respec utils | duplicaat: cvgg | [IMG team](https://github.com/orgs/Geonovum/teams/img-team) | redirecten naar cvgg | +| imgeo | Informatiemodel Grootschalige Geografie | docs.geostandaarden.nl | | | Arnoud vragen | +| imka | Informatiemodel Klimaatadaptatie | docs.geostandaarden.nl | | | OK | +| imkad | Informatiemodel Kadaster | register.geostandaarden.nl | | [IMKA team](https://github.com/orgs/Geonovum/teams/imka-team) | OK | +| imkl | Informatiemodel Kabels en Leidingen | register.geostandaarden.nl | duplicaat: kl | [IMKL team](https://github.com/orgs/Geonovum/teams/imkl-team) | Zou kl moeten worden | +| imle | | docs.geostandaarden.nl | | | OK (niet netjes gepubliceerd) | +| imro | Informatiemodel Ruimtelijke Ordening | register.geostandaarden.nl | duplicaat: ro | | liefst naar RO | +| imow | Informatiemodel Omgevingswet | register.geostandaarden.nl | duplicaten: tpod ow dso | | liefst weg | +| kl | IMKL | respec utils | duplicaat: imkl | | OK | +| md | Metadata | respec utils | duplicaat: metadata | | OK | +| mim | Metamodel Informatie Modellering (MIM | respec utils | | | OK | +| metadata | Nederlandse metadata profielen voor datasets en services | register.geostandaarden.nl | duplicaat: md | | verplaatsen naar md?? | +| nen3610 | NEN3610-Linkeddata | respec utils | | | OK | +| ngii | | docs.geostandaarden.nl | | | OK | +| oov | | docs.geostandaarden.nl | | | OK | +| ow | Standaarden omgevingswet | respec utils | duplicaten: tpod imow dso | | OK | +| ro | RO Standaarden | respec utils | duplicaat: imro | | OK | +| rwgs | Raamwerk van Geo-standaarden | respec utils | | | groeperen? | +| serv | Services | respec utils | | | groeperen? | +| tpod | Toepassingsprofiel omgevingsdocumenten | respec utils | duplicaten: ow imow dso | | OK | +| vg | Informatiemodel Vastgoedgebruik | respec utils | | | OK | +| visu | Visualisatie | respec utils | | | groeperen? | +| vtm | | docs.geostandaarden.nl | is eigenlijk metadata | | verhuizen naar MD | +| wp | Whitepaper Geostandaarden | respec utils | ook een raar pubdomain | | verhuizen naar ngii | + +## LocalBiblio + +In de localBiblio variabele worden Referenties naar andere documenten gezet. +Voordat je hier citaten toevoegt, loont het de moeite om eerst in de +[https://www.specref.org/](SpecRef) van ReSpec zelf te kijken. Pas als je een +verwijzing niet vindt in SpecRef voeg je hem hier toe! + +Verwijzen naar een bibliografieelement gebeurt als volgt `[[ID]]`. De dubbele +haakjes zorgen ervoor dat er blokhaken om de verwijzing staan in de tekst. Je +kunt ook aangeven dat een verwijzing normatief is door er een uitroepteken voor +te zetten `[[!ID]]` + +## Voorbeeld config.js + +``` +let respecConfig = { + useLogo: true, + useLabel: true, + // title is verplicht! Neem hier de titel van het document op ---------------------- + title: "[Neem titel op in config.js]", + //-- specStatus is verplicht! (activeer 1 van de volgende) -------------------------- + specStatus: "wv", // Werkversie + + //-- specType is verplicht bij alle andere dan BASIS --------------------------------- + specType: "HR", // HandReiking + + //-- pubDomain is verplicht! (komt in de URL) ------------------------------------- + pubDomain: "TODO", + //-- license: voor de geldende gebruiksvoorwaarden. Default is cc-by. + //licence: "cc-by-nd", // bronvermelding, geen afgeleide werken (default) + //licence: "cc0", // Public Domain Dedication + licence: "cc-by", // Attribution, met bronvermelding + //-- shortName is verplicht! (komt in de URL: kies logische afkorting)-------------- + shortName: "NL-ReSpec-GN-template", + //-- publishDate is verplicht ------------------------------------------------------- + //-- NB: in de werkversie uitzetten, want dan pakt Respec de pushdate --------------- + //publishDate: "2023-03-28", + //eventueel is het mogelijk een versienummer mee te geven, maar bij Geonovum werken we gewoonlijk alleen met datum als onderdeel van de permanente URI. + //publishVersion: "0.0.2", + //previousVersion: "0.0.1", + //-- Voor dit blok geldt: alleen als er eerdere versies zijn en altijd beiden aan/uit! + //previousPublishDate: "2014-05-01", + //previousMaturity: "CV", + //-- de namen van de Editor(s) / Redacteur(en)--------------------------------------- + //-- vul in: per Editor: name:, company:, companyURL: ------------------------------- + editors: + [ + { + name: "voornaam achternaam", + company: "Geonovum", + companyURL: "https://www.geonovum.nl", + } + ], + //-- de namen van de auteur(s) ------------------------------------------------------ + //-- vul in: per auteur: name:, company:, companyURL: ------------------------------- + authors: + [ + { + name: "voornaam achternaam", + company: "Geonovum", + companyURL: "https://www.geonovum.nl", + } + ], + //neem hier de URL van de github repository op waar het respec document in staat + github: "https://github.com/Geonovum/NL-ReSpec-GN-template", + // Create PDF and link to file in header (optional): + alternateFormats: [ + { + label: "pdf", + uri: "template.pdf", + }, + ], +}; +``` + +De file config.js is een stukje javascript (JSON) code, het bevat alle mogelijke +waarden voor de verschillende versies die wij hanteren bij Geonovum. In de file +zelf staat aangegeven welke waarden verplicht zijn, en uit welke waarden te +kiezen is. In bovenstaand voorbeeld gaat het om een 'Werkversie van een +standaard'. + +### Content: bestanden '\*.md' + +De 'echte' content wordt gemaakt in het formaat 'Markdown'. Er is een aantal +editors beschikbaar die dat formaat ondersteunen. Zie hiervoor +Hoofdstuk 3. Het is handig om voor elk hoofdstuk +een aparte Markdown file te maken, want dan blijven de bestanden beperkt in +grootte, en zijn er gemakkelijker werkafspraken te maken over wie wanneer in +welke file aan het editen is. + +### Content: Afbeeldingen '\*.png' + +Afbeeldingen worden als '.png' of '.svg' bestand neergezet in de map 'media'. In +je Markdown document neem je gewoon een plaatje op zoals je in Word gewend bent. +Writage en ReSpec zorgen ervoor dat de plaatjes worden getoond. + +## ReSpec Frontend + +### De knop 'ReSpec' + +De knop 'ReSpec' rechtsboven in de frontend van ReSpec, bevat een aantal handige +functies. Als je klikt op de knop, verschijnt het vervolgscherm met een viertal +functies. + +Elk van de functies wordt hieronder uitgelegd. + +![media/image25.png](media/image25.png) + +### Bewaar snapshot + +![media/image26.png](media/image26.png) + +### Doorzoek SpecRef + +![media/image27.png](media/image27.png) ![media/image28.png](media/image28.png) + +De gevonden zoekresultaten kunnen worden overgenomen in het ReSpec document. + +### Lijst van definities + +Zie: [definitielijst maken](ReSpec-definitielijst-maken.md) + +## HTML ingebed in ReSpec + +Omdat wij ervoor hebben gekozen om documenten te schrijven in Markdown, +gebruiken wij niet alle ReSpec functionaliteit. In dit hoofdstuk worden de +speciale ReSpec functies beschreven die als HTML code in het Markdown document +kunnen wordnen opgenomen, of die in de door respec gegenereerde HTML file kunnen +worden neergezet. Het gebruik van deze functionaliteit vereist dus wel HTML +kennis. + +## HTML voor Afbeeldingen + +Een lijst van afbeeldingen kan door ReSpec automatisch worden gegenereerd, maar +dan moet er wel aan een aantal ReSpec specifieke voorwaarden worden voldaan: + +In Index.html komt ergens te staan: + +```html +
+ +
The water flows from bucket A to bucket B.
+
+``` + +In de documenten worden de afbeeldingen op de volgende manier neergezet: + +```html +
+ +
The water flows from bucket A to bucket B.
+
+``` + +NB: `
` inclusief uniek ID en een ge-embedde `
` zijn +verplicht! + +Eventuele referenties naar plaatjes doe je op e volgende manier: + +```html +

The flowchart shown in is quite impressive.

+
+``` + +## Referentie naar GitHub issues + +ReSpec ondersteunt ook een koppeling naar issues die zijn gemeld op GitHub. Jek +kan referenties opnemen naar individuele issues. Ook is het mogelijk om een +lijst met alle issues op te nemen in je document. + +Om GitHub issues op te nemen moet je in 'config.js' een referentie opnemen naar +de GitHub repository. + +``` +issueBase: "https://github.com/Geonovum/MIM-Werkomgeving/issues/" +``` + +Een referentie naar een issue neem je als volgt op: + +``` +
+``` + +Waarbij data-number het issuenummer is. + +Een lijst met issues kan je toevoegen met de volgende HTML code: + +``` +
+ +
+ +``` + +## Foutmeldingen en waarschuwingen + +![media/image29.png](media/image29.png) ![media/image30.png](media/image30.png) + +In dit geval is er een tikfout gemaakt bij de naam van de Markdownfile die +ge-include wordt. Het moet natuurlijk `H2-Testcases.md` zijn. + +![media/image31.png](media/image31.png) + +Een voorbeeld van een waarschuwing. Klikken hierop geeft je je de waarschuwing. + +In het onderstaande voorbeeld meldt ReSpec dat er een `

` header ontbreekt in +het Markdown document. + +![media/image32.png](media/image32.png) + +# Publiceren in ReSpec + +In dit hoofdstuk staan checklists die je kan gebruiken als je vanuit GitHub en +ReSpec “Versies” gaat aanmaken. Bijvoorbeeld hoe maak je een nieuwe GitHub +repository aan, of hoe maak je vanuit een werkversie een consultatieversie aan, + +## Controles voor publicatie + +Controleer de volgende onderwerpen voor iedere publicatie: + +- Controleer op **WCAG** regels. Bij het pushen van een ReSpec document naar + GitHub wordt automatisch een WCAG rapport geschreven. Dit is te vinden onder + 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar + 'Check/WCAG'). +- Controleer op **Broken links**. Bij het pushen van een ReSpec document naar + GitHub wordt automatisch op broken links gechecked. Dit is te vinden onder + 'Actions'. Kies hier de commit die je gedaan hebt en je ziet daar + 'Check/Links'). +- Controleer of de **HTML correct** is: maak een snapshot aan en biedt het aan + aan de [W3C validator](https://validator.w3.org) +- C + +## Consultatie versie (CV) maken + +1. Edit en controleer config.js - configureer alles goed voor een + consultatieversie + - `specStatus`:`"GN-CV"` + - `publishDate`: moet ingevuld zijn met de datum van publicatie van de + consultatieversie. `"jjjj-mm-dd"`, + - `Shortname`: moet ingevuld zijn met korte naam voor het document. Dit + wordt onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van + versies). + - Als er al eerder een versie gepubliceerd is (stabiele versie, dus + afgezien van de werkversie in github), kan Respec bovenin een document + de navigatie naar vorige versie goed genereren. Daarvoor moet je ook + invullen: + - `Previousmaturity`: wat de status toen was. + - `Previousmaturity`: wat de status toen was. +1. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) +1. Kies “HTML” en noem dit bestand “snapshot.html” +1. Commit het en push het naar dezelfde folder als waar `index.html` staat in je + Github-repository + +### Consultatieverise met ftp + +> **Note**: uitwerken + +Omdat de webhook nogal eens problemen oplevert is er ook een proces voor het +publiceren met ftp. In het kort is het als volgt: + +1. Zet alles klaar in github (zoals bij de webhook). +2. Vraag een beheerder om de boel naar docs.geostandaarden.nl om te zetten. + +### Consultatieversie maken met behulp van webhook + +[Klik hier](/Publiceren/) voor een beschrijving over hoe je een webhook eenmalig +configureert voor een repository. over het toepassen van de webhook. + +1. Maak een release tag conform de naamgevingsconventie: + `\{specStatus\}-\{specType\}-\{shortName\}-\{publishDate\}` +1. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd + zijn als ‘webhook’ in de github repository!) het `snapshot.html` en de + bijbehorende afbeeldingen naar + [docs.geostandaarden.nl]). +1. Na succesvolle publicatie: + - zet de `specStatus` in `config.js` terug op `"GN-WV"` + - Vul `previousMaturity` in met `"GN-CV"` + - Vul `previousPublishDate` in met de datum van de zojuist gepubliceerde + consultatieversie + + + +## Vaststellingsversie (VV) maken + +1. Edit en controleer config.js - configureer alles goed voor een + vaststellingsversie + - specStatus: "GN-VV" + - publishDate: moet ingevuld zijn met de datum van publicatie van de + consultatieversie. "jjjj-mm-dd", + - Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt + onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van + versies). + - Als er al eerder een versie gepubliceerd is (stabiele versie, dus + afgezien van de werkversie in github), kan Respec bovenin een document + de navigatie naar vorige versie goed genereren. Daarvoor moet je ook + invullen: + - Previousmaturity: wat de status toen was. + - Previousmaturity: wat de status toen was. +2. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) +3. Kies “HTML” en noem dit bestand “snapshot.html” +4. Commit het en push het naar dezelfde folder als waar index.html staat in je + Github repository +5. Maak een release tag conform de naamgevingsconventie: + \{specStatus\}-\{specType\}-\{shortName\}-\{publishDate\} +6. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd + zijn als ‘webhook’ in de github repository!) het snapshot.html en de + bijbehorende afbeeldingen naar +7. Na succesvolle publicatie: + - zet de specStatus in config.js terug op GN-WV + - Vul previousMaturity in met GN-CV + - Vul previousPublishDate in met de datum van de zojuist gepubliceerde + consultatieversie + +## Definitieve versie (DEF) maken + +1. Edit en controleer config.js - configureer alles goed voor een definitieve + versie + - specStatus: "GN-DEF", + - publishDate: moet ingevuld zijn met de datum van publicatie van de + definitieve versie. "jjjj-mm-dd", + - Shortname: moet ingevuld zijn met korte naam voor het document. Dit wordt + onderdeel van de URL. Moet uniek zijn binnen pubdomain (afgezien van + versies). + - Als er al eerder een versie gepubliceerd is (stabiele versie, dus afgezien + van de werkversie in github), kan Respec bovenin een document de navigatie + naar vorige versie goed genereren. Daarvoor moet je ook invullen: + - Previousmaturity: wat de status toen was. + - previousPublishDate: vorige publicatiedatum (jjjj-mm-dd) +2. Maak een snapshot (met de knop “Bewaar Snapshot” vanuit Respec) +3. Kies “HTML” en noem dit bestand “snapshot.html” +4. Commit het en push het naar dezelfde folder als waar index.html staat in je + Github repository +5. Maak een release tag conform de naamgevingsconventie: + {specStatus}-{specType}-{shortName}-{publishDate} +6. Het script kopieert nu automatisch (NB: dit moet wel eenmalig geconfigureerd + zijn als ‘webhook’ in de github repository!) het snapshot.html en de + bijbehorende afbeeldingen naar Hoe dit werkt + is beschreven in: +7. Na succesvolle publicatie: + - zet de specStatus in config.js terug op GN-WV + - Vul previousMaturity in met GN-DEF + - Vul previousPublishDate in met de datum van de zojuist gepubliceerde + definitieve versie diff --git a/docs/index.md b/docs/index.md index ca5080f..7ffa052 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,105 +1,105 @@ -# Welkom - -Welkom bij de beschrijving van de Geonovum Werkwijze. Deze helpfiles beschrijven -welke tools we gebruiken voor het maken en beheren van de standaarden van -Geonovum. Deze tools staan in onderstaand overzicht. Daaronder staat de -publicatieomgeving van Geonovum beschreven. - -## Geonovum tooling - -- **Enterprise Architect** - - [Overzicht](EA.md) - - [Primitieve datatypes](EA-toepassing-standaarddatatypen.md): Handleiding - en toelichting op het toepassen van standaarddatatypes in - modelleeromgeving Geonovum. -- **GitHub**: - - [GitHub werkwijze](GitHub-Inleiding.md): algemene inleiding over GitHub. - - [GitHub handleiding](GitHub.md): Hoe maak je een account aan en hoe doe - je beheertaken. -- **Imvertor** - - [Imvertor](Imvertor.md): Verwijzingen naar verschillende onderwerpen met - betrekking tot Imvertor. -- **Markdown** - - [Markdown handleiding](Markdown.md): Handleiding werken met Markdown - voor ReSpec-documentatie. -- **ReSpec** - - [Respec handleiding](ReSpec.md): Algemene handleiding. - - [Respec code toepassen](ReSpec-code-toepassen.md): Richtlijnen voor het - toepassen van code in documentatie. - - [Respec definitielijst maken](ReSpec-definitielijst-maken.md): - Handleiding voor het maken van een definitielijst in - ReSpec-documentatie. -- **MIM** - - [Toolbox importeren](MIM-toolbox-importeren.md): Handleiding voor het - importeren van de MIM-toolbox in EA. - - [Toolbox genereren](MIM-toolbox-genereren.md): Handleiding voor het - maken van een EA-toolbox. - - [Toolbox genereren extensie](MIM-toolbox-genereren-extensie.md): - Handleiding voor het maken van een extensie op de MIM-toolbox. -- **Subversion (SVN)** - - [Subversion installeren voor EA](SVN-importeren-bestaand-project.md): - Installatie SVN en informatiemodel in versiebeheer zetten. - - [Subversion importeren bestaand project](SVN-installeren-voor-EAP.md): - Packages importeren vanuit SVN in EA. -- **GML** - - [GML](GML.md): Toelichting GML, XSD en Namespaces. -- **Ontologie** - - [Ontologie](Handleiding-ontologie-maken-en-publiceren.md): Handleiding - voor het maken en publiceren van een ontologie. -- **Word Conversies** - - [Word2werkversie](WordConversies.md) - -Voor licenties of de interne beheerder van de tooling kun je terecht op -[intranet](https://stichtinggeonovum.sharepoint.com/:b:/r/sites/FBICT/Gedeelde%20documenten/General/wat%20staat%20waar/Tooling_en_Beheerders.pdf?csf=1&web=1&e=aEcKjl) - -### Documentatie elders - -De documentatie van de werkwijze is niet alleen hier vastgelegd. Links naar -andere documenten: - -- [werkomgeving modelleren](werkomgeving-modelleren.md). -- [werkwijze modelleren](werkwijze-modelleren.md). -- [geonovum werkwijze modelleren](geonovum-werkwijze-modelleren.md) - -## Geonovum publicatieomgeving - -Verschillende onderdelen van standaarden worden op verschillende plaatsen -gepubliceerd. De publicatieomgeving ziet er als volgt uit - -![Architectuurplaatje](https://raw.githubusercontent.com/Geonovum/DrawIO/master/GeonovumInterneArchitectuur.drawio.png) -### Documenten (docs.geostandaarden.nl) - -Standaarden en technische documentatie. Voor een nette lijst van pubdomains op -docs.geostandaarden.nl moet de de volgende lijst up-to-date zijn: -[pubDomainList.json](https://github.com/Geonovum/respec-utils/blob/master/src/autodeploy/config/pubDomainList.json) - -### Het Technisch Register (register.geostandaarden.nl) - -Technische onderdelen van de standaard worden op: -[register.geostandaarden.nl](https://register.geostandaarden.nl) gezet. Hoe je -dit met een webhook kan doen staat beschreven in: -[technisch-register-2019](https://github.com/Geonovum/technisch-register-2019/blob/master/documentatie/Handleiding%20voor%20beheerders%20informatiemodellen.md) - -### Ontologieën (modellen.geostandaarden.nl) - -Er is één ontologie gepubliceerd: die van NEN 3610. - -Dit is uitgelegd in de [handleiding ontologie maken](Handleiding-ontologie-maken-en-publiceren.md) - -### Conceptenbibliotheek (definities.geostandaarden.nl) - -## MkDocs voor deze handleiding - -De handleiding wordt beheerd in [MkDocs](https://www.mkdocs.org/). Dit is een -lichtgewicht tool die een collectie Markdown handleidingen omzet in een -navigeerbare handleiding. De handleiding staat op -[github pages](https://github.com/Geonovum/handleiding-tooling). De -bronbestanden staan in: -[handleiding-tooling](https://github.com/Geonovum/handleiding-tooling). - -Je kunt mkdocs ook lokaal installeren. Dan kun je live je edits volgen in je -browser: [http://127.0.0.1:8000/](http://127.0.0.1:8000/) met het commando: - -```shell -mkdocs serve -``` +# Welkom + +Welkom bij de beschrijving van de Geonovum Werkwijze. Deze helpfiles beschrijven +welke tools we gebruiken voor het maken en beheren van de standaarden van +Geonovum. Deze tools staan in onderstaand overzicht. Daaronder staat de +publicatieomgeving van Geonovum beschreven. + +## Geonovum tooling + +- **Enterprise Architect** + - [Overzicht](EA.md) + - [Primitieve datatypes](EA-toepassing-standaarddatatypen.md): Handleiding + en toelichting op het toepassen van standaarddatatypes in + modelleeromgeving Geonovum. +- **GitHub**: + - [GitHub werkwijze](GitHub-Inleiding.md): algemene inleiding over GitHub. + - [GitHub handleiding](GitHub.md): Hoe maak je een account aan en hoe doe + je beheertaken. +- **Imvertor** + - [Imvertor](Imvertor.md): Verwijzingen naar verschillende onderwerpen met + betrekking tot Imvertor. +- **Markdown** + - [Markdown handleiding](Markdown.md): Handleiding werken met Markdown + voor ReSpec-documentatie. +- **ReSpec** + - [Respec handleiding](ReSpec.md): Algemene handleiding. + - [Respec code toepassen](ReSpec-code-toepassen.md): Richtlijnen voor het + toepassen van code in documentatie. + - [Respec definitielijst maken](ReSpec-definitielijst-maken.md): + Handleiding voor het maken van een definitielijst in + ReSpec-documentatie. +- **MIM** + - [Toolbox importeren](MIM-toolbox-importeren.md): Handleiding voor het + importeren van de MIM-toolbox in EA. + - [Toolbox genereren](MIM-toolbox-genereren.md): Handleiding voor het + maken van een EA-toolbox. + - [Toolbox genereren extensie](MIM-toolbox-genereren-extensie.md): + Handleiding voor het maken van een extensie op de MIM-toolbox. +- **Subversion (SVN)** + - [Subversion installeren voor EA](SVN-importeren-bestaand-project.md): + Installatie SVN en informatiemodel in versiebeheer zetten. + - [Subversion importeren bestaand project](SVN-installeren-voor-EAP.md): + Packages importeren vanuit SVN in EA. +- **GML** + - [GML](GML.md): Toelichting GML, XSD en Namespaces. +- **Ontologie** + - [Ontologie](Handleiding-ontologie-maken-en-publiceren.md): Handleiding + voor het maken en publiceren van een ontologie. +- **Word2XXX** + - [Word2werkversie](WordConversies.md) + +Voor licenties of de interne beheerder van de tooling kun je terecht op +[intranet](https://stichtinggeonovum.sharepoint.com/:b:/r/sites/FBICT/Gedeelde%20documenten/General/wat%20staat%20waar/Tooling_en_Beheerders.pdf?csf=1&web=1&e=aEcKjl) + +### Documentatie elders + +De documentatie van de werkwijze is niet alleen hier vastgelegd. Links naar +andere documenten: + +- [werkomgeving modelleren](werkomgeving-modelleren.md). +- [werkwijze modelleren](werkwijze-modelleren.md). +- [geonovum werkwijze modelleren](geonovum-werkwijze-modelleren.md) + +## Geonovum publicatieomgeving + +Verschillende onderdelen van standaarden worden op verschillende plaatsen +gepubliceerd. De publicatieomgeving ziet er als volgt uit + +![Architectuurplaatje](https://raw.githubusercontent.com/Geonovum/DrawIO/master/GeonovumInterneArchitectuur.drawio.png) +### Documenten (docs.geostandaarden.nl) + +Standaarden en technische documentatie. Voor een nette lijst van pubdomains op +docs.geostandaarden.nl moet de de volgende lijst up-to-date zijn: +[pubDomainList.json](https://github.com/Geonovum/respec-utils/blob/master/src/autodeploy/config/pubDomainList.json) + +### Het Technisch Register (register.geostandaarden.nl) + +Technische onderdelen van de standaard worden op: +[register.geostandaarden.nl](https://register.geostandaarden.nl) gezet. Hoe je +dit met een webhook kan doen staat beschreven in: +[technisch-register-2019](https://github.com/Geonovum/technisch-register-2019/blob/master/documentatie/Handleiding%20voor%20beheerders%20informatiemodellen.md) + +### Ontologieën (modellen.geostandaarden.nl) + +Er is één ontologie gepubliceerd: die van NEN 3610. + +Dit is uitgelegd in de [handleiding ontologie maken](Handleiding-ontologie-maken-en-publiceren.md) + +### Conceptenbibliotheek (definities.geostandaarden.nl) + +## MkDocs voor deze handleiding + +De handleiding wordt beheerd in [MkDocs](https://www.mkdocs.org/). Dit is een +lichtgewicht tool die een collectie Markdown handleidingen omzet in een +navigeerbare handleiding. De handleiding staat op +[github pages](https://github.com/Geonovum/handleiding-tooling). De +bronbestanden staan in: +[handleiding-tooling](https://github.com/Geonovum/handleiding-tooling). + +Je kunt mkdocs ook lokaal installeren. Dan kun je live je edits volgen in je +browser: [http://127.0.0.1:8000/](http://127.0.0.1:8000/) met het commando: + +```shell +mkdocs serve +``` diff --git a/mkdocs.yml b/mkdocs.yml index 0aad406..b2ffc0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,4 +29,4 @@ nav: - 'SVN importeren bestaand project': SVN-importeren-bestaand-project.md - GML: GML.md - Ontologie: Handleiding-ontologie-maken-en-publiceren.md - - WordConversies: WordConversies.md + - Word2XXX: WordConversies.md