-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsnapshot.html
1689 lines (1610 loc) · 324 KB
/
snapshot.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html><html lang="nl"><head>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta content="text/html; charset=utf-8" http-equiv="content-type">
<meta name="generator" content="ReSpec 35.1.1">
<style>
.issue-label{text-transform:initial}
.warning>p:first-child{margin-top:0}
.warning{padding:.5em;border-left-width:.5em;border-left-style:solid}
span.warning{padding:.1em .5em .15em}
.issue.closed span.issue-number{text-decoration:line-through}
.issue.closed span.issue-number::after{content:" (Closed)";font-size:smaller}
.warning{border-color:#f11;border-color:var(--warning-border,#f11);border-width:.2em;border-style:solid;background:#fbe9e9;background:var(--warning-bg,#fbe9e9);color:#000;color:var(--text,#000)}
.warning-title:before{content:"⚠";font-size:1.3em;float:left;padding-right:.3em;margin-top:-.3em}
li.task-list-item{list-style:none}
input.task-list-item-checkbox{margin:0 .35em .25em -1.6em;vertical-align:middle}
.issue a.respec-gh-label{padding:5px;margin:0 2px 0 2px;font-size:10px;text-transform:none;text-decoration:none;font-weight:700;border-radius:4px;position:relative;bottom:2px;border:none;display:inline-block}
</style>
<style>
dfn{cursor:pointer}
.dfn-panel{position:absolute;z-index:35;min-width:300px;max-width:500px;padding:.5em .75em;margin-top:.6em;font-family:"Helvetica Neue",sans-serif;font-size:small;background:#fff;background:var(--indextable-hover-bg,#fff);color:#000;color:var(--text,#000);box-shadow:0 1em 3em -.4em rgba(0,0,0,.3),0 0 1px 1px rgba(0,0,0,.05);box-shadow:0 1em 3em -.4em var(--tocsidebar-shadow,rgba(0,0,0,.3)),0 0 1px 1px var(--tocsidebar-shadow,rgba(0,0,0,.05));border-radius:2px}
.dfn-panel:not(.docked)>.caret{position:absolute;top:-9px}
.dfn-panel:not(.docked)>.caret::after,.dfn-panel:not(.docked)>.caret::before{content:"";position:absolute;border:10px solid transparent;border-top:0;border-bottom:10px solid #fff;border-bottom-color:var(--indextable-hover-bg,#fff);top:0}
.dfn-panel:not(.docked)>.caret::before{border-bottom:9px solid #a2a9b1;border-bottom-color:var(--indextable-hover-bg,#a2a9b1)}
.dfn-panel *{margin:0}
.dfn-panel b{display:block;color:#000;color:var(--text,#000);margin-top:.25em}
.dfn-panel ul a[href]{color:#333;color:var(--text,#333)}
.dfn-panel>div{display:flex}
.dfn-panel a.self-link{font-weight:700;margin-right:auto}
.dfn-panel .marker{padding:.1em;margin-left:.5em;border-radius:.2em;text-align:center;white-space:nowrap;font-size:90%;color:#040b1c}
.dfn-panel .marker.dfn-exported{background:#d1edfd;box-shadow:0 0 0 .125em #1ca5f940}
.dfn-panel .marker.idl-block{background:#8ccbf2;box-shadow:0 0 0 .125em #0670b161}
.dfn-panel a:not(:hover){text-decoration:none!important;border-bottom:none!important}
.dfn-panel a[href]:hover{border-bottom-width:1px}
.dfn-panel ul{padding:0}
.dfn-panel li{margin-left:1em}
.dfn-panel.docked{position:fixed;left:.5em;top:unset;bottom:2em;margin:0 auto;max-width:calc(100vw - .75em * 2 - .5em - .2em * 2);max-height:30vh;overflow:auto}
</style>
<script>document.title = respecConfig.title</script>
<title>Respec documentatie generatie</title>
<title>Default</title>
<link rel="shortcut icon" type="image/x-icon" href="https://vng-realisatie.github.io/VNG-R-Respec-Organization-configurations/media/logo-VNG-Realisatie.ico">
<style>
.figure img, .sidefigure img, figure img,
.figure object, .sidefigure object, figure object {
max-width: none !important;
}
h7 {
font-style: italic;
}
h7::after{
content: "\a";
white-space: pre;
}
h7::before{
content: "\a";
white-space: pre;
}
</style>
<style id="respec-mainstyle">
@keyframes pop{
0%{transform:scale(1,1)}
25%{transform:scale(1.25,1.25);opacity:.75}
100%{transform:scale(1,1)}
}
a.internalDFN{color:inherit;border-bottom:1px solid #99c;text-decoration:none}
a.externalDFN{color:inherit;border-bottom:1px dotted #ccc;text-decoration:none}
a.bibref{text-decoration:none}
.respec-offending-element:target{animation:pop .25s ease-in-out 0s 1}
.respec-offending-element,a[href].respec-offending-element{text-decoration:red wavy underline}
@supports not (text-decoration:red wavy underline){
.respec-offending-element:not(pre){display:inline-block}
.respec-offending-element{background:url(data:image/gif;base64,R0lGODdhBAADAPEAANv///8AAP///wAAACwAAAAABAADAEACBZQjmIAFADs=) bottom repeat-x}
}
#references :target{background:#eaf3ff;animation:pop .4s ease-in-out 0s 1}
cite .bibref{font-style:normal}
a[href].orcid{padding-left:4px;padding-right:4px}
a[href].orcid>svg{margin-bottom:-2px}
ol.tof,ul.tof{list-style:none outside none}
.caption{margin-top:.5em;font-style:italic}
#issue-summary>ul{column-count:2}
#issue-summary li{list-style:none;display:inline-block}
details.respec-tests-details{margin-left:1em;display:inline-block;vertical-align:top}
details.respec-tests-details>*{padding-right:2em}
details.respec-tests-details[open]{z-index:999999;position:absolute;border:thin solid #cad3e2;border-radius:.3em;background-color:#fff;padding-bottom:.5em}
details.respec-tests-details[open]>summary{border-bottom:thin solid #cad3e2;padding-left:1em;margin-bottom:1em;line-height:2em}
details.respec-tests-details>ul{width:100%;margin-top:-.3em}
details.respec-tests-details>li{padding-left:1em}
.self-link:hover{opacity:1;text-decoration:none;background-color:transparent}
aside.example .marker>a.self-link{color:inherit}
.header-wrapper{display:flex;align-items:baseline;position:relative;left:-.5em}
:is(h2,h3,h4,h5,h6):not(#toch2)+a.self-link{color:inherit;order:-1;position:relative;left:-.7em;font-size:1rem;opacity:.5}
:is(h2,h3,h4,h5,h6)+a.self-link::before{content:"§";text-decoration:none;color:var(--heading-text)}
:is(h2,h3)+a.self-link{top:-.2em}
:is(h4,h5,h6)+a.self-link::before{color:#000}
@media (max-width:767px){
dd{margin-left:0}
}
@media print{
.removeOnSave{display:none}
}
</style>
<style id="respec-nlgov">
img.license{float:left;padding-right:5px}
</style>
<style>
ul.index{columns:30ch;column-gap:1.5em}
ul.index li{list-style:inherit}
ul.index li span{color:inherit;cursor:pointer;white-space:normal}
#index-defined-here ul.index li{font-size:.9rem}
ul.index code{color:inherit}
#index-defined-here .print-only{display:none}
@media print{
#index-defined-here .print-only{display:initial}
}
</style>
<meta name="description" content="Dit document bevat een uitleg van de toepassing van Respec documentatie binnen VNG Realisatie.">
<style>
.hljs{--base:#fafafa;--mono-1:#383a42;--mono-2:#686b77;--mono-3:#717277;--hue-1:#0b76c5;--hue-2:#336ae3;--hue-3:#a626a4;--hue-4:#42803c;--hue-5:#ca4706;--hue-5-2:#c91243;--hue-6:#986801;--hue-6-2:#9a6a01}
@media (prefers-color-scheme:dark){
.hljs{--base:#282c34;--mono-1:#abb2bf;--mono-2:#818896;--mono-3:#5c6370;--hue-1:#56b6c2;--hue-2:#61aeee;--hue-3:#c678dd;--hue-4:#98c379;--hue-5:#e06c75;--hue-5-2:#be5046;--hue-6:#d19a66;--hue-6-2:#e6c07b}
}
.hljs{display:block;overflow-x:auto;padding:.5em;color:#383a42;color:var(--mono-1,#383a42);background:#fafafa;background:var(--base,#fafafa)}
.hljs-comment,.hljs-quote{color:#717277;color:var(--mono-3,#717277);font-style:italic}
.hljs-doctag,.hljs-formula,.hljs-keyword{color:#a626a4;color:var(--hue-3,#a626a4)}
.hljs-deletion,.hljs-name,.hljs-section,.hljs-selector-tag,.hljs-subst{color:#ca4706;color:var(--hue-5,#ca4706);font-weight:700}
.hljs-literal{color:#0b76c5;color:var(--hue-1,#0b76c5)}
.hljs-addition,.hljs-attribute,.hljs-meta-string,.hljs-regexp,.hljs-string{color:#42803c;color:var(--hue-4,#42803c)}
.hljs-built_in,.hljs-class .hljs-title{color:#9a6a01;color:var(--hue-6-2,#9a6a01)}
.hljs-attr,.hljs-number,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-pseudo,.hljs-template-variable,.hljs-type,.hljs-variable{color:#986801;color:var(--hue-6,#986801)}
.hljs-bullet,.hljs-link,.hljs-meta,.hljs-selector-id,.hljs-symbol,.hljs-title{color:#336ae3;color:var(--hue-2,#336ae3)}
.hljs-emphasis{font-style:italic}
.hljs-strong{font-weight:700}
.hljs-link{text-decoration:underline}
</style>
<style>
.sidelabel {
position: fixed;
-webkit-transform-origin: top right;
right: 100%;
top: 0;
-webkit-transform: rotate(-90deg);
padding: 4px 50px 4px 10px;
color: white;
white-space: nowrap;
z-index: 1;
background-color: #DC7633;
}
</style>
<script type="text/javascript">
/* Any custom mermaid.js scripts will go here. */
</script>
<style>
/* Any custom mermaid.js scripts will go here. */
}
</style>
<script id="initialUserConfig" type="application/json">{
"nl_organisationName": "VNG Realisatie",
"nl_organisationStylesURL": "https://gitdocumentatie.logius.nl/publicatie/respec/style/",
"nl_organisationPublishURL": "https://vng-realisatie.github.io/publicatie",
"logos": [
{
"src": "https://vng-realisatie.github.io/VNG-R-Respec-Organization-configurations/media/logo-VNG-Realisatie.jpg",
"alt": "VNG-Realisatie",
"id": "VNG-Realisatie",
"height": 77,
"url": "https://www.vng.nl"
}
],
"postProcess": [
null
],
"pubDomain": "hl",
"latestVersion": [
"nl_organisationPublishURL",
"pubDomain",
"/",
"shortName"
],
"thisVersion": [
"nl_organisationPublishURL",
"pubDomain",
"/",
"shortName",
"/",
"publishVersion"
],
"prevVersion": [
"nl_organisationPublishURL",
"pubDomain",
"/",
"shortName",
"/",
"previousPublishVersion"
],
"useLogo": true,
"useLabel": true,
"license": "eupl",
"addSectionLinks": true,
"localizationStrings": {
"nl": {
"cv": "Consultatieversie",
"vv": "Versie ter vaststelling",
"ig": "In Gebruik versie",
"io": "In Ontwikkeling versie",
"im": "Informatiemodel",
"hl": "Handleiding",
"st": "Standaard"
}
},
"sotdText": {
"nl": {
"sotd": "Status van dit document",
"cv": "Dit is een door het TO goedgekeurde consultatieversie. Commentaar over dit document kan gestuurd worden naar ",
"vv": "Dit is een definitief concept van de nieuwe versie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.",
"ig": "Dit document is 'In Gebruik'.",
"io": "Dit document is nog 'In Ontwikkeling'."
}
},
"labelColor": {
"ig": "#A569BD",
"io": "#DC7633"
},
"licenses": {
"cc0": {
"name": "Creative Commons 0 Public Domain Dedication",
"short": "CC0",
"url": "https://creativecommons.org/publicdomain/zero/1.0/",
"image": "https://gitdocumentatie.logius.nl/publicatie/respec/media/logos/cc-zero.svg"
},
"cc-by": {
"name": "Creative Commons Attribution 4.0 International Public License",
"short": "CC-BY",
"url": "https://creativecommons.org/licenses/by/4.0/legalcode",
"image": "https://gitdocumentatie.logius.nl/publicatie/respec/media/logos/cc-by.svg"
},
"cc-by-nd": {
"name": "Creative Commons Naamsvermelding-GeenAfgeleideWerken 4.0 Internationaal",
"short": "CC-BY-ND",
"url": "https://creativecommons.org/licenses/by-nd/4.0/legalcode.nl",
"image": "https://gitdocumentatie.logius.nl/publicatie/respec/media/logos/cc-by-nd.svg"
},
"eupl": {
"name": "EUROPEAN UNION PUBLIC LICENCE v. 1.2",
"short": "EUPL",
"url": "https://eupl.eu/",
"image": "https://eupl.eu/eu.png"
}
},
"localBiblio": {
"MIM": {
"href": "https://docs.geostandaarden.nl/mim/mim/",
"publisher": "Geonovum",
"title": "MIM - Metamodel Informatie Modellering",
"date": "Oktober 2023",
"rawDate": "2023",
"id": "mim"
},
"SemVer": {
"href": "https://semver.org/lang/nl/",
"title": "Semantisch Versioneren 2.0.0",
"date": "December 19, 2023",
"rawDate": "2023",
"id": "semver"
}
},
"shortName": "Respec-template",
"specType": "HL",
"specStatus": "IO",
"publishDate": "2024-05-16",
"publishVersion": "0.2.0",
"title": "Respec documentatie generatie",
"subtitle": "Tevens een voorbeeld van een gegenereerd Respec document",
"content": {
"mermaid": "",
"ch01": "informative",
"ch02": ""
},
"editors": [
{
"name": "Robert Melskens",
"company": "VNG Realisatie",
"companyURL": "https://vng.nl/artikelen/vng-realisatie"
}
],
"github": "https://github.com/VNG-Realisatie/VNG-R-Respec-Template",
"alternateFormats": [
{
"label": "pdf",
"uri": "hl-Respec-template-0.2.0.pdf"
}
]
}</script>
<link rel="stylesheet" href="https://gitdocumentatie.logius.nl/publicatie/respec/style/base.css"></head>
<body class="h-entry toc-inline"><div class="head">
<a class="logo" href="https://www.vng.nl"><img alt="VNG-Realisatie" height="77" id="VNG-Realisatie" src="https://vng-realisatie.github.io/VNG-R-Respec-Organization-configurations/media/logo-VNG-Realisatie.jpg">
</a> <h1 id="title" class="title">Respec documentatie generatie</h1>
<h2 id="subtitle" class="subtitle">Tevens een voorbeeld van een gegenereerd Respec document</h2>
<h2>
VNG Realisatie Handleiding<br>
In Ontwikkeling versie
<time class="dt-published" datetime="2024-05-16">16 mei 2024</time>
</h2>
<dl>
<dt>Deze versie:</dt><dd class="status">
<a class="u-url status" href="https://vng-realisatie.github.io/publicatie/hl/respec-template/0.2.0">https://vng-realisatie.github.io/publicatie/hl/respec-template/0.2.0</a>
</dd>
<dt>Laatst gepubliceerde versie:</dt><dd>
<a href="https://vng-realisatie.github.io/publicatie/hl/respec-template">https://vng-realisatie.github.io/publicatie/hl/respec-template</a>
</dd>
<dt>Laatste werkversie:</dt><dd><a href="https://vng-realisatie.github.io/VNG-R-Respec-Template/">https://vng-realisatie.github.io/VNG-R-Respec-Template/</a></dd>
<dt>Redacteur:</dt>
<dd class="editor p-author h-card vcard">
<span class="p-name fn">Robert Melskens</span> (<a class="p-org org h-org" href="https://vng.nl/artikelen/vng-realisatie">VNG Realisatie</a>)
</dd>
<dt>Doe mee:</dt><dd>
<a href="https://github.com/VNG-Realisatie/VNG-R-Respec-Template/">GitHub VNG-Realisatie/VNG-R-Respec-Template</a>
</dd><dd>
<a href="https://github.com/VNG-Realisatie/VNG-R-Respec-Template/issues/">Dien een melding in</a>
</dd><dd>
<a href="https://github.com/VNG-Realisatie/VNG-R-Respec-Template/commits/">Revisiehistorie</a>
</dd><dd>
<a href="https://github.com/VNG-Realisatie/VNG-R-Respec-Template/pulls/">Pull requests</a>
</dd>
</dl>
<p>
Dit document is ook beschikbaar in dit niet-normatieve formaat:
<a rel="alternate" href="hl-Respec-template-0.2.0.pdf">pdf</a>
</p>
<p class="copyright">
Dit document valt onder de volgende licentie:
<a rel="license" href="https://eupl.eu/" class="subfoot"><img class="license" src="https://eupl.eu/eu.png" alt="Logo EUROPEAN UNION PUBLIC LICENCE v. 1.2"><br> EUROPEAN UNION PUBLIC LICENCE v. 1.2</a>
</p>
<hr title="Separator for header">
</div>
<section id="abstract" class="introductory"><h2>Samenvatting</h2><p>Dit document bevat een uitleg van de toepassing van Respec documentatie binnen VNG Realisatie. </p>
<ul>
<li>In hoofdstuk 1 wordt de werking van het template uitgelegd. Hoe je het kunt gebruiken voor je eigen specificatie, wat er precies gebeurd als je er mee aan de gang gaat en waar je daarbij op moet letten.</li>
<li>Hoofdstuk 2 beschrijft hoe je binnen Imvertor (indien toegepast) een deel van de content van je specificatie kan genereren. Dit hoofdstuk is optioneel aangezien je Respec document niet per definitie betrekking hoeft te hebben op een Informatiemodel.</li>
<li>Hoofdstuk 3 beschrijft waar je op moet letten als je het GitHub Respec template kopieert (zowel als admin als als gebruiker), hoe je de Respec documentatie, evt. naast de door Imvertor gegenereerde content, nog kan voorzien van andere content en hoe je door het aanpassen van configuration properties de stijl van het document kan veranderen daarbij rekening houdend met wat wij binnen VNG Realisatie met elkaar hebben afgesproken. In de flowchart van hoofdstuk 5 wordt dit hoofdstuk met de 'Generatie tak' geïllustreerd.</li>
<li>Hoe de gegenereerde Respec bestanden gepubliceerd kunnen worden wordt in Hoofdstuk 4 beschreven. In de flowchart van hoofdstuk 5 wordt dit hoofdstuk met de 'Publicatie tak' geïllustreerd.</li>
<li>In hoofdstuk 5 is een flowchart van het gehele proces voor het vervaardigen van Respec documentatie uitgewerkt. Dit is echter tevens een voorbeeld van het gebruik van Mermaid, een manier om flowcharts te vervaardigen.</li>
<li>De hoofdstukken volgend op hoofdstuk 5 hebben slechts een illustratieve functie. Op basis daarvan moet je, samen met de uitleg in hoofdstuk 3, in staat zijn de getoonde functionaliteit te gebruiken.</li>
</ul>
</section>
<section id="sotd" class="introductory"><h2>Status van dit document</h2><p>Dit document is nog 'In Ontwikkeling'.</p></section><nav id="toc"><h2 class="introductory" id="inhoudsopgave">Inhoudsopgave</h2><ol class="toc"><li class="tocline"><a class="tocxref" href="#abstract">Samenvatting</a></li><li class="tocline"><a class="tocxref" href="#sotd">Status van dit document</a></li><li class="tocline"><a class="tocxref" href="#rm"><bdi class="secno">1. </bdi>ReSpec template instructies</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#vereiste-voor-gebruik"><bdi class="secno">1.1 </bdi>Vereiste voor gebruik</a></li><li class="tocline"><a class="tocxref" href="#gebruikersinstructie"><bdi class="secno">1.2 </bdi>Gebruikersinstructie</a></li><li class="tocline"><a class="tocxref" href="#rendering-automatische-controles-en-publicatie"><bdi class="secno">1.3 </bdi>Rendering, automatische controles en publicatie</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#rendering"><bdi class="secno">1.3.1 </bdi>Rendering</a></li><li class="tocline"><a class="tocxref" href="#checken"><bdi class="secno">1.3.2 </bdi>Checken</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#gen"><bdi class="secno">2. </bdi>Respec m.b.v. Imvertor</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#documentatie-generatie"><bdi class="secno">2.1 </bdi>Documentatie generatie</a></li><li class="tocline"><a class="tocxref" href="#diagrammen-als-clickable-images"><bdi class="secno">2.2 </bdi>Diagrammen als clickable images</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#clickable-images-en-pdf"><bdi class="secno">2.2.1 </bdi>Clickable images en pdf</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#assembl"><bdi class="secno">3. </bdi>Samenstellen Respec documentatie in GitHub (under construction)</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#door-administrator-uit-te-voeren-acties"><bdi class="secno">3.1 </bdi>Door administrator uit te voeren acties</a></li><li class="tocline"><a class="tocxref" href="#door-repository-eigenaar-uit-te-voeren-acties"><bdi class="secno">3.2 </bdi>Door repository eigenaar uit te voeren acties</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#imvertor-resultaat-plaatsen"><bdi class="secno">3.2.1 </bdi>Imvertor resultaat plaatsen</a></li><li class="tocline"><a class="tocxref" href="#de-content-van-het-respec-document-aanpassen"><bdi class="secno">3.2.2 </bdi>De content van het Respec document aanpassen</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#content-methode"><bdi class="secno">3.2.2.1 </bdi>Content methode</a></li><li class="tocline"><a class="tocxref" href="#sectie-methode"><bdi class="secno">3.2.2.2 </bdi>Sectie methode</a></li><li class="tocline"><a class="tocxref" href="#secties-met-id-attribuutwaarde-sotd"><bdi class="secno">3.2.2.3 </bdi>Secties met 'id' attribuutwaarde 'sotd'</a></li><li class="tocline"><a class="tocxref" href="#secties-met-id-attribuutwaarde-abstract"><bdi class="secno">3.2.2.4 </bdi>Secties met 'id' attribuutwaarde 'abstract'</a></li><li class="tocline"><a class="tocxref" href="#secties-met-id-attribuutwaarde-conformance"><bdi class="secno">3.2.2.5 </bdi>Secties met 'id' attribuutwaarde 'conformance'</a></li><li class="tocline"><a class="tocxref" href="#secties-met-id-attribuutwaarde-tof"><bdi class="secno">3.2.2.6 </bdi>Secties met 'id' attribuutwaarde 'tof'</a></li><li class="tocline"><a class="tocxref" href="#secties-met-id-attribuutwaarde-index"><bdi class="secno">3.2.2.7 </bdi>Secties met 'id' attribuutwaarde 'index'</a></li><li class="tocline"><a class="tocxref" href="#secties-met-een-andere-id-attribuutwaarde"><bdi class="secno">3.2.2.8 </bdi>Secties met een andere 'id' attribuutwaarde</a></li><li class="tocline"><a class="tocxref" href="#secties-met-data-include-format-html"><bdi class="secno">3.2.2.9 </bdi>Secties met <code>data-include-format="html"</code></a></li><li class="tocline"><a class="tocxref" href="#andersoortige-secties"><bdi class="secno">3.2.2.10 </bdi>Andersoortige secties</a></li></ol></li><li class="tocline"><a class="tocxref" href="#bijlage-n-referenties"><bdi class="secno">3.2.3 </bdi>Bijlage N Referenties</a></li><li class="tocline"><a class="tocxref" href="#images-in-de-documentatie"><bdi class="secno">3.2.4 </bdi>Images in de documentatie</a></li></ol></li><li class="tocline"><a class="tocxref" href="#lokale-respec-configuratie-properties"><bdi class="secno">3.3 </bdi>Lokale Respec configuratie properties</a></li><li class="tocline"><a class="tocxref" href="#functie-respec-configuratie-properties"><bdi class="secno">3.4 </bdi>Functie Respec configuratie properties</a></li></ol></li><li class="tocline"><a class="tocxref" href="#publ"><bdi class="secno">4. </bdi>Publiceren Respec documentatie (under construction)</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#inrichten-publicatie-repository"><bdi class="secno">4.1 </bdi>Inrichten publicatie repository</a></li><li class="tocline"><a class="tocxref" href="#publiceren-van-documenten"><bdi class="secno">4.2 </bdi>Publiceren van documenten</a></li></ol></li><li class="tocline"><a class="tocxref" href="#probl"><bdi class="secno">5. </bdi>Foutoplossing</a></li><li class="tocline"><a class="tocxref" href="#het-vng-r-respec-proces"><bdi class="secno">6. </bdi>Het VNG-R Respec proces</a></li><li class="tocline"><a class="tocxref" href="#niet-normatieve-deel"><bdi class="secno">7. </bdi>Niet-normatieve deel</a></li><li class="tocline"><a class="tocxref" href="#meer-inhoud"><bdi class="secno">8. </bdi>Meer inhoud</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#definities"><bdi class="secno">8.1 </bdi>Definities</a></li><li class="tocline"><a class="tocxref" href="#afbeeldingen"><bdi class="secno">8.2 </bdi>Afbeeldingen</a></li><li class="tocline"><a class="tocxref" href="#referenties"><bdi class="secno">8.3 </bdi>Referenties</a></li><li class="tocline"><a class="tocxref" href="#optioneel"><bdi class="secno">8.4 </bdi>Optioneel</a></li></ol></li><li class="tocline"><a class="tocxref" href="#conformance"><bdi class="secno">9. </bdi>Conformiteit</a></li><li class="tocline"><a class="tocxref" href="#tof"><bdi class="secno">10. </bdi>Lijst met figuren</a></li><li class="tocline"><a class="tocxref" href="#index"><bdi class="secno">A. </bdi>Index</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#index-defined-here"><bdi class="secno">A.1 </bdi>Begrippen gedefinieerd door deze specificatie</a></li><li class="tocline"><a class="tocxref" href="#index-defined-elsewhere"><bdi class="secno">A.2 </bdi>Begrippen gedefinieerd door verwijzing</a></li></ol></li><li class="tocline"><a class="tocxref" href="#references"><bdi class="secno">B. </bdi>Referenties</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#normatieve-referenties"><bdi class="secno">B.1 </bdi>Normatieve referenties</a></li></ol></li></ol></nav>
<section id="rm"><div class="header-wrapper"><h2 id="x1-respec-template-instructies"><bdi class="secno">1. </bdi>ReSpec template instructies</h2><a class="self-link" href="#rm" aria-label="Permalink for Section 1."></a></div>
<p>ReSpec is een tool om html en pdf documenten te genereren op basis van markdown en html content.</p>
<p>Organisatie administrators dienen de knop <a href="https://github.com/vng-realisatie/VNG-R-Respec-Template/generate"><em>Use this template</em></a> te gebruiken om een kopie van de template repository aan te maken. Deze kan daarna door jouzelf aangepast en uitgebreid worden.
Dit template is afgeleid van het <a href="https://github.com/Logius-standaarden/respec-template">Logius Respec template</a> maar is op enkele details aangepast:</p>
<ul>
<li>Het organisation configuration bestand is in een <a href="https://github.com/VNG-Realisatie/VNG-R-Respec-Organization-configurations">aparte repository</a> ondergebracht;</li>
<li>Het lokale configuratie bestand is aangepast aan de behoeftes van VNG Realisatie;</li>
<li>In de 'index.html' is een style element aangebracht waarmee de standaard instelling van de 'max-width' property op 'none' is gesteld;</li>
<li>De uitleg van de toepassing van het VNG-R Respec profiel is als inhoud aan deze repository toegevoegd.</li>
</ul>
<p>De dynamische pagina van het template document is <a href="https://vng-realisatie.github.io/VNG-R-Respec-Template/">hier</a> te zien.</p>
<p>Deze repository bevat ook de GitHub Workflows om een statische HTML-pagina en PDF-document te genereren en enkele controles uit te voeren. Deze workflows worden
automatisch gerund zodra er een aanpassing gedaan wordt aan de main branch. Een beschrijving van deze acties vind je onderaan dit hoofdstuk.</p>
<section id="vereiste-voor-gebruik"><div class="header-wrapper"><h3 id="x1-1-vereiste-voor-gebruik"><bdi class="secno">1.1 </bdi>Vereiste voor gebruik</h3><a class="self-link" href="#vereiste-voor-gebruik" aria-label="Permalink for Section 1.1"></a></div>
<ul>
<li>Kennis van git/GitHub</li>
<li>Kennis van Markdown en/of HTML</li>
<li>Een webserver om de documentatie te hosten</li>
</ul>
<p>Voor de laatste gebruiken wij GitHub. Kennis van de vorm van een Javascript object is handig om de in dit template voorkomende scripts aan te kunnen passen maar zonder die kennis kom je m.b.v. deze documentatie ook al heel ver.</p>
</section><section id="gebruikersinstructie"><div class="header-wrapper"><h3 id="x1-2-gebruikersinstructie"><bdi class="secno">1.2 </bdi>Gebruikersinstructie</h3><a class="self-link" href="#gebruikersinstructie" aria-label="Permalink for Section 1.2"></a></div>
<p>Om het gebruik van dit template makkelijker te maken raden we het aan om een IDE te gebruiken. Die geeft een voorbeeld van hoe de markdown eruit zal zien, kan laten zien of de config files nog in de correcte vorm zijn en kan helpen in het gebruik van git.<br>Een gratis voorbeeld van een IDE is: <a href="https://code.visualstudio.com/">Visual studio code</a>. Een combinatie van GitHub desktop en je eigen favoriete Markdown editor is echter ook mogelijk.</p>
<p>Aanpassingen maken aan het document gaat op 2 manieren:</p>
<ul>
<li>De configuratie van het document aanpassing in de config files</li>
<li>Markdown of html files toevoegen/veranderen</li>
</ul>
<p>De <strong>configuratie files</strong> bevatten informatie over de organisatie en over
de status van het document. Helemaal onderaan hoofdstuk 3 vind je meer informatie over de configuratie opties, daarnaast kun je ook de <a href="https://github.com/Logius-standaarden/respec/wiki">Logius ReSpec wiki</a>
bezoeken. De files zijn gesplitst in 2 files die weer in 2 verschillende repositories zijn ondergebracht:
<a href="https://github.com/vng-realisatie/Respec-Organization-configurations/blob/main/js/organisation-config.js">organisation-config.js</a> en <a href="js/config.js">config.js</a>.</p>
<p>De organisation_config (organisation-config.js) bevat configuratie properties die betrekking hebben op alle VNG-R Respec documentatie, de properties in deze file
zullen zelden veranderen zoals bijv. de naam van de organisatie. </p>
<p>De document_config (config.js) bevat configuratie properties die alleen relevant is voor het betreffende Respec document en hoort dan ook in elke Respec renderende repository thuis.</p>
<p>Beide configuratie bestanden worden gelinkt in de <code>index.html</code> file waardoor ze beide bij het renderen van de Respec documentatie automatisch worden samengevoegd. Daardoor zijn de organisatie specifieke configuraties over alle Respec documentatie van VNG-R gelijk en
hoeft deze niet steeds gekopieerd te worden. Op deze wijze zorgen we er voor dat alle VNG-R Respec documenten zo eenduidig mogelijk zijn en blijven. </p>
<p>Sommige configuratie properties hebben een taalspecifieke instelling. Denk bijv. aan de documenttypes. Deze kunnen voor diverse talen gespecificeerd worden. Teneinde het Respec framework in staat te stellen de gewenste taal te kiezen moet het <code><html></code> element van het attribute <code>lang</code> worden voorzien met de gewenste waarde, bijv. <code>nl</code> of <code>en</code>. Ontbreekt deze dan zal de voor Respec typische Header niet gegenereerd worden.</p>
<p>In <a href="https://vng-realisatie.github.io/VNG-R-Respec-Template/#wow">het volgende hoofdstuk</a> staat beschreven hoe je de inhoud van het Respec document naar wens kunt aanpassen.</p>
</section><section id="rendering-automatische-controles-en-publicatie"><div class="header-wrapper"><h3 id="x1-3-rendering-automatische-controles-en-publicatie"><bdi class="secno">1.3 </bdi>Rendering, automatische controles en publicatie</h3><a class="self-link" href="#rendering-automatische-controles-en-publicatie" aria-label="Permalink for Section 1.3"></a></div>
<p>Het bestand '.github/workflows/build.yml' bevat een action script waarmee automatisch een drietal acties worden uitgevoerd nadat een bestand in de repository wordt gewijzigd, toegevoegd of verwijderd:</p>
<ul>
<li>het renderen van het Respec document;</li>
<li>het checken of de gerenderde Respec html wel correct is en voldoet aan de toegankelijkheidseisen;</li>
<li>het publiceren van de gegenereerde statische html en pdf naar een centrale Respec publicatie repository.</li>
</ul>
<p>We beschrijven de eerste 2 acties in het kort hieronder. Aangezien we de laatste actie nog niet werkende hebben wordt deze voorlopig nog handmatig uitgevoerd, dat beschrijven we in hoofdstuk 4.
De log van deze acties is te vinden in het tabblad <code>Actions</code> in de GitHub repository.</p>
<section id="rendering"><div class="header-wrapper"><h4 id="x1-3-1-rendering"><bdi class="secno">1.3.1 </bdi>Rendering</h4><a class="self-link" href="#rendering" aria-label="Permalink for Section 1.3.1"></a></div>
<p>Deze actie start het renderen van de Respec html. Vervolgens wordt er op basis daarvan een statische html en een pdf bestand gegenereerd. Die gebruiken we uiteindelijk om te publiceren.</p>
<p>De PDF-versie wordt aangemaakt omdat de property <code>alternateFormats</code> in de organisation_config als volgt geconfigureerd staat:</p>
<pre><code class="js hljs" aria-busy="false"><span class="hljs-attr">alternateFormats</span>: [
{
<span class="hljs-attr">label</span>: <span class="hljs-string">"pdf"</span>,
<span class="hljs-attr">uri</span>: <span class="hljs-string">"snapshot.pdf"</span>,
},
]
</code></pre>
<p>Er moet nog worden bepaald of we de document eigenaar zelf willen laten bepalen of hij/zij een pdf wil genereren. Indien we dat willen verhuisd deze property naar de document_config. De waarde van de property <code>uri</code> kan dan naar wens worden aangepast.</p>
</section><section id="checken"><div class="header-wrapper"><h4 id="x1-3-2-checken"><bdi class="secno">1.3.2 </bdi>Checken</h4><a class="self-link" href="#checken" aria-label="Permalink for Section 1.3.2"></a></div>
<p>Na het renderen van de Respec html en pdf worden er via github actions 2 controles uitgevoerd op de html: </p>
<ul>
<li><p>een WCAG-check (Web Content Accessibility Guidelines), deze guidelines gemaakt door W3C zorgen voor een verbetering van de toegankelijkheid van webapplicaties verbeterd voor zowel verschillende apparaten als voor mensen met een beperking. Ook wordt de validiteit van het HTML bestand gecheckt, bijv.:</p>
<ul>
<li>of er geen <code><section></code> elementen met 'id' attributen voorkomen die al voorkomen in het bestand;</li>
<li>of er geen <code><a></code> elementen voorkomen met 'href' attributen die verwijzen naar <code><section></code> elementen die helemaal niet bestaan.</li>
</ul>
<p>Deze check moet eerst succesvol uitgevoerd zijn voordat wordt begonnen aan de volgende check. In de 'Action' die start met het woord 'Update' (zie het <code>Actions</code> tabblad) kun je in de actie 'Check/WCAG' de step 'Run pa11y snapshot.html' vinden. Daar kun je zien welke fouten geconstateerd zijn.</p>
</li>
<li><p>een link-check, deze check controleert of alle links die in het document staan ook bestaan. Het gaat dan bijv. om de links die worden vermeldt in:</p>
<ul>
<li>'Deze versie'</li>
<li>'Laatst gepubliceerde versie'</li>
<li>'Laatste werkversie'</li>
<li>'Vorige versie'</li>
</ul>
<p>Deze links verwijzen naar specifieke locaties in de GitHub Pages interface van de 'publicatie' GitHub repository (zie de volgende subparagraaf voor meer uitleg). Om deze check goed te kunnen doorstaan moeten deze locaties dus al bestaan in die interface. Indien dat nog niet gedaan is moet daar de folder voor het nieuwe versienummer van de Respec documentatie al worden aangemaakt. Plaats in die folder dan ook een tijdelijk 'index.html' bestand. De inhoud van dat bestand is (nog) niet van belang.</p>
</li>
</ul>
<blockquote>
<p><strong>LET OP!</strong><br>
Onderstaand tekst is slechts een voorstel.
De definitieve url kan indien gewenst nog andere onderdelen bevatten zoals bijv. <code>publishDate</code>, <code>previousPublishDate</code>, <code>specStatus</code> en <code>previousMaturity</code>.</p>
</blockquote>
<p>Bij het genereren van de links zijn op dit moment de volgende configuration properties van belang:</p>
<ul>
<li>nl_organisationPublishURL<br>
De basis url van de GitHub Pages interface van de 'publicatie' GitHub repository, op dit moment: <code>https://vng-realisatie.github.io/publicatie</code>. Deze is gedefinieerd in de organisation_config aangezien deze altijd gelijk blijft.</li>
<li>pubDomain<br>
Het publicatie domein. Aangezien we vooralsnog slechts voor Conceptuele Modellen Respec documentatie genereren heeft deze de waarde <code>cim</code> en staat deze gedefinieerd in de organisation_config. Zo nodig kan deze overruled worden in de document_config. Vergeet in dat geval niet om ook de structuur in de 'publicatie' GitHub repository uit te breiden. Wordt gebruikt in 'latestVersion', 'thisVersion' en 'prevVersion'.</li>
<li>specStatus</li>
<li>latestVersion<br>
Wordt opgebouwd a.d.h.v. een aantal andere configuratie properties uit zowel de organisation_config als de document_config en enkele vaste karakters. Deze is gedefinieerd in de organisation_config aangezien deze altijd gelijk blijft.</li>
<li>thisVersion<br>
Wordt opgebouwd a.d.h.v. een aantal andere configuratie properties uit zowel de organisation_config als de document_config en enkele vaste karakters. Deze is gedefinieerd in de organisation_config aangezien deze altijd gelijk blijft.</li>
<li>prevVersion<br>
Wordt opgebouwd a.d.h.v. een aantal andere configuratie properties uit zowel de organisation_config als de document_config en enkele vaste karakters. Deze is gedefinieerd in de organisation_config aangezien deze altijd gelijk blijft.</li>
<li>shortName<br>
De project-mnemonic, een afkorting van het project. Zo wordt het project 'Open Raadsinformatie' wordt bijv. afgekort als 'ori'. Deze is gedefinieerd in de document_config aangezien deze natuurlijk afhankelijk is van het te genereren Respec document. Wordt gebruikt in 'latestVersion', 'thisVersion' en 'prevVersion'.</li>
<li>publishVersion<br>
De versie van het te publiceren Respec document. Komt overeen met de Tagged Value 'Version' in het Enterprise Architect bestand van het model en heeft een waarde dat voldoet aan het formaat <code>x.x.x</code>, bijv. <code>2.0.0</code>. Deze is gedefinieerd in de document_config aangezien deze natuurlijk afhankelijk is van het te genereren Respec document. Wordt gebruikt in de titel van het Respec document maar ook in 'thisVersion'.</li>
<li>previousVersion<br>
De voorgaande versie van het te publiceren Respec document. Komt overeen met de Tagged Value 'Version' in het Enterprise Architect bestand van het voorgaande versie van het model en heeft een waarde dat voldoet aan het formaat <code>x.x.x</code>, bijv. <code>2.0.0</code>. Deze is gedefinieerd in de document_config aangezien deze natuurlijk afhankelijk is van het te genereren Respec document. Wordt gebruikt in 'prevVersion'.</li>
</ul>
<p>Het consistent en nauwgezet invullen van de configuratie properties in de document_config is essentieel voor een goede werking van de links.</p>
<p>De bovenstaande properties hebben invloed op de wijze waarop het eerste deel van de Respec documentatie wordt gegenereerd. Hieronder sommen we de regels op. Indien wordt besloten de properties 'latestVersion', 'thisVersion' en 'prevVersion' een andere inhoud te geven dan zullen onderstaande regels moeten worden herzien.</p>
<ul>
<li>Als de parameter 'specStatus' de waarde 'WV' heeft dan wordt de waarde van de parameter 'thisVersion' niet gebruikt voor het bepalen van 'Deze versie' maar wordt daar dezelfde waarde neergezet als bij 'Laatste werkversie'.</li>
<li>Als de parameter 'specStatus' de waarde 'WV' heeft dan wordt de waarde van 'Subtitel 2' niet gebaseerd op de parameter 'publishDate' maar op de datum waarop de Respec documentatie door GitHub wordt gegenereerd.</li>
<li>Als de parameter 'specStatus' de waarde 'WV' heeft dan wordt het versienummer niet in de titel van het document opgenomen.</li>
<li>Als de parameter 'previousPublishVersion' niet bestaat dan kan 'prevVersion' niet bepaald worden en wordt 'Vorige versie' niet gegenereerd.</li>
<li>Als de parameter 'publishVersion' niet bestaat dan kan 'thisVersion' niet bepaald worden en wordt 'Deze versie' niet gegenereerd.</li>
</ul>
</section></section></section>
<section id="gen"><div class="header-wrapper"><h2 id="x2-respec-m-b-v-imvertor"><bdi class="secno">2. </bdi>Respec m.b.v. Imvertor</h2><a class="self-link" href="#gen" aria-label="Permalink for Section 2."></a></div>
<section id="documentatie-generatie"><div class="header-wrapper"><h3 id="x2-1-documentatie-generatie"><bdi class="secno">2.1 </bdi>Documentatie generatie</h3><a class="self-link" href="#documentatie-generatie" aria-label="Permalink for Section 2.1"></a></div>
<p>Het is mogelijk om met Imvertor Respec documentatie te genereren van een model. Voorwaarde is wel dat het model MIM compliant is. Bij het genereren spelen de volgende Imvertor configuratieproperties (<b>LET OP!</b> Dus niet een van de Respec property bestanden) een rol:</p>
<table>
<thead>
<tr>
<th>Configuratieproperty</th>
<th>Mogelijke waarden</th>
<th>Uitleg</th>
</tr>
</thead>
<tbody><tr>
<td>createoffice</td>
<td>html, doc, none</td>
<td>Hiermee geef je aan of je een documentatie bestand wil genereren en zo ja in welk formaat (html of MsWord). De defaultwaarde is 'none', behalve in het geval van een SIM, daar is de default 'html'. De 'doc' optie is nog niet geïmplementeerd.</td>
</tr>
<tr>
<td>createofficeanchor</td>
<td>name, id</td>
<td>Geeft aan op welke basis hyperlink anchors moeten worden gegenereerd (op basis van id's of op basis van namen). De default is 'name'. Vooralsnog maakt het niet uit welke variant je voor deze property kiest, beide varianten leiden tot hetzelfde resultaat.</td>
</tr>
<tr>
<td>createofficemode</td>
<td>plain, click</td>
<td>Definieert of er in het te genereren bestand hyperlinks moeten worden gegenereert. Bij de waarde 'click' is dat het geval. De defaultwaarde is 'plain'.</td>
</tr>
<tr>
<td>createofficevariant</td>
<td>respec, msword</td>
<td>Definieert het type te genereren document. Een Respec html document of een MsWord html variant.</td>
</tr>
</tbody></table>
<p>Voor het genereren van Respec documentatie is het essentieel om in je lokale Imvertor property bestand de property 'createofficevariant' de waarde 'respec' te geven. Normaliter zal je dan ook de property 'createofficemode' de waarde 'click' geven.
Dit resulteert er in dat in de folder 'app/cat' 2 Respec bestanden geplaatst, 1 in html en de ander in xhtml.</p>
</section><section id="diagrammen-als-clickable-images"><div class="header-wrapper"><h3 id="x2-2-diagrammen-als-clickable-images"><bdi class="secno">2.2 </bdi>Diagrammen als clickable images</h3><a class="self-link" href="#diagrammen-als-clickable-images" aria-label="Permalink for Section 2.2"></a></div>
<p>Indien op de juiste wijze geconfigureerd en aangeroepen (zie <a href="https://imvertor.armatiek.nl/imvertor-executor/dashboard/wiki?key=info-IMAGEMAPS">hier</a>) zet Imvertor alle in Enterprise Architect gedefinieerde diagrammen om naar PNG images.
Deze images worden echter niet als <code>img</code> elementen opgenomen in de gegenereerde (x)html. Indien dat gewenst is dan zul je ze zelf moeten opnemen. (<strong>TODO</strong> Onderzoeken of dit wel klopt)
Het is echter wel mogelijk om deze diagrammen automatisch als clickable images in de gegenereerde (x)html op te nemen. Om dat te kunnen doen moet wel aan een aantal voorwaarden worden voldaan.</p>
<ol>
<li>Alleen diagrammen die direct geplaatst zijn in de root folder (Stereotype = 'Basismodel') of in de folder waarin (de folder met) de componenten staan worden daarbij meegenomen of binnen de entiteittypes zelf. Ze mogen dus ook niet in een subfolder van deze folders worden geplaatst. De plaatsing in het model bepaald tevens de plaatsing van het diagram in het (x)html bestand. (<strong>TODO</strong> Onderzoeken wat de exacte regels zijn);</li>
<li>De diagrammen moeten class diagrams zijn;</li>
<li>De naam van de diagrammen moet als suffix '<code>- overzicht</code>' of '<code>- detail</code>' hebben;</li>
</ol>
<p>Tenslotte is de onderstaande Imvertor configuratieproperty nog van belang.</p>
<table>
<thead>
<tr>
<th>Configuratieproperty</th>
<th>Mogelijke waarden</th>
<th>Uitleg</th>
</tr>
</thead>
<tbody><tr>
<td>createimagemap</td>
<td>yes, no</td>
<td>Definieert of van de Diagrammen een imagemap moet worden gegenereerd en of de gegenereerde PNG images als <code>img</code> element in de (x)html images worden opgenomen. De default is 'yes'.</td>
</tr>
</tbody></table>
<p>Als deze de waarde 'yes' heeft of niet geconfigureerd is worden er in de (x)html bestanden <code>img</code> elementen met referenties naar de juiste images en imagemap elementen opgenomen.</p>
<p><strong>LET OP!</strong> Maak de in Respec op te nemen diagrammen zoveel als mogelijk in portrait mode op. Dat voorkomt dat je nodeloos diep op het Respec document moet inzoomen.</p>
<section id="clickable-images-en-pdf"><div class="header-wrapper"><h4 id="x2-2-1-clickable-images-en-pdf"><bdi class="secno">2.2.1 </bdi>Clickable images en pdf</h4><a class="self-link" href="#clickable-images-en-pdf" aria-label="Permalink for Section 2.2.1"></a></div>
<p>In het evt. te genereren pdf bestand worden de clickable images natuurlijk niet clickable opgenomen. Het kan echter wel zijn dat de images van de pagina's aflopen. Dit is eenvoudig te voorkomen door in het html bestand waarin de images staan bij de <code>img</code> elementen het volgende attribute op te nemen:</p>
<p><code>style="width: 50em;"</code></p>
<p>Nadeel daarvan is echter dat de imagemaps in het html bestand niet meer overeenkomen met de geplaatste images. De volgende workaround zorgt er voor dat je in de publicatie omgeving beschikt over zowel correcte clickable images als een pdf waarin de images niet van de pagina's aflopen. Helaas zal in de werkomgeving de pdf mogelijk wel images bevatten die van de pagina's aflopen.</p>
<p><strong>Workaround:</strong></p>
<ol>
<li>Creëer een kopie van het door Imvertor gegenereerde html bestand;</li>
<li>Plaats in die kopie bij de <code>img</code> elementen het attribute <code>style="width: 50em;"</code> en bewaar het bestand;</li>
<li>Refereer in het <code>index.html</code> bestand naar de zojuist vervaardigde html kopie i.p.v. naar het origineel daarvan en bewaar het bestand;</li>
<li>Check zonodig beide bestanden in;</li>
<li>Na de build en deployment moeten er in het gegenereerde pdf bestand geen images meer van de pagina's aflopen. Hernoem dat pdf bestand naar <code>[originele naam]-2.pdf</code>;</li>
<li>Refereer in het <code>index.html</code> bestand weer naar het origenele door Imvertor gegenereerde html bestand en bewaar het bestand weer;</li>
<li>Check zonodig beide bestanden in;</li>
<li>Bij de publicatie in de publicatie omgeving (zie <a href="./#publ">verderop in deze handleiding</a>) maak je gebruik van het laatst gegenereerde <code>snapshot.html</code> bestand en het <code>[originele naam]-2.pdf</code> bestand.</li>
</ol>
</section></section></section>
<section id="assembl"><div class="header-wrapper"><h2 id="x3-samenstellen-respec-documentatie-in-github-under-construction"><bdi class="secno">3. </bdi>Samenstellen Respec documentatie in GitHub (under construction)</h2><a class="self-link" href="#assembl" aria-label="Permalink for Section 3."></a></div>
<p>De acties die in het voorgaande hoofdstuk staan beschreven leveren een html bestand voor de Respec documentatie op waarin een informatiemodel wordt beschreven. Respec documentatie hoeft echter niet persé over informatiemodellen te gaan, voor de Respec documentatie die je nu leest is dat immers ook niet het geval. Het resultaat van het voorgaande hoofdstuk kan samen met andere html of markdown bestanden worden gebundeld tot de Respec documentatie. Daarnaast wordt een deel van de content van de Respec documentatie door het Respec framework in GitHub gegenereerd a.d.h.v. een aantal variabelen. Dat framework verzorgt daarnaast ook de vormgeving dat essentieel is voor de Respec documentatie.</p>
<p>Binnen VNG-R maken we gebruik van een door Logius vervaardigde extensie op het W3C Respec framework. We volgen daarbij andere organisaties in Nederland die hetzelfde doen zoals Geonovum. Van het door Logius beschikbaar gestelde template is een VNG-R versie beschikbaar binnen de VNG-Realisatie GitHub organisatie. Dat geeft de mogelijkheid om te verwijzen naar een VNG-R Respec configuratie waardoor we specifiek voor VNG-Realisatie geldende configuraties, zoals bijv. het VNG-Realisatie logo, kunnen aanbrengen. Deze vind je in de repository 'Respec-Organization-configurations'.
Het template zelf kan echter door eenieder worden gebruikt om de eigen Respec documentatie te vervaardigen en daarbinnen bestaan nog mogelijkheden om jouw Respec documentatie een invulling tintje te geven.</p>
<p>Hieronder wordt de werkwijze beschreven waarbij de 8 in de volgende paragraaf beschreven stappen moeten worden uitgevoerd door een GitHub organisatie administrator. Voorzie hem daarvoor van de gewenste respository naam.</p>
<section id="door-administrator-uit-te-voeren-acties"><div class="header-wrapper"><h3 id="x3-1-door-administrator-uit-te-voeren-acties"><bdi class="secno">3.1 </bdi>Door administrator uit te voeren acties</h3><a class="self-link" href="#door-administrator-uit-te-voeren-acties" aria-label="Permalink for Section 3.1"></a></div>
<ol>
<li>Open het <a href="https://github.com/vng-realisatie/VNG-R-Respec-Template">VNG-R Respec template</a> en klik in de README op die pagina op de link 'Use this template';</li>
<li>Je komt nu in het menu om een nieuwe repository aan te maken waarbij al een aantal velden zijn ingevuld. De te maken repository mag niet private zijn want dat maakt het gebruik van GitHub Pages onmogelijk. Geef de van de aanvrager verkregen repository naam in en klik op 'Create repository';</li>
<li>Voer de acties, zoals beschreven in <a href="https://github.com/VNG-Realisatie/api-beheer/blob/master/doc/Standaard-inrichting-GitHub-GitLab.md">de handleiding voor het initieel inrichten van GitHub repositories</a>, uit;</li>
<li>Verwijder in de root van de repository het 'README.md' bestand en hernoem 'Alt-README.md' naar 'README.md'</li>
</ol>
<blockquote>
<p>Dat bestand moet nog gecreëerd worden in het template;</p>
</blockquote>
<ol start="6">
<li>Activeer GitHub Pages voor de nieuwe repository. Selecteer daarvoor het tabblad 'Settings' en kies daar 'Pages';</li>
<li>Kies daar waar bij Branch 'None' staat voor 'main' en klik op 'Save';</li>
<li>Nadat de build en deployment is uitgevoerd ga je naar het 'Code' tabblad, klikt daar op het tandwieltje bij 'About' en klikt op de checkbox naast 'Use your GitHub Pages website'. Klikken op de resulterende link onder 'About' brengt je naar de standaard gegenereerde Respec documentatie die nu kan worden aangepast door de eigenaar van de repository;</li>
</ol>
</section><section id="door-repository-eigenaar-uit-te-voeren-acties"><div class="header-wrapper"><h3 id="x3-2-door-repository-eigenaar-uit-te-voeren-acties"><bdi class="secno">3.2 </bdi>Door repository eigenaar uit te voeren acties</h3><a class="self-link" href="#door-repository-eigenaar-uit-te-voeren-acties" aria-label="Permalink for Section 3.2"></a></div>
<p>Je beschikt nu over een repository die je kunt gaan vullen en waarin je je persoonlijke configuratie properties van een waarde kunt voorzien. Indien je een met Imvertor gegenereerd Respec html bestand wil gebruiken dan volg je de beschrijving van de volgende paragraaf, zo niet dan ga je direct naar de daarop volgende paragraaf.</p>
<section id="imvertor-resultaat-plaatsen"><div class="header-wrapper"><h4 id="x3-2-1-imvertor-resultaat-plaatsen"><bdi class="secno">3.2.1 </bdi>Imvertor resultaat plaatsen</h4><a class="self-link" href="#imvertor-resultaat-plaatsen" aria-label="Permalink for Section 3.2.1"></a></div>
<p>Plaats het met Imvertor gegenereerde bestand in de root van de repository. Van dat bestand gebruiken we alleen de inhoud van het 'section' element met het id 'cat'. Het section element zelf gebruiken we dus niet. Verwijder alle andere content behalve de processing instruction 'DOCTYPE HTML' aan het begin van dit bestand en commit het bestand.
Open vervolgens het bestand 'index.html' en plaats daarin op de gewenste locatie het volgende html fragment:<br><br>
<code><section id="XXXX" data-include-format="html" data-include="XXXX.html"></section></code><br><br>
Waarbij je 'XXXX.html' vervangt door de naam van het zojuist aangepaste bestand en 'XXXX' door een id dat de sectie duidelijk en uniek identificeert.</p>
</section><section id="de-content-van-het-respec-document-aanpassen"><div class="header-wrapper"><h4 id="x3-2-2-de-content-van-het-respec-document-aanpassen"><bdi class="secno">3.2.2 </bdi>De content van het Respec document aanpassen</h4><a class="self-link" href="#de-content-van-het-respec-document-aanpassen" aria-label="Permalink for Section 3.2.2"></a></div>
<p>Een Respec document kan op 2 verschillende manier van content worden voorzien:</p>
<ul>
<li>door de 'sectie' elementen aan het 'index.html' bestand toe te voegen.</li>
<li>m.b.v. de 'content' configuratie property;</li>
</ul>
<p>Beide methodes kunnen naast elkaar worden gebruikt. Advies is echter omn de eerste methode te gebruiken. Deze is transparanter omdat met 1 blik op het index.html bestand te zien is wat er in wordt opgenomen.</p>
<p>Het Respec document zoals dat van het VNG-R Respec template is overgenomen moet nog aangepast worden. Deels kan dat door in de 'index.html' secties aan te passen danwel te vervangen en deels door de configuration property 'content' aan te passen. </p>
<section id="content-methode"><div class="header-wrapper"><h5 id="x3-2-2-1-content-methode"><bdi class="secno">3.2.2.1 </bdi>Content methode</h5><a class="self-link" href="#content-methode" aria-label="Permalink for Section 3.2.2.1"></a></div>
<p>M.b.v. de 'content' configuratie property kunnen alleen secties waarvan de content in markdown bestanden staat worden toegevoegd. In deze property kan per bestand worden aangegeven of die sectie informatief is. Is dat het geval dan wordt automatisch de tekst <code>Dit onderdeel is niet normatief.</code> aan het hoofdstuk toegevoegd.
Het toevoegen van bestanden aan de 'content' configuratie property doe je door de naam van het bestand (zonder de extensie) en een eventueel relevante CSS class in de property te plaatsen.
De volgorde van bestanden binnen <code>content</code> bepaalt de volgorde in het resulterende document.</p>
<p>De code <code>content: {"ch01": "informative", "mermaid": ""},</code> voegt 2 markdown bestanden toe, te weten:</p>
<ul>
<li><code>ch01.md</code> met de CSS class <code>informative</code>;</li>
<li><code>mermaid.md</code> zonder CSS class.</li>
</ul>
<p>Voor een volledige lijst van CSS classes zie de <a href="https://respec.org/docs/#css-classes">ReSpec Documentation</a>. Deze classes zijn ook binnen de markdown files te gebruiken op de volgende manier: </p>
<p><code><div class="example">voorbeeld</div></code></p>
<p>Het gebruik van de 'content' properties is niet verplicht, er mag voor worden gekozen nieuwe content alleen toe te voegen door het 'index.html' bestand aan te passen. De 'content' property moet dan wel uit het lokale 'js/config.js' bestand worden verwijderd of worden uitbecommentarieerd. Ook kan de plaats waar de in 'content' gedefinieerde hoofdstukken moeten worden toegevoegd worden aangepast. Zorg er dan voor dat het 'section' element waarna je die chapters wil toevoegen een 'id' attribuut met een waarde heeft en wijzig in het script in 'index.html' de regel</p>
<p><code>document.getElementById("id-van-sectie").insertAdjacentHTML('afterend', content);</code></p>
<p>zodanig dat de waarde 'id-van-sectie' de waarde van het id heeft.</p>
</section><section id="sectie-methode"><div class="header-wrapper"><h5 id="x3-2-2-2-sectie-methode"><bdi class="secno">3.2.2.2 </bdi>Sectie methode</h5><a class="self-link" href="#sectie-methode" aria-label="Permalink for Section 3.2.2.2"></a></div>
<p>In tegenstelling tot de methode met de 'content' configuratie property kunnen aan het 'index.html' bestand zowel 'sectie' elementen worden toegevoegd waarvan de content uit markdown bestaat als 'sectie' elementen waarvan de content uit html bestaat. Aangezien het gegenereerde Respec bestand een html bestand is kunnen we het alleen toevoegen aan het Respec document door een 'sectie' element toe te voegen aan het index.html bestand.</p>
<p>Bij de methode met de 'section' elementen maken we nog verschil tussen 'sectie' elementen met specifieke waarden voor het 'id' attribuut en 'sectie' elementen die andere waarden voor dat 'id' attribuut hebben of die zelfs helemaal geen 'id' attribuut hebben.</p>
<p>In de onderstaande paragrafen volgt per sectie een toelichting.</p>
</section><section id="secties-met-id-attribuutwaarde-sotd"><div class="header-wrapper"><h5 id="x3-2-2-3-secties-met-id-attribuutwaarde-sotd"><bdi class="secno">3.2.2.3 </bdi>Secties met 'id' attribuutwaarde 'sotd'</h5><a class="self-link" href="#secties-met-id-attribuutwaarde-sotd" aria-label="Permalink for Section 3.2.2.3"></a></div>
<p>Toe te voegen m.b.v. <code><section id="sotd"></section></code>. Leidt ertoe dat het hoofdstuk met de titel 'Status van het document' wordt toegevoegd met als inhoud de, van de waarde van de configuration property 'specStatus' afhankelijke, content van de configuration property 'sotdText'.</p>
<p>Tevens wordt een TOC gegenereerd waarin de titels (incl. evt. hoofdstuk en paragraafnummers) van alle, in het document opgenomen, hoofdstukken en paragrafen worden opgenomen afhankelijk van de configuratie property 'maxTocLevel'. Ook de titels van 'sectie' elementen zonder 'id' attribuut worden daar opgenomen.</p>
<p>Indien de configuration property 'content' bestaat dan worden de daarin gedefinieerde markdown bestanden na de 'sotd' sectie opgenomen.
Zo niet dan worden de in de 'content' configuratie property gedefinieerde secties ook niet toegevoegd en wordt er ook geen TOC gegenereerd.</p>
</section><section id="secties-met-id-attribuutwaarde-abstract"><div class="header-wrapper"><h5 id="x3-2-2-4-secties-met-id-attribuutwaarde-abstract"><bdi class="secno">3.2.2.4 </bdi>Secties met 'id' attribuutwaarde 'abstract'</h5><a class="self-link" href="#secties-met-id-attribuutwaarde-abstract" aria-label="Permalink for Section 3.2.2.4"></a></div>
<p>Indien de sectie wordt toegevoegd met <code><sectie id="abstract" data-include-format="markdown" data-include="filenaam.md"></code> dan krijgt het hoofdstuk de titel Samenvatting zonder hoofdstuknr. als inhoud wordt de inhoud van het bestand 'filenaam.md' toegevoegd.</p>
</section><section id="secties-met-id-attribuutwaarde-conformance"><div class="header-wrapper"><h5 id="x3-2-2-5-secties-met-id-attribuutwaarde-conformance"><bdi class="secno">3.2.2.5 </bdi>Secties met 'id' attribuutwaarde 'conformance'</h5><a class="self-link" href="#secties-met-id-attribuutwaarde-conformance" aria-label="Permalink for Section 3.2.2.5"></a></div>
<p>Door <code><section id='conformance'></section></code> wordt een hoofdstuk met als titel 'Conformiteit' toegevoegd. </p>
<p>De inhoud komt waarschijnlijk uit <a href="https://github.com/Logius-standaarden/respec">https://github.com/Logius-standaarden/respec</a>. Het is nog niet duidelijk hoe dit hoofdstuk zijn inhoud krijgt.</p>
</section><section id="secties-met-id-attribuutwaarde-tof"><div class="header-wrapper"><h5 id="x3-2-2-6-secties-met-id-attribuutwaarde-tof"><bdi class="secno">3.2.2.6 </bdi>Secties met 'id' attribuutwaarde 'tof'</h5><a class="self-link" href="#secties-met-id-attribuutwaarde-tof" aria-label="Permalink for Section 3.2.2.6"></a></div>
<p><code><section id='tof'></section></code> genereert een hoofdstuk met als titel 'Lijst met Figuren' als er in minimaal een van de opgenomen bestanden minimaal een html 'figure' element met een 'figcaption' element is opgenomen of een markdown equivalent daarvan ( '' ). In de markdown variant mag het onderschrift ontbreken.</p>
<p>De titel komt waarschijnlijk uit <a href="https://github.com/Logius-standaarden/respec">https://github.com/Logius-standaarden/respec</a>. Het is nog niet duidelijk hoe die titel wordt toegekend.</p>
</section><section id="secties-met-id-attribuutwaarde-index"><div class="header-wrapper"><h5 id="x3-2-2-7-secties-met-id-attribuutwaarde-index"><bdi class="secno">3.2.2.7 </bdi>Secties met 'id' attribuutwaarde 'index'</h5><a class="self-link" href="#secties-met-id-attribuutwaarde-index" aria-label="Permalink for Section 3.2.2.7"></a></div>
<p><code><section id="index"></section></code> genereert een hoofdstuk met als titel 'Bijlage N Index' als er in minimaal 1 van de in het document opgenomen bestanden (zowel markdown als html) minimaal 1 'dfn' element is opgenomen. Vanuit de tekst kan naar dat element verwezen worden door een 'a' element op te nemen zonder attributen maar met als inhoud de naam van een 'dfn' element.</p>
</section><section id="secties-met-een-andere-id-attribuutwaarde"><div class="header-wrapper"><h5 id="x3-2-2-8-secties-met-een-andere-id-attribuutwaarde"><bdi class="secno">3.2.2.8 </bdi>Secties met een andere 'id' attribuutwaarde</h5><a class="self-link" href="#secties-met-een-andere-id-attribuutwaarde" aria-label="Permalink for Section 3.2.2.8"></a></div>
<ul>
<li>Indien de sectie wordt toegevoegd met <code><sectie id="nnnnnn" data-include-format="markdown" data-include="filenaam.md"></code> dan wordt het hoofdstuk gevuld met de inhoud van 'filenaam.md'. Als 'filenaam.md' met een markdown titel start (ongeacht het level en het aantal blanco regels er voor) dan wordt een hoofdstuknummer voor die titel gegenereerd anders wordt de content zonder titel toegevoegd aan het document. Een evt. titel wordt ook opgenomen in de TOC.</li>
<li>Indien de sectie wordt toegevoegd met <code><sectie data-include-format="markdown" data-include="filenaam.md"></code> dan wijkt het resultaat niet af van die van hierboven. Alleen wordt bij deze variant het 'id' van de sectie en de gerelateerde 'href' in de TOC gegenereerd op basis van de titel van deze sectie.</li>
</ul>
<p>In alle gevallen is <code>data-include-format="markdown"</code> verplicht.</p>
</section><section id="secties-met-data-include-format-html"><div class="header-wrapper"><h5 id="x3-2-2-9-secties-met-data-include-format-html"><bdi class="secno">3.2.2.9 </bdi>Secties met <code>data-include-format="html"</code></h5><a class="self-link" href="#secties-met-data-include-format-html" aria-label="Permalink for Section 3.2.2.9"></a></div>
<p>Dit soort secties wordt direct opgenomen op de plaats waar <code><section id="nnnn" data-include-format="html" data-include="filenaam.html"></section></code> is geplaatst.</p>
<p>Het html fragment in het bestand hoeft niet te bestaan uit 1 root element. Sterker nog als dat wel het geval is en het fragment heeft de root 'div' of 'sectie' dan wordt het fragment niet vertaalt naar een separaat hoofdstuk.</p>
<p>Om een separaat hoofdstuk te kunnen starten dient het document wel met een 'hx' element te starten (h1, h2, h3, etc..).</p>
<p>De titel wordt dan ook opgenomen in de TOC.</p>
<p>Dit soort secties mag ook zonder 'id' attribuut worden opgenomen. Die variant geeft geen ander resultaat dan die hiervoorgeschetst. Alleen wordt bij deze variant het id van de sectie en de gerelateerde href in de TOC gegenereerd op basis van de titel van deze sectie.</p>
<p><code>data-include-format="html"</code> mag worden weggelaten.</p>
</section><section id="andersoortige-secties"><div class="header-wrapper"><h5 id="x3-2-2-10-andersoortige-secties"><bdi class="secno">3.2.2.10 </bdi>Andersoortige secties</h5><a class="self-link" href="#andersoortige-secties" aria-label="Permalink for Section 3.2.2.10"></a></div>
<p>Indien een sectie element leeg is en het 'id' komt niet overeen met een van de, in de voorgaande paragrafen beschreven, bekende id's dan wordt de sectie genegeerd.</p>
</section></section><section id="bijlage-n-referenties"><div class="header-wrapper"><h4 id="x3-2-3-bijlage-n-referenties"><bdi class="secno">3.2.3 </bdi>Bijlage N Referenties</h4><a class="self-link" href="#bijlage-n-referenties" aria-label="Permalink for Section 3.2.3"></a></div>
<p>Wordt alleen opgenomen als er in een van de andere documenten (zowel markdown als html)een referentie is opgenomen in de vorm '[ [Ref] ]' en die referentie in config.js of organisation-config.js is gedefinieerd.</p>
</section><section id="images-in-de-documentatie"><div class="header-wrapper"><h4 id="x3-2-4-images-in-de-documentatie"><bdi class="secno">3.2.4 </bdi>Images in de documentatie</h4><a class="self-link" href="#images-in-de-documentatie" aria-label="Permalink for Section 3.2.4"></a></div>
<p>Plaats eventuele images die je in de Respec documentatie wil opnemen in de 'media' folder. Daarbinnen mag je elke door jou gewenste folderstructuur creëren.</p>
</section></section><section id="lokale-respec-configuratie-properties"><div class="header-wrapper"><h3 id="x3-3-lokale-respec-configuratie-properties"><bdi class="secno">3.3 </bdi>Lokale Respec configuratie properties</h3><a class="self-link" href="#lokale-respec-configuratie-properties" aria-label="Permalink for Section 3.3"></a></div>
<p>Zoals aangegeven maken we in het Respec framework gebruik van een aantal VNG-R properties. Properties die er voor zorgen dat alle Respec documentatie van VNG-R eenzelfde look en feel heeft. Er zijn echter ook een aantal lokale configuratie properties waarmee voor ieder Respec document eigen keuzes kunnen worden gemaakt. Denk daarbij aan de status die het document heeft, de publicatie datum, de editors, etc...</p>
<p>Alle lokale configuratie properties kun je vinden in 'js/config.js' en mag je naar eigen inzicht aanpassen. </p>
<blockquote>
<p>Er moet nog bepaald worden welke properties lokaal moeten zijn en welke globaal (dus welke behoren te staan in de repository 'Respec-Organization-configurations').</p>
</blockquote>
</section><section id="functie-respec-configuratie-properties"><div class="header-wrapper"><h3 id="x3-4-functie-respec-configuratie-properties"><bdi class="secno">3.4 </bdi>Functie Respec configuratie properties</h3><a class="self-link" href="#functie-respec-configuratie-properties" aria-label="Permalink for Section 3.4"></a></div>
<p>Hieronder vind je de totale lijst van Configuratie properties. De vierde kolom geeft aan of het om een globale of lokale property gaat. Voor enkele properties is dat heel logisch,
zo zijn 'localizationStrings' en 'previousPublishVersion' logischerwijs globaal, 'github' en 'title' zijn juist weer lokaal.
De meeste globaal gedefinieerd properties kunnen lokaal overruled worden zoals 'useLogo'. Doe dat echter alleen als daar een hele goede reden voor is.</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Type</th>
<th>Afspraak gebruik binnen VNG-R (Globaal/Lokaal)</th>
<th>Vaste globale waarde of default waarde</th>
<th>Beschrijving</th>
<th>Opmerking</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/addSectionLinks">addSectionLinks</a></td>
<td>boolean</td>
<td>Globaal en lokaal</td>
<td>true</td>
<td>Bepaald of er een paragraafteken (§), met een link naar de paragraaf waar het teken vóór komt te staan, wordt gegenereerd of niet.<br>
Biedt anderen de gelegenheid tom links naar specifieke paragrafen in je Respec document te kopiëren en elders te gebruiken. Er is voor gekozen standaard altijd de links mee te genereren.</td>
<td>Deze property kan lokaal overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/alternateFormats">alternateFormats</a></td>
<td>Array met per formaat de properties 'label' en 'url'.</td>
<td>Lokaal</td>
<td>
</td><td>Hiermee kun je aangeven of je de Respec documentatie ook in een ander formaat dan html aanbiedt, op dit moment is alleen pdf mogelijk.<br>
Deze configuratie property zorgt er voor dat er een pdf bestand wordt gegenereerd en dat er in de Respec documentatie een zin gewijd wordt aan het pdf
formaat met daarin de link naar het pdf bestand.</td>
<td>Deze property mag indien het niet gewenst is een pdf te genereren uit becommentarieerd worden. Dat zou zich voor kunnen doen bij vroege werkversies waarvan je juist níet wil dat deze in een duurzaam formaat gaan circuleren.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/authors">authors</a></td>
<td>Array met per naam de properties 'name', 'company' en 'companyURL'.</td>
<td>Lokaal</td>
<td>
</td><td>Bevat 1 of meerdere beschrijvingen van personen die hebben bijgedragen aan de tot stand koming van het Respec document.<br><br>Het heeft de voorkeur editors te gebruiken
boven authors. Indien deze configuratie property niet aanwezig is wordt 'Auteurs' niet getoond.</td>
<td>Authors hebben bijgedragen aan de initiële content van het Respec document, editors hebben verbeteringen en wijzigingen aangebracht aan die initiële content.</td>
</tr>
<tr>
<td>content</td>
<td>Array (zie een beschrijving onder deze tabel).</td>
<td>Lokaal</td>
<td>
</td><td>Te gebruiken voor het toevoegen van content aan het Respec document. Het heeft de voorkeur [de 'Sectie' methode](./#sectie-methode) te gebruiken.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/editors">editors</a></td>
<td>Array met per naam de properties 'name', 'company' en 'companyURL'.</td>
<td>Lokaal</td>
<td>
</td><td>Één of meerdere beschrijvingen van personen die hebben bijgedragen aan de tot stand koming van het Respec document.<br><br>Het heeft de voorkeur editors te gebruiken boven
authors. Indien deze configuratie property niet aanwezig is wordt 'Redacteurs' getoond zonder vulling.</td>
<td>Authors hebben bijgedragen aan de initiële content van het Respec document, editors hebben verbeteringen en wijzigingen aangebracht aan die initiële content.</td>
</tr>
<tr>
<td><a href="https://github.com/w3c/respec/wiki/formerEditors">formerEditors</a></td>
<td>Array met per naam de properties 'name', 'company' en 'companyURL'.</td>
<td>Lokaal</td>
<td>
</td><td>Bevat 1 of meerdere beschrijvingen van personen die in het verleden hebben bijgedragen aan de totstandkoming van het Respec document.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/github">github</a></td>
<td>URI of een array van de properties 'repoURL' en 'branch'.</td>
<td>Lokaal</td>
<td>
</td><td>Gebruikt voor het genereren van de links in de 'Doe mee' tabel bovenin de Respec documentatie. Kan gevuld worden met
<ul>
<li>een url naar een GitHub repository</li>
<li>het deel van de url van een GitHub repository dat komt na 'https://github.com/'</li>
<li>een set van properties bestaande uit
<ul>
<li>repoURL: Een van bovenstaande opties</li>
<li>branch: de branch waarin het Respec document maar ook issues staan opgeslagen.</li>
</ul>
</li>
</ul>
Verwijst naar de GitHub repository waarin het Informatiemodel wordt beheerd.<br><br>Indien niet gedefinieerd dan wordt de 'Doe mee' tabel niet gegenereerd.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/labelColor">labelColor</a></td>
<td>Hexadecimale colorcode.</td>
<td>Globaal</td>
<td>
</td><td>Definieert de bij de in 'LocalizationStrings' gedefinieerde statussen horende kleuren.</td>
<td>De specifiek voor VNG Realisatie gedefinieerde statussen kennen de volgende kleuren:<br>
<ul>
<li>In Gebruik (IG): <span style="color: #A569BD">█████</span></li>
<li>In Ontwikkeling (IO): <span style="color: #DC7633">█████</span></li>
</ul>
Deze property kan niet Lokaal gespecificeerd en dus ook niet overruled worden.
</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/latestVersion">latestVersion</a></td>
<td>Combinatie van strings en configuration propertynamen.</td>
<td>Globaal en lokaal</td>
<td>Definieert de url van de laatst gepubliceerde versie. Samenvoeging van achtereenvolgens <code>nl_organisationPublishURL</code>, <code>pubDomain</code>, "/", en <code>shortName</code>.</td>
<td>Wordt opgebouwd m.b.v. andere gedefinieerde configuration properties en '/' tekens. Daarin voorkomende hoofdletters worden omgezet naar kleine letters.</td>
<td>Indien deze configuration property of een van de properties waaruit het bestaat niet worden verstrekt dan wordt de gerelateerde rubriek in het Respec document
ook niet aangemaakt.<br><br>Deze property kan lokaal overruled worden maar ben daar terughoudend mee. Bij lokaal definiëren van deze property is de werking
van de links in het document nl. niet te garanderen aangezien die zou kunnen afwijken van de afgesproken structuur in de publishing repository.<br><br>
De laatste gepubliceerde versie is overigens wat anders dan de laatste werkversie (property 'edDraftURI').</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/license">license</a></td>
<td>enumeration</td>
<td>Globaal en lokaal</td>
<td>eupl</td>
<td>Definieert het licentietype dat van toepassing is op het Respec document. VNG-R hanteert de 'EUPL' licentie maar zo gewenst kan ook gekozen worden voor 'CC0', 'CC-BY' of 'CC-BY-ND'.
Toegestane waardes 'eupl', 'cc0', 'cc-by', 'cc-by-nd'. Wordt gebruikt om licentie-logo en bijbehorende link in het document te genereren.</td>
<td>Deze property kan en mag lokaal overruled worden.<br><br>Nieuwe licentie types en het bijbehorende logo's kunnen in zowel in de globale als lokale property 'licenses' worden gedefinieerd.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/licenses">licenses</a></td>
<td>Array met per licentiecode de properties 'name', 'short', 'url' en 'image'.</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Definieert middels een array van configuratie properties ('name', 'short', 'url' en 'image') de te gebruiken soorten licenties waarnaar middels de code kan worden verwezen in de
configuratie-optie 'license'.</td>
<td>Deze property is globaal gedefinieerd maar lokaal mogen er licentietypes toegevoegd worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/localBiblio">localBiblio</a></td>
<td>Array van één of meerdere objecten met met per object de properties 'href', 'title, 'publisher', 'date' en 'rawDate'.</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Hiermee kan een lijst met referenties in het hoofdstuk 'Referenties' worden gegenereerd. Die referenties bevatten metainformatie (bijv. 'auteur', 'publicatiedatum' en 'status') en
links naar de betreffende externe referenties. De referenties worden echter alleen opgenomen in dat hoofdstuk als er in het Respec document naar verwezen wordt middels een
link in de volgende syntax <code>[[Referentienaam]]</code>. Deze syntax geldt voor zowel html als markdown documenten.<br><br>
Indien een link wordt opgenomen in een normatief documentdeel zal de referentie terecht komen in de subparagraaf 'Normatieve referenties'. Is deze opgenomen in een informatief
documentdeel dan komt deze in de subparagraaf 'Informatieve referenties' terecht.<br><br>
Gerefereerd kan worden aan specrefs die beschikbaar zijn in <a href="https://www.specref.org/">de SpecRef database</a> (zie ook
<a href="https://github.com/tobie/specref">https://github.com/tobie/specref</a> of aan zelf in deze propertty gedefinieerde referenties. De syntax voor de inhoud van de localBiblio
property is <a href="https://github.com/tobie/specref/blob/main/schemas/raw-reference.json">hier</a> beschreven.<br><br>
Neem waar van toepassing verwijzingen op naar gerelateerde wetgeving en gerelateerde standaarden op de 'Pas toe leg uit'-lijst van het Forum Standaardisatie of de Gemeentelijke
standaardenlijst met verbindendheid 'pas-toe-of-leg-uit' en 'verplicht'.</td>
<td>Deze property kan zowel lokaal als globaal geconfigureerd worden.<br><br>Voor referenties waarvan we verwachten dat deze vaker gebruikt gaan worden of waarvan inmiddels duidelijk
is dat deze vaker gebruikt worden dient een verzoek te worden gedaan deze op te nemen in de organisation-config.js of nog beter deze op te laten nemen in de
<a href="https://www.specref.org/">SpecRef database</a>. Sterker nog, het wordt zelfs aangemoedigd geen gebruik van deze property te maken. Beheerders van Respec repositories zijn
er vanaf het moment dat de referentie is opgenomen in een van de twee opties zelf verantwoordelijk voor dat deze referenties uit hun eigen config.js worden verwijderd.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/localizationStrings">localizationStrings</a></td>
<td>Array van properties per taalcode</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Bevat voor een aantal doel- ('document statussen' en 'document types') / taalcombinaties de te gebruiken codes en de daarbij horende tekst.</td>
<td>Bij VNG-R zullen we moeten bepalen of alle bestaande codes gewenst zijn en of er nieuwe codes toegevoegd moeten worden.<br><br>Deze property kan lokaal overruled worden maar
ben daar terughoudend mee.<br>Definieer in dat geval een nieuwe code en bijbehorende tekst en neem tegelijkertijd stappen deze op te laten nemen in de globale variant van deze property.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/logos">logos</a></td>
<td>Array per logo van de properties 'src', 'alt', 'id', 'height' en 'url'.</td>
<td>Globaal en lokaal</td>
<td>VNG Realisatie logo</td>
<td>Definieert de src, alternate tekst, url en grootte van het linksboven in het Respec document te plaatsen logo.</td>
<td>Willen we het VNG Realisatie logo geplaatst hebben of een ander logo? (Vraag ligt bij Communicatie)<br><br>Deze property kan lokaal overruled worden. Indien deze property wordt aangepast
moet ook de property 'nl_organisationName' worden aangepast.</td>
</tr>
<tr>
<td><a href="https://github.com/w3c/respec/wiki/maxTocLevel">maxTocLevel</a></td>
<td>Integer</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Is van invloed op twee zaken:
<ul>
<li>het aantal niveau's dat maximaal wordt opgenomen in de inhoudsopgave van het Respec document;</li>
<li>het aantal paragraafniveau's dat in de inhoud van het document wordt benummerd. Dat is altijd 1 niveau meer dan de waarde van deze property.</li>
</ul>
</td>
<td>Default worden alle niveau's opgenomen.<br><br>Deze property kan lokaal overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/nl_organisationName">nl_organisationName</a></td>
<td>String</td>
<td>Globaal en lokaal</td>
<td>VNG Realisatie</td>
<td>Wordt gebruikt om de subtitel en het vertikale label linksboven te genereren.</td>
<td>Deze property kan lokaal overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/nl_organisationPublishURL">nl_organisationPublishURL</a></td>
<td>URL</td>
<td>Globaal en lokaal</td>
<td>https://vng-realisatie.github.io/publicatie</td>
<td>Wordt gebruikt voor het genereren van de link naar de GitHub pages van de huidige, de vorige en de laatst gepubliceerde versie. Een link die leidt naar een document in
de GitHub Pages interface van de 'publicatie' GitHub repository en zo gewenst de in de 'publicatie' repository gedefinieerde custom domain name.<br><br>
Kan worden gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.</td>
<td>Willen we de organisatienaam 'VNG Realisatie' gebruiken of een andere naam? (Vraag ligt bij Communicatie)<br><br>
Deze property kan lokaal overruled worden, in dat geval moet ook de property 'logos' worden aangepast.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/nl_organisationStylesURL">nl_organisationStylesURL</a></td>
<td>URL</td>
<td>Globaal en lokaal</td>
<td>https://gitdocumentatie.logius.nl/publicatie/respec/style/</td>
<td>Definieert de locatie waar het te gebruiken css bestand staat excl. dat bestand zelf.</td>
<td>Deze property kan lokaal overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/w3c/respec/wiki/noTOC">noTOC</a></td>
<td>boolean</td>
<td>Lokaal</td>
<td>false</td>
<td>Bepaald of er links van de inhoud een frame met de inhoudsopgave gegenereerd wordt.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/w3c/respec/wiki/otherLinks">otherLinks</a></td>
<td>Array van properties</td>
<td>Lokaal</td>
<td>
</td><td>Genereert een of meerdere secties (afhankelijk van het aantal 'key' 'data' voorkomens) in de header van het Respec document met als titel de waarde van de property 'key' en als inhoud een of meerdere links.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/w3c/respec/wiki/postProcess">postProcess</a></td>
<td>Functie aanroep.</td>
<td>Globaal</td>
<td>?</td>
<td>Bevat een of meer JavaScript functies die achtereenvolgend opgestart worden nadat Respec klaar is met generatie van het Respec document.</td>
<td>Bevat nu een functie die indien van toepassing mermaid notatie wijze omzet naar graphs.<br><br>
Deze property kan niet lokaal gedefinieerd worden en dus ook niet overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/previousMaturity">previousMaturity</a></td>
<td>enumeration</td>
<td>Lokaal</td>
<td>
</td><td>Status van de voorgaande in de 'publicatie' repository gepubliceerde versie.</td>
<td>Heeft op dit moment geen functie aangezien deze property niet wordt gebruikt in de property 'prevVersion'.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/previousPublishDate">previousPublishDate</a></td>
<td>Datum in het formaat YYYY-MM-DD</td>
<td>Lokaal</td>
<td>
</td><td>Publicatiedatum van de voorgaande versie.</td>
<td>Heeft op dit moment geen functie aangezien deze property niet wordt gebruikt in de property 'prevVersion'.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/previousPublishVersion">previousPublishVersion</a></td>
<td>SemVer notatie</td>
<td>Lokaal</td>
<td>
</td><td>Versienummer van de voorgaande versie in SemVer notatie (https://semver.org/lang/nl/).<br><br>
Wordt gebruikt in de property 'prevVersion'.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/prevVersion">prevVersion</a></td>
<td>Combinatie van strings en configuration propertynamen.</td>
<td>Globaal en lokaal</td>
<td>Samenvoeging van achtereenvolgens <code>nl_organisationPublishURL</code>, <code>pubDomain</code>, "/", <code>shortName</code>, "/" en <code>previousPublishVersion</code>.</td>
<td>Wordt opgebouwd m.b.v. andere gedefinieerde configuration properties en '/' tekens. Daarin voorkomende hoofdletters worden omgezet naar kleine letters.</td>
<td>Indien deze configuration property of een van de properties waaruit het bestaat niet worden verstrekt dan wordt de gerelateerde rubriek in het Respec document
ook niet aangemaakt.<br><br>Deze property kan lokaal overruled worden maar ben daar terughoudend mee. Bij lokaal definiëren van deze property is de werking
van de links in het document nl. niet te garanderen aangezien die zou kunnen afwijken van de afgesproken structuur in de publishing repository.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/pubDomain">pubDomain</a></td>
<td>enumeration</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Definieert het publicatie domein van het Respec document en heeft op dit moment de waarde 'cim'.<br><br>Wordt nu gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.</td>
<td>Er moet bepaald worden of we deze opnemen bij het opbouwen van 'lastVersion', 'thisVersion' en 'prevVersion'.<br><br>
Een andere mogelijkheid is de folder 'cim' vast op te nemen in de configuratie property 'nl_organisationPublishURL' en binnen VNG-R voor deze property de volgende waarden toe te staan en te definiëren:
<ul>
<li>zd (Zaken en Documenten)</li>
<li>bk (Basis en Kerngegevens)</li>
<li>dv (Dienstverlening)</li>
<li>rd (Ruimtelijk domein)</li>
<li>sd (Sociaal domein)</li>
<li>bv (Bedrijfsvoering)</li>
</ul>
Dat betekent wel dat de folderstructuur van de 'publicatie' GitHub repository ook moet worden aangepast.<br><br>Property kan ook een waarde hebben als <code>zd/cim</code>.<br><br>Deze property kan lokaal
overruled worden maar ben daar terughoudend mee. Bij lokaal definiëren van deze property is de werking van de links in het document nl. niet te garanderen aangezien die zou kunnen afwijken van de afgesproken structuur in de publishing repository..
</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/publishDate">publishDate</a></td>
<td>Datum in het formaat YYYY-MM-DD</td>
<td>Lokaal</td>
<td>
</td><td>Publicatiedatum van de huidige versie.<br><br>
Kan evt. worden gebruikt in de property 'thisVersion'.</td>
<td>Heeft op dit moment geen functie aangezien deze property niet wordt gebruikt in de property 'thisVersion'.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/publishVersion">publishVersion</a></td>
<td>SemVer notatie</td>
<td>Lokaal</td>
<td>
</td><td>Versienummer van de huidige versie in SemVer notatie (https://semver.org/lang/nl/).<br><br>
Wordt gebruikt in de property 'thisVersion'.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/shortName">shortName</a></td>
<td>String</td>
<td>Lokaal</td>
<td>
</td><td>Korte naam (bijv. een mnemonic) van het Respec document.<br><br>
Wordt gebruikt in de properties 'lastVersion', 'thisVersion' en 'prevVersion'.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/sotdText">sotdText</a></td>
<td>Array van properties per taalcode.</td>
<td>Globaal en lokaal</td>
<td>
</td><td>Bevat voor een aantal 'specStatus'sen en talen de te gebruiken codes en de daarbij horende volledige tekst.</td>
<td>Bij VNG-R zullen we moeten bepalen welke teksten er bij welke status gegenereerd moeten worden.<br><br>Kan lokaal overruled worden.</td>
</tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/specStatus">specStatus</a></td>
<td>enumeration</td>
<td>Lokaal</td>
<td>
</td><td>Definieert de status van het Respec document. De te gebruiken statussen zijn gedefinieerd in de globale configuratie property 'localizationStrings'. Op dit moment zijn dat:
<ul>
<li><b>cv</b>: Consultatieversie</li>
<li><b>vv</b>: Versie ter vaststelling</li>
<li><b>ig</b>: In Gebruik versie</li>
<li><b>io</b>: In Ontwikkeling versie"</li>
</ul><br><br>
Wordt gebruikt om de subtitel en het vertikale label linksboven te genereren. Bepaald ook de kleur van dat label. Dit dient in de lokale configuratie gedefinieerd te worden.<br><br>
De kleuren voor de VNG-R statussen kunnen worden gedefinieerd in de globale optie 'labelColor'.<br><br>
Kan ook worden gebruikt in de properties 'latestVersion', 'thisVersion' en 'prevVersion'.</td>
<td>
</td></tr>
<tr>
<td><a href="https://github.com/Logius-standaarden/respec/wiki/specType">spectype</a></td>
<td>enumeration</td>
<td>Lokaal</td>
<td>