From a76493bfd0777f49c10e0e7b543b1f4754efca1b Mon Sep 17 00:00:00 2001 From: Wilko Quak Date: Tue, 27 Feb 2024 23:49:10 +0100 Subject: [PATCH] respec aangepast --- .markdownlint.json | 7 + .prettierrc | 8 + docs/EA-toepassing-standaarddatatypen.md | 75 ++-- docs/EA.md | 23 +- docs/Markdown.md | 43 +- docs/ReSpec-Checklists.md | 88 ----- docs/ReSpec.md | 478 ++++++++++++++++++----- docs/index.md | 86 ++-- mkdocs.yml | 3 +- 9 files changed, 540 insertions(+), 271 deletions(-) create mode 100644 .markdownlint.json create mode 100644 .prettierrc delete mode 100644 docs/ReSpec-Checklists.md diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..66fca2c --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,7 @@ +{ + "default": true, + "MD003": { "style": "atx" }, + "MD007": { "indent": 4 }, + "MD013": { "line_length": 80, "code_blocks": false, "heading_line_length": 200, "tables": false}, + "no-hard-tabs": false +} diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..d9ba23e --- /dev/null +++ b/.prettierrc @@ -0,0 +1,8 @@ +{ + "tabWidth": 4, + "useTabs": false, + "singleQuote": true, + "endOfLine": "lf", + "proseWrap": "always", + "printWidth": 80 +} diff --git a/docs/EA-toepassing-standaarddatatypen.md b/docs/EA-toepassing-standaarddatatypen.md index d47115b..534ca00 100644 --- a/docs/EA-toepassing-standaarddatatypen.md +++ b/docs/EA-toepassing-standaarddatatypen.md @@ -1,65 +1,86 @@ # EA - Gebruik standaarddatatypes (intern) -> **Note** -> `@Gerard`: screenshots toevoegen +> **Note** > `@Gerard`: screenshots toevoegen -Bij Geonovum gebruiken we een aantal voorgedefineerde datatypes. Deze zijn opgedeeld in drie categorieën: +Bij Geonovum gebruiken we een aantal voorgedefineerde datatypes. Deze zijn +opgedeeld in drie categorieën: - 1. MIM11 -- Dit package bevat de datatypes die voorgedefinieerd zijn in het [MIM](https://docs.geostandaarden.nl/mim/mim/) - 1. Geonovum geometrie -- Dit package bevat de geometrietypes uit [ISO19107](https://docs.geostandaarden.nl/nen3610/gimeg/). Deze zijn in een los package gestopt zodat andere partijen die alleen geometrie willen gebruik deze types kunnen gebruiken, - 1. Geonovum algemeen -- In dit package zitten alle overige datatypes die in Geonovum UML packages gebruikt worden. Merk op dat in dit package ook wat geometrie types zitten; dit zijn types die niet uit ISO-19107 komen. Bij voorkeur worden deze niet in de modellering gebruikt. +1. MIM11 -- Dit package bevat de datatypes die voorgedefinieerd zijn in het + [MIM](https://docs.geostandaarden.nl/mim/mim/) +1. Geonovum geometrie -- Dit package bevat de geometrietypes uit + [ISO19107](https://docs.geostandaarden.nl/nen3610/gimeg/). Deze zijn in een + los package gestopt zodat andere partijen die alleen geometrie willen + gebruik deze types kunnen gebruiken, +1. Geonovum algemeen -- In dit package zitten alle overige datatypes die in + Geonovum UML packages gebruikt worden. Merk op dat in dit package ook wat + geometrie types zitten; dit zijn types die niet uit ISO-19107 komen. Bij + voorkeur worden deze niet in de modellering gebruikt. -In: svn.geostandaarden.nl/Datatypes zijn drie collecties met primitieve types opgenomen die alle primitieve types bevat die in Geonovum UML modellen gebruikt +In: svn.geostandaarden.nl/Datatypes zijn drie collecties met primitieve types +opgenomen die alle primitieve types bevat die in Geonovum UML modellen gebruikt -Deze packages zijn in beheer bij @wilkoquak. Het is de bedoeling dat er in [Imvertor] een mapping komt die precies overeenkomt het deze drie collecties types +Deze packages zijn in beheer bij @wilkoquak. Het is de bedoeling dat er in +[Imvertor] een mapping komt die precies overeenkomt het deze drie collecties +types ## Geometrie datatypes -In dit package zitten de geometrische datatypes zoals genoemd in [ISO19107:2003](https://www.iso.org/standard/26012.html). +In dit package zitten de geometrische datatypes zoals genoemd in +[ISO19107:2003](https://www.iso.org/standard/26012.html). ![Geometrie](media/GML-geometrie.png) ## MIM datatypes -In dit package zitten de geometrische datatypes zoals genoemd in [MIM](https://docs.geostandaarden.nl/mim/mim/#datatypen). +In dit package zitten de geometrische datatypes zoals genoemd in +[MIM](https://docs.geostandaarden.nl/mim/mim/#datatypen). ![MIM](media/MIM11.png) ## Geonovum datatypes -In dit package zitten datatypes die niet in de twee eerdergenoemde packages vallen maar wel ergens gebruikt zijn bij Geonovum. +In dit package zitten datatypes die niet in de twee eerdergenoemde packages +vallen maar wel ergens gebruikt zijn bij Geonovum. ![Geonovum datatypes](media/Geonovum-algemeen.png) -> **Note** -> `@Wilko` wil jij een korte toelichting geven op de driedeling. Wat vind je waar en waarom? +> **Note** > `@Wilko` wil jij een korte toelichting geven op de driedeling. Wat +> vind je waar en waarom? -Alle basic datatypes binnen UML zouden in één van deze packages moeten staan. Als dat niet zo is neem dan contact op met `@Wilko`. +Alle basic datatypes binnen UML zouden in één van deze packages moeten staan. +Als dat niet zo is neem dan contact op met `@Wilko`. Je vindt ze op SVN: `svn://svn.geostandaarden.nl/Datatypes`: -> **Warning** -> Onderstaande naamgeving klopt niet meer. Dit is door Wilko in overleg aangepast. `@Gerard`: graag updaten! +> **Warning** Onderstaande naamgeving klopt niet meer. Dit is door Wilko in +> overleg aangepast. `@Gerard`: graag updaten! - 1. `MIM11.xml` - 1. `Geonovum-algemeen.xml` - 1. `Geonovum-geometrie.xml` +1. `MIM11.xml` +1. `Geonovum-algemeen.xml` +1. `Geonovum-geometrie.xml` -> **Note** -> Er is nu nog een `Datatyps.xml` waarin alle datatypes zitten deze gaat binnenkort verdwijnen. +> **Note** Er is nu nog een `Datatyps.xml` waarin alle datatypes zitten deze +> gaat binnenkort verdwijnen. ## Datatypes importeren voor gebruik in EA -Lees hoe je deze types als packages importeert in de handleiding [SVN - importeren bestaand project](https://github.com/Geonovum/imvertor/blob/main/handleidingen/SVN%20-%20importeren%20bestaand%20project.md). +Lees hoe je deze types als packages importeert in de handleiding +[SVN - importeren bestaand project](https://github.com/Geonovum/imvertor/blob/main/handleidingen/SVN%20-%20importeren%20bestaand%20project.md). ## Gebruik packages in EA -Deze packages zijn bedoeld voor toepassing binnen een informatiemodel. Het is niet de bedoeling om de packages in of uit te checken; er hoeven immers geen wijzigingen in aangebracht te worden. +Deze packages zijn bedoeld voor toepassing binnen een informatiemodel. Het is +niet de bedoeling om de packages in of uit te checken; er hoeven immers geen +wijzigingen in aangebracht te worden. -> **Note** -> `@Wilko` en `@Paul`: Eigenlijk zou je hier een beperkt aantal mensen schrijfrechten willen geven en de rest alleen lees-rechten. Ik heb zoiets nog niet kunnen vinden. `@Gerart`: je kunt dat instellen door in configuratiebestandjes op svn.geostandaarden.nl, maar dan moet je daar wel bij kunnen. +> **Note** > `@Wilko` en `@Paul`: Eigenlijk zou je hier een beperkt aantal +> mensen schrijfrechten willen geven en de rest alleen lees-rechten. Ik heb +> zoiets nog niet kunnen vinden. `@Gerart`: je kunt dat instellen door in +> configuratiebestandjes op svn.geostandaarden.nl, maar dan moet je daar wel bij +> kunnen. ## Verwijzen naar een datatype -> **Note** -> `@Gerard`: In deze paragraaf een uitleg opnemen hoe je vanuit Enterprise Architect een voorgedefineerd datatype opneemt bij een `«Attribuutsoort»`. | +> **Note** > `@Gerard`: In deze paragraaf een uitleg opnemen hoe je vanuit +> Enterprise Architect een voorgedefineerd datatype opneemt bij een +> `«Attribuutsoort»`. | diff --git a/docs/EA.md b/docs/EA.md index ec931e9..242a407 100644 --- a/docs/EA.md +++ b/docs/EA.md @@ -7,24 +7,19 @@ Instructie voor het gebruik van Enterprise Architect binnen Geonovum: ## Installatie -- Op de website is een proefversie van [Enterprise Architect](https://www.sparxsystems.eu/) te downloaden. -- Neem voor een licentie contact op met de [beheerder](https://stichtinggeonovum.sharepoint.com/:b:/r/sites/FBICT/Gedeelde%20documenten/General/wat%20staat%20waar/Tooling_en_Beheerders.pdf?csf=1&web=1&e=aEcKjl) +- Op de website is een proefversie van + [Enterprise Architect](https://www.sparxsystems.eu/) te downloaden. +- Neem voor een licentie contact op met de + [beheerder](https://stichtinggeonovum.sharepoint.com/:b:/r/sites/FBICT/Gedeelde%20documenten/General/wat%20staat%20waar/Tooling_en_Beheerders.pdf?csf=1&web=1&e=aEcKjl) +## De MIM toolbox +Importeer de MIM toolbox: -## De MIM toolbox +Zie: [MIM toolbox importeren](MIM-toolbox-importeren.md) + +Externe links: -Externe links: - [Handleiding gebruik MIM-toolbox](https://github.com/Geonovum/MIM-Werkomgeving/blob/master/UML%20profieltooling/werkversie1.1.1/README.md) - [Handleiding genereren MIM-profiel](https://github.com/Geonovum/MIM-Werkomgeving/tree/master/UML%20profieltooling#readme) - [Handleiding genereren Extensie MIM-toolbox](https://github.com/Geonovum/MIM-Werkomgeving/blob/master/UML%20profieltooling/how_to_extensie_op_toolbox.md) - - -Stappen: -- Download de MIM Toolbox. Deze is te vinden op: [github](https://github.com/Geonovum/MIM/tree/master/informatiemodel) -- Start Enterprise Architect en open de project browser (Start→Design→Browser) -- Open het resources tabje en klik met de rechtermuis op ‘MDG Technologies’. -- Kies ‘Import Technology’ en importeer de MIM Toolbox. -- Deze is nu zichtbaar onder ‘Model Technologies’: - -![MIM toolbox](media/MIM-toolbox.png) \ No newline at end of file diff --git a/docs/Markdown.md b/docs/Markdown.md index 080e03e..37613f1 100644 --- a/docs/Markdown.md +++ b/docs/Markdown.md @@ -1,20 +1,32 @@ # Markdown -Voor het extern publiceren van documenten en standaarden gebruiken we [ReSpec](../ReSpec). Deze tool ondersteunt naast HTML en Javascript ook Markdown +Voor het extern publiceren van documenten en standaarden gebruiken we +[ReSpec](../ReSpec). Deze tool ondersteunt naast HTML en Javascript ook Markdown -[Markdown](https://nl.wikipedia.org/wiki/Markdown) is een lichtgewicht opmaaktaal op basis van platte tekst die zodanig ontworpen is dat het gemakkelijk valt te converteren naar HTML en andere. Markdown wordt vaak gebruikt voor de opmaak van project documentatie (README-bestanden), eenvoudige CMS-systemen en berichten in online fora. Je kunt Markdown in iedere simpele teksteditor bewerken. +[Markdown](https://nl.wikipedia.org/wiki/Markdown) is een lichtgewicht +opmaaktaal op basis van platte tekst die zodanig ontworpen is dat het +gemakkelijk valt te converteren naar HTML en andere. Markdown wordt vaak +gebruikt voor de opmaak van project documentatie (README-bestanden), eenvoudige +CMS-systemen en berichten in online fora. Je kunt Markdown in iedere simpele +teksteditor bewerken. -Het ontwerpdoel van de taal is leesbaarheid. Teksten geschreven met behulp van Markdown worden geacht al leesbaar te zijn voordat opmaak is toegepast op de tekst. Opmaakinstructies en tags zijn dan ook niet te vinden in pure Markdown. +Het ontwerpdoel van de taal is leesbaarheid. Teksten geschreven met behulp van +Markdown worden geacht al leesbaar te zijn voordat opmaak is toegepast op de +tekst. Opmaakinstructies en tags zijn dan ook niet te vinden in pure Markdown. ## Het viewen van Markdown in je broswer -Sommige browsers weigeren het openen van lokale bestanden, of negeren links naar locale bestanden. Dit kun je in de configuratie aanpassen: +Sommige browsers weigeren het openen van lokale bestanden, of negeren links naar +locale bestanden. Dit kun je in de configuratie aanpassen: ### Chrome Je moet twee dingen instellen: -- Local access: Toestaan dat je local files toont in Chrome, dat is een opstart argument. Kan je doen vanuit een cmd-prompt `%localappdata%\google\chrome\application\chrome --allow-file-access-from-files +- Local access: Toestaan dat je local files toont in Chrome, dat is een opstart + argument. Kan je doen vanuit een cmd-prompt + `%localappdata%\google\chrome\application\chrome + --allow-file-access-from-files - CORS Toestaan : zelfde soort oplossing: `--disable-web-security` Dit kan je ook in een snelkoppeling zetten als icoon op de desktop. @@ -23,7 +35,9 @@ Dit kan je ook in een snelkoppeling zetten als icoon op de desktop. In Firefox kan je dat instellen via de parameters. -In de adresbalk: about:config, dan het risico aanvaarden, en deze parameter veranderen: `security.fileuri.strict_origin_policy = false` (dus op false zetten) +In de adresbalk: about:config, dan het risico aanvaarden, en deze parameter +veranderen: `security.fileuri.strict_origin_policy = false` (dus op false +zetten) ## Tools voor Markdown @@ -39,4 +53,19 @@ In de adresbalk: about:config, dan het risico aanvaarden, en deze parameter vera | [mdlint](https://github.com/Laboratoria/mdlint) | Een style checker form markdown bestanden. Geef meldingen voor verkeerde markdown | | [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) | VSCode plugin. Klik rechtsonder op "Go Live" en je ReSpec doc wordt in live browser geopend. | -> **Note** > `@Wilko`: we kunnen nog styling regels voor markdown vastleggen. Maximale regellengte = 80 bijvoorbeeld. Dit zou in `.mdlintrc` of de configuratie van Prettier kunnen. +> **Note** `@Wilko`: we kunnen nog styling regels voor markdown vastleggen. +> Maximale regellengte = 80 bijvoorbeeld. Dit kan door een `.prettierrc` in de root van +> een project te zetten. + +Voorbeeld van '.prettierrc' gebruikt in dit project: + +```json +{ + "printWidth": 80, + "tabWidth": 2, + "useTabs": false, + "singleQuote": true, + "endOfLine": "lf", + "proseWrap": "always" +} +``` diff --git a/docs/ReSpec-Checklists.md b/docs/ReSpec-Checklists.md deleted file mode 100644 index b490af6..0000000 --- a/docs/ReSpec-Checklists.md +++ /dev/null @@ -1,88 +0,0 @@ -# Checklist voor publicatie - -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, - -## Een nieuwe ReSpec repository maken - -1. Maak een nieuw repository op basis van [de ReSpec template](https://github.com/Geonovum/NL-ReSpec-GN-template) en kies 'Use this template' -2. Check met behulp van GitHub Desktop het nieuwe repository uit 'File/Clone Repository...'. -3. Pas in `index.html` de betreffende velden aan -4. Pas in `config.js` de betreffende velden aan - - Pas het `specType` aan. (TODO: welke zijn er?) - - `pubDomain`: de documentgroep waar het doc toe behoort. Moet ingevuld zijn. Er is een lijst met afkortingen. Je mag ook een nieuwe groep bedneken maar geen wildgroei graag -5. Maak content in Markdown - -## 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'). -- Je kunt oook het HTML controleren: maak een snapshot aan en biedt het aan aan de [W3C validator](https://validator.w3.org) - -## 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 - -### 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]http://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 - -### Consultatieverise met behulp van webhook. - -> **Note**: uitwerken - -## 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 http://docs.geonovum.nl -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 -6. Maak een release tag conform de naamgevingsconventie: {specStatus}-{specType}-{shortName}-{publishDate} -7. 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 http://docs.geostandaarden.nl Hoe dit werkt is beschreven in: https://github.com/Geonovum/technisch-register-2019 -8. 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 \ No newline at end of file diff --git a/docs/ReSpec.md b/docs/ReSpec.md index 93c1abf..d8262a4 100644 --- a/docs/ReSpec.md +++ b/docs/ReSpec.md @@ -1,46 +1,70 @@ -# ReSpec +# 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. +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 eigenlijk achterhaald omdat we nu van de Logius Respec gebruik maken. - -# 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. +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. +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 +## De mapindeling van een ReSpec repository Dit levert een nieuw repository op met de onderstaande mappenstructuur. @@ -61,47 +85,91 @@ Hieronder staat een voorbeeld van zo’n mappenstructuur. ## 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 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: +Het bestand 'index.html' heeft een vaste indeling. Hieronder de structuur uit de +template: -``` +```html - - - - - - - - - - TODO: Vul hier de titel in - - - - - -
-
- - -
-
-
- -
-
-
- - + + + + + + + + + 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-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: +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: ```
@@ -109,55 +177,101 @@ In de HTML-Body geldt _vrijheid in gebondenheid_ De `
` en/of `
` re
\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 `
` 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. +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. +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). - -- _GN-WV, Werkversie_: Dit is de versie van het document waaraan wordt gewerkt. Deze versie is continu 'under-construction'. -- _GN-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. -- _GN-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'. -- _GN-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. +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). + +- _GN-WV, Werkversie_: Dit is de versie van het document waaraan wordt + gewerkt. Deze versie is continu 'under-construction'. +- _GN-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. +- _GN-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'. +- _GN-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. ### 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. +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
. +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. +- **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.. +- **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. +- **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. +- **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. +- **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. +- **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. +- **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. +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: +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. +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: @@ -211,9 +325,15 @@ Naamgevinsregels voor pubDomain: ## 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! +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]]` +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 @@ -278,21 +398,34 @@ let respecConfig = { }; ``` -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'. +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. +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. +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. +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. @@ -304,8 +437,7 @@ Elk van de functies wordt hieronder uitgelegd. ### Doorzoek SpecRef -![media/image27.png](media/image27.png) -![media/image28.png](media/image28.png) +![media/image27.png](media/image27.png) ![media/image28.png](media/image28.png) De gevonden zoekresultaten kunnen worden overgenomen in het ReSpec document. @@ -313,17 +445,23 @@ De gevonden zoekresultaten kunnen worden overgenomen in het ReSpec document. Zie: [definitielijst maken](ReSpec-definitielijst-maken.md) -## Hogere ReSpec +## 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. +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. -### Afbeeldingen +## 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: +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.
@@ -332,29 +470,35 @@ In Index.html komt ergens te staan: 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! +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 +## 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. +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. +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: @@ -373,17 +517,143 @@ Een lijst met issues kan je toevoegen met de volgende HTML code: ``` -### Foutmeldingen en waarschuwingen +## Foutmeldingen en waarschuwingen -![media/image29.png](media/image29.png) -![media/image30.png](media/image30.png) +![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. +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. +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'). +- Je kunt oook het HTML controleren: maak een snapshot aan en biedt het aan + aan de [W3C validator](https://validator.w3.org) + +## 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 + +### 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 + +### Consultatieverise met behulp van webhook + +> **Note**: uitwerken + +## 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 f11c979..94bbb9b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,62 +1,85 @@ # 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. +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. + - [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. + - [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. + - [Imvertor](Imvertor.md): Verwijzingen naar verschillende onderwerpen met + betrekking tot Imvertor. - **Markdown** - - [Markdown handleiding](Markdown.md): Handleiding werken met Markdown voor ReSpec-documentatie. + - [Markdown handleiding](Markdown.md): Handleiding werken met Markdown + voor ReSpec-documentatie. - **ReSpec** - [Respec handleiding](ReSpec.md): Algemene handleiding. - - [Respec checklist](ReSpec-Checklists.md): Checklist van handeling bij het - publiceren van een standaard middels ReSpec. - - [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. + - [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. + - [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. + - [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. + - [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) +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: +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) +- [werkomgeving modelleren](werkomgeving-modelleren.md). +- [werkwijze modelleren](werkwijze-modelleren.md). +- [geonovum werkwijze modelleren](geonovum-werkwijze-modelleren.md) -## Geonovum publicatieomgeving +## Geonovum publicatieomgeving -Verschillende onderdelen van standaarden worden op verschillende plaatsen gepubliceerd. De publicatieomgeving ziet er als volgt uit +Verschillende onderdelen van standaarden worden op verschillende plaatsen +gepubliceerd. De publicatieomgeving ziet er als volgt uit ![Architectuurplaatje](media/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) +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) +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 (begrippen.geostandaarden.nl) @@ -64,11 +87,16 @@ Technische onderdelen van de standaard worden op: [register.geostandaarden.nl](h ## Uitleg MkDocs -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). +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: +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 36a01b4..0aad406 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,9 +19,8 @@ nav: - Toolbox genereren extensie: MIM-toolbox-genereren-extensie.md - ReSpec: - Manual: ReSpec.md - - Checklists: ReSpec-Checklists.md - Code toepassen: ReSpec-code-toepassen.md - - 'Definitielijst maken': ReSpec-definitielijst-maken.md + - Definitielijst maken: ReSpec-definitielijst-maken.md - EA: - Overzicht: EA.md - standaarddatatypen: EA-toepassing-standaarddatatypen.md