-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathrakudoc_v2.html
3509 lines (3133 loc) · 344 KB
/
rakudoc_v2.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 class="theme-light" style="scroll-padding-top:var(--bulma-navbar-height)" >
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>RakuDoc</title>
<link rel="icon" href="https://irclogs.raku.org/favicon.ico">
<style>/*! Vanilla CSS */span.basis{font-weight:800}span.important{font-style:italic}span.unusual{text-decoration:underline}span.code{font-weight:500;background-color:linen;display:inline-block;margin:2px;padding:2px}span.overstrike{text-decoration:line-through}span.high{vertical-align:super}span.junior{vertical-align:sub}span.replace{font-style:small-caps;text-shadow:-1px 1px}span.indexed{text-shadow:1px 1px orange}span.indexed:hover::before{content:attr(data-index-text);translate:0 -1.5em;position:absolute;opacity:75%;background-color:#40e0d0;color:indigo}span.keyboard{text-shadow:1px 1px}span.terminal{text-decoration:overline underline}span.footnote{vertical-align:super}span.developer-version{display:none;color:red}span.developer-version span.developer-note{font-family:"Brush Script MT",cursive}span.developer-version:hover{display:inline-block;transform:translate(50px, 100px);z-index:5}span.bad-markdown{text-shadow:1px 1px red}pre.code-block{background-color:#eee;margin:1rem;padding:0 1rem 1rem 1rem}pre.input-block{background-color:#eee;margin:1rem;padding:0 1rem 1rem 1rem}pre.input-block::before{content:"--- input ---";display:block;text-shadow:-2px -2px 4px #000;color:#fff;padding-bottom:1rem}pre.output-block{background-color:#eee;margin:1rem;padding:0 1rem 1rem 1rem}pre.output-block::before{content:"--- output ---";display:block;text-shadow:2px 2px 4px #000;color:#fff;padding-bottom:1rem}div.defn-text{margin-left:1rem}div.defn-term{font-weight:bold;font-style:italic}div.id-target{display:none}div.nested{margin-left:5rem}div.toc .toc-item{margin-left:calc(var(--level)*1rem)}div.toc .toc-item::before{content:attr(data-bullet)}div.toc .toc-item a{padding-left:.4rem}div.index-section{margin-left:calc((var(--level) - 1)*1rem)}div.index-section[data-index-level="1"]{text-shadow:1px 1px orange}div.index-section>a.index-ref{white-space:nowrap;display:inline-block;width:1em}div.index-section>a.index-ref+span{display:none;width:0}div.index-section>a.index-ref:hover+span{display:inline-block;position:absolute;width:auto;z-index:5;background-color:#fff5ee}span.developer-note{display:none;width:0;color:blue;text-shadow:2px 2px 5px green}span.developer-version{display:none;width:0;color:red;text-shadow:2px 2px 5px green}.delta::before,span.developer-text::before{content:"ℹ";vertical-align:super}.delta:hover .developer-version,span.developer-text:hover .developer-version{display:inline-block;position:absolute;width:100%;z-index:5;transform:translate(0.5rem, -1rem)}.delta:hover .developer-note,span.developer-text:hover .developer-note{display:inline-block;position:absolute;width:auto;z-index:5;margin-left:1rem}span.developer-text:hover{text-decoration:overline}div.footer{border-top:2px dashed;margin:1rem 0;padding:2rem}div.footer .footer-field{display:inline-block}div.footer .footer-line{display:block}.heading>a{color:maroon;text-decoration:none}h.title{font-size:larger}table,th,td{border:1px solid;border-collapse:collapse}tbody.procedural tr.procedural .procedural-cell-left{text-align:left}tbody.procedural tr.procedural .procedural-cell-centre{text-align:center}tbody.procedural tr.procedural .procedural-cell-center{text-align:center}tbody.procedural tr.procedural .procedural-cell-right{text-align:right}tbody.procedural tr.procedural .procedural-cell-top{vertical-align:text-top}tbody.procedural tr.procedural .procedural-cell-middle{vertical-align:baseline}tbody.procedural tr.procedural .procedural-cell-bottom{vertical-align:text-bottom}tbody.procedural tr.procedural .procedural-cell-label{font-weight:bold}li.item{padding-left:.4rem;margin-left:calc(var(--level)*1rem)}li.item::marker{content:attr(data-bullet)}div.rakudoc-image-placement{display:flex;flex-direction:column;align-items:center}.rakudoc-placement-error{display:flex;justify-content:sapace-around;align-items:center;color:red;font-weight:bold}.raku-anchor{font-size:.9em;text-decoration:none;visibility:hidden}.heading:hover .raku-anchor{visibility:visible;padding-left:5px}
</style>
<style>/* bulma */
#page-nav{width:25%;position:fixed}#page-nav .panel-block .toc{overflow-y:scroll;height:65vh}#page-nav .panel-block .index{overflow-y:scroll;height:65vh}.main-footer{z-index:1;position:relative}.toc-item:hover{background:var(--bulma-background)}.toc-item a{text-decoration:none;color:var(--bulma-text)}
</style>
<style>/* bulma */
.content p+ul.item-list{margin-top:0}.content p+ol.item-list{margin-top:0}.delta:hover{border:var(--bulma-border-hover) 1px solid}.navbar-start{margin-bottom:1rem}table{width:fit-content;margin:auto}table caption{font-weight:bold}
</style>
<style>/* bulma */
label.chyronToggle input#navbar-toc-toggle{opacity:0;height:0;width:0}label.chyronToggle span.checkmark{top:1rem;position:relative;cursor:pointer}label.chyronToggle input[type=checkbox]{position:absolute;opacity:0;cursor:pointer;height:0;width:0}label.chyronToggle span.checkmark::before{content:"[⇨";color:gray;font-weight:800;line-height:.5rem;font-size:1.75rem;margin-right:.25rem;width:3rem;display:inline-block}label.chyronToggle:hover span.checkmark::before{content:"[ ⇨"}label.chyronToggle input[type=checkbox]:checked+.checkmark::before{content:"[ ⇦"}label.chyronToggle:hover input[type=checkbox]:checked+.checkmark::before{content:"[⇦"}
</style>
<style>/* graphviz */
div.graphviz{display:flex;justify-content:space-around;align-items:center;margin:auto;margin-bottom:1rem}.graphviz-error{display:flex;justify-content:space-around;align-items:center;color:red;font-weight:bold}.graphviz-error span.data{color:green}
</style>
<style>/* hilite */
.raku-code{position:relative;margin:1rem 0}.raku-code button.copy-code{cursor:pointer;opacity:0;padding:0 .25rem .25rem .25rem;position:absolute}.raku-code:hover button.copy-code{opacity:.5}.raku-code label{float:right;font-size:xx-small;font-style:italic;height:auto;padding-right:0}.raku-code pre.browser-hl{padding:7px}.raku-code .code-name{padding-top:.75rem;padding-left:1.25rem;font-weight:500}.raku-code pre{display:inline-block;overflow:scroll;width:100%}.raku-code .rakudoc-in-code{padding:1.25rem 1.5rem}.raku-code .section{padding:0rem}.raku-code .rainbow-name_scalar{color:var(--bulma-link-40);font-weight:500}.raku-code .rainbow-name_array{color:var(--bulma-link);font-weight:500}.raku-code .rainbow-name_hash{color:var(--bulma-link-60);font-weight:500}.raku-code .rainbow-name_code{color:var(--bulma-info);font-weight:500}.raku-code .rainbow-keyword{color:var(--bulma-primary);font-weight:500}.raku-code .rainbow-operator{color:var(--bulma-success);font-weight:500}.raku-code .rainbow-type{color:var(--bulma-danger-60);font-weight:500}.raku-code .rainbow-routine{color:var(--bulma-info-30);font-weight:500}.raku-code .rainbow-string{color:var(--bulma-info-40);font-weight:500}.raku-code .rainbow-string_delimiter{color:var(--bulma-primary-40);font-weight:500}.raku-code .rainbow-escape{color:var(--bulma-black-60);font-weight:500}.raku-code .rainbow-text{color:var(--bulma-black);font-weight:500}.raku-code .rainbow-comment{color:var(--bulma-success-30);font-weight:500}.raku-code .rainbow-regex_special{color:var(--bulma-success-60);font-weight:500}.raku-code .rainbow-regex_literal{color:var(--bulma-black-60);font-weight:500}.raku-code .rainbow-regex_delimiter{color:var(--bulma-primary-60);font-weight:500}.raku-code .rainbow-rakudoc_text{color:var(--bulma-success-40);font-weight:500}.raku-code .rainbow-rakudoc_markup{color:var(--bulma-danger-40);font-weight:500}
</style>
<style>/* latexformula */
div.latex-equation{display:flex;justify-content:space-around;align-items:center}div.latex-equation a.logo{align-self:flex-last}span.latex-formula{display:inline-block;cursor:crosshair}span.latex-formula a{display:none}span.latex-formula:hover>a{display:inline-block;position:absolute;transform:translate(-3rem, -2rem);background:#faebd7}.latex-render-error{color:red;font-weight:bold}
</style>
<style>/* listfiles */
.listf-container{display:flex;flex-direction:column;margin-bottom:1.25rem;font-size:1rem;font-weight:500;line-height:1.5;border:1px solid #ccc;border-bottom:5px solid #d9d9d9;box-shadow:0 2px 3px 0 rgba(0,0,0,.07)}.listf-container .listf-caption{display:flex;justify-content:center;background:#f2f2f2;border-bottom:1px solid #ccc;color:#83858d}.listf-container .listf-file{display:inline-block;border-top:1px solid #ccc;border-bottom:1px solid #ccc;break-inside:avoid}.listf-container .listf-file .listf-link{display:inline-block;width:100%;text-align:center;padding-top:.25rem}.listf-container .listf-file p{padding-left:.5rem;padding-right:.5rem;margin-bottom:.25rem}.listf-error{color:red;font-size:xlarge}
</style>
<style>/* leafletmap */
.leaflet-map-rakudoc{margin-bottom:1rem}.leaflet-map-rakudoc div{margin:auto}
</style>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/default.min.css"/>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@1.0.1/css/bulma.min.css"/>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
crossorigin=""
/>
<script defer src="https://use.fontawesome.com/releases/v5.15.4/js/all.js" integrity="sha384-rOA1PnstxnOBLzCLMcre8ybwbTmemjzdNlILg8O7z1lUkLXozs4DHonlDtnE7fpc" crossorigin="anonymous"></script>
<script src="https://rawgit.com/farzher/fuzzysort/master/fuzzysort.js"></script>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
crossorigin=""
></script>
<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/highlight.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/languages/haskell.min.js"></script>
<script src="https://unpkg.com/leaflet-providers@latest/leaflet-providers.js"
></script>
<script> // Hilite-helper.js
document.addEventListener('DOMContentLoaded', function () {
// trigger the highlighter for non-Raku code
hljs.highlightAll();
// copy code block to clipboard adapted from solution at
// https://stackoverflow.com/questions/34191780/javascript-copy-string-to-clipboard-as-text-html
// if behaviour problems with different browsers add stylesheet code from that solution.
const copyButtons = Array.from(document.querySelectorAll('.copy-code'));
copyButtons.forEach( function( button ) {
var codeElement = button.nextElementSibling.nextElementSibling; // skip the label and get the div
button.addEventListener( 'click', function(insideButton) {
var container = document.createElement('div');
container.innerHTML = codeElement.innerHTML;
container.style.position = 'fixed';
container.style.pointerEvents = 'none';
container.style.opacity = 0;
document.body.appendChild(container);
window.getSelection().removeAllRanges();
var range = document.createRange();
range.selectNode(container);
window.getSelection().addRange(range);
document.execCommand("copy", false);
document.body.removeChild(container);
});
});
});
</script>
<script>// BulmaHelper.js
var change_theme = function (theme) {
document.querySelector('html').className = '';
document.querySelector('html').classList.add('theme-' + theme);
};
var persisted_theme = function () { return localStorage.getItem('theme') };
var persist_theme = function (theme) { localStorage.setItem('theme', theme) };
var persisted_tocState = function () { return localStorage.getItem('tocOpen') };
var persist_tocState = function (tocState) { localStorage.setItem('tocOpen', tocState ) };
var originalIndex;
var originalTOC;
document.addEventListener('DOMContentLoaded', function () {
// set up functions needing document variables.
var matchTocState = function ( state ) {
if ( state ) {
document.getElementById("TOC").classList.remove('is-hidden');
document.getElementById("page-nav").classList.remove('is-hidden');
document.getElementById("mobile-nav").classList.remove('is-hidden');
document.getElementById("MainText").classList.add('is-three-quarters');
document.getElementById("MainText").classList.add('column');
document.getElementById("MainText").classList.remove('px-5');
persist_tocState( 'open');
}
else {
document.getElementById("TOC").classList.add('is-hidden');
document.getElementById("page-nav").classList.add('is-hidden');
document.getElementById("mobile-nav").classList.add('is-hidden');
document.getElementById("MainText").classList.remove('is-three-quarters');
document.getElementById("MainText").classList.remove('column');
document.getElementById("MainText").classList.add('px-5');
persist_tocState( 'closed' );
}
}
var setTocState = function ( state ) {
if ( state === 'closed') {
document.getElementById("TOC").classList.add('is-hidden');
document.getElementById("page-nav").classList.add('is-hidden');
document.getElementById("mobile-nav").classList.add('is-hidden');
document.getElementById("MainText").classList.remove('is-three-quarters');
document.getElementById("MainText").classList.remove('column');
document.getElementById("MainText").classList.add('px-5');
document.getElementById("navbar-toc-toggle").checked = false;
}
else {
document.getElementById("TOC").classList.remove('is-hidden');
document.getElementById("page-nav").classList.remove('is-hidden');
document.getElementById("mobile-nav").classList.remove('is-hidden');
document.getElementById("MainText").classList.add('is-three-quarters');
document.getElementById("MainText").classList.add('column');
document.getElementById("MainText").classList.remove('px-5');
document.getElementById("navbar-toc-toggle").checked = true;
}
};
// initialise if localStorage is set
let theme = persisted_theme();
if ( theme ) {
theme = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
change_theme(theme);
persist_theme(theme);
}
let tocState = persisted_tocState();
if ( tocState ) {
setTocState( tocState );
persist_tocState( tocState );
}
// Add listeners
// Get all "navbar-burger" elements
const $navbarBurgers = Array.prototype.slice.call(document.querySelectorAll('.navbar-burger'), 0);
// Check if there are any navbar burgers
if ($navbarBurgers.length > 0) {
// Add a click event on each of them
$navbarBurgers.forEach(el => {
el.addEventListener('click', () => {
// Get the target from the "data-target" attribute
const target = el.dataset.target;
const $target = document.getElementById(target);
// Toggle the "is-active" class on both the "navbar-burger" and the "navbar-menu"
el.classList.toggle('is-active');
$target.classList.toggle('is-active');
});
});
};
// initialise window state
document.getElementById('changeTheme').addEventListener('click', function () {
let theme = persisted_theme() === 'light' ? 'dark' : 'light';
change_theme(theme);
persist_theme(theme);
});
document.getElementById("navbar-toc-toggle").addEventListener('change', function() {
matchTocState( this.checked )
});
document.getElementById('toc-tab').addEventListener('click', function () { swap_toc_index('','toc') });
document.getElementById('index-tab').addEventListener('click', function () { swap_toc_index('','index') });
document.getElementById('mtoc-tab').addEventListener('click', function () { swap_toc_index('m','toc') });
document.getElementById('mindex-tab').addEventListener('click', function () { swap_toc_index('m','index') });
originalTOC = document.getElementById('toc-menu').getHTML();
originalIndex = document.getElementById('index-menu').getHTML();
document.getElementById("page-nav-search").addEventListener('keyup', function (event) {
filtersearch(event, 'toc-menu', 'index-menu', 'page-nav')
});
document.getElementById("mobile-nav-search").addEventListener('keyup', function (event) {
filtersearch(event, 'mtoc-menu', 'mindex-menu', 'mobile-nav')
});
});
function filtersearch(event, toc,index,nav) {
document.getElementById(toc).innerHTML = originalTOC;
document.getElementById(index).innerHTML = originalIndex;
var searchText = event.srcElement.value.toLowerCase();
if (searchText.length === 0) return;
var menuListElements = document.getElementById(nav).querySelectorAll('.toc-item, .index-section');
var matchingListElements = Array.from(menuListElements).filter(function (item) {
var el;
if ( item.classList.contains('toc-item') ) {
el = item.querySelector('a');
} else {
el = item.querySelector('.index-entry')
}
var listItemHTML = el.innerHTML;
var fuzzyRes = fuzzysort.go(searchText, [listItemHTML])[0];
if (fuzzyRes === undefined || fuzzyRes.score <= 0) {
return false;
}
var res = fuzzyRes.highlight('<b>','</b>');
if (res !== null) {
el.innerHTML = res;
return true;
} else {
return false;
}
});
menuListElements.forEach(function(elem){elem.classList.add('is-hidden')});
matchingListElements.forEach(function(elem){elem.classList.remove('is-hidden')});
};
function swap_toc_index(div, activate) {
let disactivate = (activate == 'toc') ? 'index' : 'toc';
document.getElementById( div + activate + '-tab').classList.add('is-active');
document.getElementById( div + disactivate + '-menu').classList.add('is-hidden');
document.getElementById( div + disactivate + '-tab').classList.remove('is-active');
document.getElementById( div + activate + '-menu').classList.remove('is-hidden');
}
</script>
<link rel="icon" href="https://irclogs.raku.org/favicon.ico">
</head>
<body class="has-navbar-fixed-top">
<nav class="navbar is-fixed-top" role="navigation" aria-label="main navigation">
<div class="navbar-brand">
<figure class="navbar-item is-256x256">
<a href="/index.html">
<img class="is-rounded" src="https://avatars.githubusercontent.com/u/58170775">
</a>
</figure>
<a role="button" class="navbar-burger" aria-label="menu" aria-expanded="false" data-target="pageNavigation">
<span aria-hidden="true"></span>
<span aria-hidden="true"></span>
<span aria-hidden="true"></span>
<span aria-hidden="true"></span>
</a>
</div>
<div id="pageNavigation" class="navbar-menu">
<div class="navbar-start">
<label class="chyronToggle">
<input id="navbar-toc-toggle" type="checkbox" />
<span class="checkmark"> </span>
</label>
</div>
<div class="navbar-end">
<div class="navbar-item">
<button id="changeTheme" class="button">Change theme</button>
</div>
</div>
<nav class="panel is-hidden-tablet" id="mobile-nav">
<div class="panel-block">
<p class="control has-icons-left">
<input class="input" type="text" placeholder="Search" id="mobile-nav-search"/>
<span class="icon is-left">
<i class="fas fa-search" aria-hidden="true"></i>
</span>
</p>
</div>
<p class="panel-tabs">
<a id="mtoc-tab">Table of Contents</a>
<a id="mindex-tab">Index</a>
</p>
<aside id="mtoc-menu" class="panel-block">
<div class="toc"><div class="toc-item" style="--level:0;" data-bullet=""><a href="#VERSION">VERSION</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#SYNOPSIS">SYNOPSIS</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Case_1:_You_are_writing_internal_documentation_to_aid_software_design">Case 1: You are writing internal documentation to aid software design</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Case2:_You_are_writing_external_documentation_to_accompany_some_software">Case2: You are writing external documentation to accompany some software</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Introduction">Introduction</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Two_use_cases_for_RakuDoc">Two use cases for RakuDoc</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Components">Components</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Directive_syntax">Directive syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_syntax">Block syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Markup_instruction_syntax">Markup instruction syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Metadata_syntax">Metadata syntax</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Directives">Directives</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Aliases">Aliases</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_specifiers">Block specifiers</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Config">Config</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Document_termination">Document termination</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Table_constructors">Table constructors</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Placement_from_external_sources">Placement from external sources</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Raku's_mascot">Raku's mascot</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Code-oriented_RakuDoc">Code-oriented RakuDoc</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Declarator_blocks">Declarator blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Data_blocks">Data blocks</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Text-oriented_RakuDoc">Text-oriented RakuDoc</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Headings">Headings</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Numbered_headings">Numbered headings</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_scope">Block scope</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Sections">Sections</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Document_scope">Document scope</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Ordinary_paragraphs">Ordinary paragraphs</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Nesting_or_indenting_a_block">Nesting or indenting a block</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Verbatim_blocks">Verbatim blocks</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Code_blocks">Code blocks</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Preprocessing_and_postprocessing_of_code">Preprocessing and postprocessing of code</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#I/O_blocks">I/O blocks</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Markup_within_verbatim_blocks">Markup within verbatim blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Lists">Lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Unordered_lists">Unordered lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Multi-level_lists">Multi-level lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Multi-paragraph_lists">Multi-paragraph lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Bullets_and_bullet_strategy">Bullets and bullet strategy</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Ordered_lists">Ordered lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Definition_lists">Definition lists</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Numbered_definitions">Numbered definitions</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Tables">Tables</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Visual_description_of_simple_tables">Visual description of simple tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Valid_tables">Valid tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Invalid_tables">Invalid tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Unexpected_tables">Unexpected tables</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Procedural_description_of_tables">Procedural description of tables</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Formulae">Formulae</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#RakuDoc_comments">RakuDoc comments</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Semantic_blocks">Semantic blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#User-defined_blocks">User-defined blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Naming_rules">Naming rules</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Implied_code_and_indentation">Implied code and indentation</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Metadata">Metadata</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Anchors">Anchors</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Table_of_Contents_and_Index">Table of Contents and Index</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Developer_or_delta_notes">Developer or delta notes</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Error_messages">Error messages</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Alternative_rendering">Alternative rendering</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Markup_instructions">Markup instructions</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Formatting_codes">Formatting codes</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Instructions_with_side_effects">Instructions with side effects</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Links">Links</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Examples">Examples</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Placement_links">Placement links</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Alias_placement">Alias placement</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Inline_definitions">Inline definitions</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Space-preserving_text">Space-preserving text</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Comments">Comments</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Notes">Notes</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Keyboard_input">Keyboard input</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Replaceable">Replaceable</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Terminal_output">Terminal output</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Unicode_and_HTML_references">Unicode and HTML references</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Verbatim_text">Verbatim text</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Indexing_terms">Indexing terms</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Markup_extras">Markup extras</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Display_and_metadata">Display and metadata</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Display_only_codes">Display only codes</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Metadata_and_(optional)_display_text">Metadata and (optional) display text</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Metadata_only">Metadata only</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Implementor_considerations">Implementor considerations</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#AUTHORS_0">AUTHORS</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Summary">Summary</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#LICENSE">LICENSE</a></div>
</div>
</aside>
<aside id="mindex-menu" class="panel-block is-hidden">
<div class="index">
<div class="index-section" data-index-level="1" style="--level:1">
<span class="index-entry">Syntax</span>: <a class="index-ref" href="#index-entry-"> § </a><span>Code-oriented RakuDoc</span>, <a class="index-ref" href="#index-entry-_0"> § </a><span>Code-oriented RakuDoc</span>
</div>
</div>
</aside>
</nav>
</div>
</nav>
<nav class="panel is-hidden-mobile" id="page-nav">
<div class="panel-block">
<p class="control has-icons-left">
<input class="input" type="text" placeholder="Search" id="page-nav-search"/>
<span class="icon is-left">
<i class="fas fa-search" aria-hidden="true"></i>
</span>
</p>
</div>
<p class="panel-tabs">
<a id="toc-tab">Table of Contents</a>
<a id="index-tab">Index</a>
</p>
<aside id="toc-menu" class="panel-block">
<div class="toc"><div class="toc-item" style="--level:0;" data-bullet=""><a href="#VERSION">VERSION</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#SYNOPSIS">SYNOPSIS</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Case_1:_You_are_writing_internal_documentation_to_aid_software_design">Case 1: You are writing internal documentation to aid software design</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Case2:_You_are_writing_external_documentation_to_accompany_some_software">Case2: You are writing external documentation to accompany some software</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Introduction">Introduction</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Two_use_cases_for_RakuDoc">Two use cases for RakuDoc</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Components">Components</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Directive_syntax">Directive syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_syntax">Block syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Markup_instruction_syntax">Markup instruction syntax</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Metadata_syntax">Metadata syntax</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Directives">Directives</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Aliases">Aliases</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_specifiers">Block specifiers</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Config">Config</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Document_termination">Document termination</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Table_constructors">Table constructors</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Placement_from_external_sources">Placement from external sources</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Raku's_mascot">Raku's mascot</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Code-oriented_RakuDoc">Code-oriented RakuDoc</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Declarator_blocks">Declarator blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Data_blocks">Data blocks</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Text-oriented_RakuDoc">Text-oriented RakuDoc</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Headings">Headings</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Numbered_headings">Numbered headings</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Block_scope">Block scope</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Sections">Sections</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Document_scope">Document scope</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Ordinary_paragraphs">Ordinary paragraphs</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Nesting_or_indenting_a_block">Nesting or indenting a block</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Verbatim_blocks">Verbatim blocks</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Code_blocks">Code blocks</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Preprocessing_and_postprocessing_of_code">Preprocessing and postprocessing of code</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#I/O_blocks">I/O blocks</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Markup_within_verbatim_blocks">Markup within verbatim blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Lists">Lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Unordered_lists">Unordered lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Multi-level_lists">Multi-level lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Multi-paragraph_lists">Multi-paragraph lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Bullets_and_bullet_strategy">Bullets and bullet strategy</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Ordered_lists">Ordered lists</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Definition_lists">Definition lists</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Numbered_definitions">Numbered definitions</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Tables">Tables</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Visual_description_of_simple_tables">Visual description of simple tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Valid_tables">Valid tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Invalid_tables">Invalid tables</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Unexpected_tables">Unexpected tables</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Procedural_description_of_tables">Procedural description of tables</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Formulae">Formulae</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#RakuDoc_comments">RakuDoc comments</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Semantic_blocks">Semantic blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#User-defined_blocks">User-defined blocks</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Naming_rules">Naming rules</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Implied_code_and_indentation">Implied code and indentation</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Metadata">Metadata</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Anchors">Anchors</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Table_of_Contents_and_Index">Table of Contents and Index</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Developer_or_delta_notes">Developer or delta notes</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Error_messages">Error messages</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Alternative_rendering">Alternative rendering</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Markup_instructions">Markup instructions</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Formatting_codes">Formatting codes</a></div>
<div class="toc-item" style="--level:1;" data-bullet="▹"><a href="#Instructions_with_side_effects">Instructions with side effects</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Links">Links</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Examples">Examples</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Placement_links">Placement links</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Alias_placement">Alias placement</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Inline_definitions">Inline definitions</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Space-preserving_text">Space-preserving text</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Comments">Comments</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Notes">Notes</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Keyboard_input">Keyboard input</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Replaceable">Replaceable</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Terminal_output">Terminal output</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Unicode_and_HTML_references">Unicode and HTML references</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Verbatim_text">Verbatim text</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Indexing_terms">Indexing terms</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Markup_extras">Markup extras</a></div>
<div class="toc-item" style="--level:2;" data-bullet="‣"><a href="#Display_and_metadata">Display and metadata</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Display_only_codes">Display only codes</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Metadata_and_(optional)_display_text">Metadata and (optional) display text</a></div>
<div class="toc-item" style="--level:3;" data-bullet="⁃"><a href="#Metadata_only">Metadata only</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Implementor_considerations">Implementor considerations</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#AUTHORS_0">AUTHORS</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#Summary">Summary</a></div>
<div class="toc-item" style="--level:0;" data-bullet=""><a href="#LICENSE">LICENSE</a></div>
</div>
</aside>
<aside id="index-menu" class="panel-block is-hidden">
<div class="index">
<div class="index-section" data-index-level="1" style="--level:1">
<span class="index-entry">Syntax</span>: <a class="index-ref" href="#index-entry-"> § </a><span>Code-oriented RakuDoc</span>, <a class="index-ref" href="#index-entry-_0"> § </a><span>Code-oriented RakuDoc</span>
</div>
</div>
</aside>
</nav>
<div class="columns">
<div id="TOC" class="column is-one-quarter">
</div>
<div id="MainText" class="column">
<section class="section">
<div class="container">
<div id="RakuDoc"></div><h1 class="title is-centered">RakuDoc</h1>
<p class="subtitle">A Raku slang for documenting Raku software to aid development and use.</p>
</div>
</section>
<div class="content px-4">
<div class="id-target" id="VERSION&nbsp&nbsp&nbsp&nbsp2.11.1"></div><h1 id="VERSION" class="heading py-2 "><a href="#" title="go to top of document">VERSION    2.11.1</a><a class="raku-anchor" title="direct link" href="#VERSION&nbsp&nbsp&nbsp&nbsp2.11.1">§</a></h1>
<p id="b25d5ab">RakuDoc is a markup language with simple instructions for simple tasks and more complex structures to suit larger projects. There is a clear distinction between documenting intended to help maintain and develop the software, and the visually presentations needed by a newcomer to understand how to use software. </p>
<h1 id="SYNOPSIS" class="heading py-2 "><a href="#" title="go to top of document">SYNOPSIS</a><a class="raku-anchor" title="direct link" href="#SYNOPSIS">§</a></h1>
<p id="67e0153">Consider the two ways in which documentation is used. </p>
<div class="id-target" id="Case 1: You are writing internal documentation to aid software design"></div><h2 id="Case_1:_You_are_writing_internal_documentation_to_aid_software_design" class="heading py-2 "><a href="#" title="go to top of document">Case 1: You are writing internal documentation to aid software design</a><a class="raku-anchor" title="direct link" href="#Case 1: You are writing internal documentation to aid software design">§</a></h2>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
unit class Beginners;
<span class="basis">#| a variable to hold number of people</span>
has $.participants;
<span class="basis">#| data that is initially provided by default, but will be overwritten</span>
has $.new-participant = $=finish;
... # code
<span class="basis">=finish</span>
default data string for a new participant
</pre>
</div>
</div>
<p id="1c5b019">A RakuDoc compliant editor or Integrated Design Environment will pick up the text following <span class="code">#|</span> and put it into a pop-up menu whenever you select (e.g. by hovering over) a use of <span class="code">$.participants</span>. </p>
<p id="696b357">The <span class="code">=finish</span> statement is the last piece of code. Everything after it is treated as a string and placed in the <span class="code">$=finish</span> variable. </p>
<p id="e07d1eb">There are other possibilities described below. </p>
<div class="id-target" id="Case2: You are writing external documentation to accompany some software"></div><h2 id="Case2:_You_are_writing_external_documentation_to_accompany_some_software" class="heading py-2 "><a href="#" title="go to top of document">Case2: You are writing external documentation to accompany some software</a><a class="raku-anchor" title="direct link" href="#Case2: You are writing external documentation to accompany some software">§</a></h2>
<p id="29f8f87">Consider the following short description: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_markup"> =begin rakudoc</span><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> =TITLE Tutorial about Flavorizing<br></span><span class="rainbow-rakudoc_markup"> =SUBTITLE</span><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> A short tutorial on Flavorizing your quarks<br><br></span><span class="rainbow-rakudoc_markup"></span><span class="rainbow-rakudoc_text"> =head1 Starting out<br><br> In the section you will learn about how to add flavors to quarks produced<br> by the I<Imagiton>.<br> It goes without saying that these techniques should B<NOT> be carried out<br> without a precocious child nearby; they will strain the imagination of<br> an ossified adult.<br><br> =head2 What is a flavour<br><br> It is well-known (see the L<Wikipedia article|https://en.wikipedia.org/wiki/Flavour_(particle_physics)><br> that quarks N<a quark is a constituent of a hadron> come in six flavors, for example:<br> =item Up<br> =item Bottom<br> =item Charm<br><br> Z< Lots more text ><br> =end rakudoc</span><span class="rainbow-rakudoc_markup"></span>
</pre>
</div>
</div>
<p id="ba2cb62">To indicate that all of the markup above is not Raku code, it is enclosed in a block labelled <span class="important">rakudoc</span>. This is an example of the <span class="basis">delimited</span> form of the <span class="basis">rakudoc</span> block (so named because it is specified between <span class="code">=begin</span> and <span class="code">=end</span> directives). </p>
<p id="0cd037b">The <span class="code">=TITLE</span>, <span class="code">=SUBTITLE</span>, and <span class="code">=SYNOPSIS</span> are <span class="important">semantic blocks</span> containing standard information that can be searched by other tools. For all other purposes, they can be considered to the same as <span class="code">=head1</span> <span class="important">blocks</span>. </p>
<p id="7e4a903">A <span class="code">=head1</span> block begins a top-level heading. The <span class="code">=head2</span> is a second level heading. These are examples of the <span class="basis">abbreviated</span> form of RakuDoc blocks. Any non-empty text lines following a heading specifier are collectively treated as the text of the heading. </p>
<p id="dad237a">The <span class="code">=item</span> components are abbreviated blocks with text entries for a list. There is no need to start or stop a list explicitly; the renderer will place each consecutive <span class="code">=item</span> in a list. The first non-<span class="code">=item</span> paragraph or block will end the list. </p>
<p id="1318a32">Within the text there are several examples of inline markup instructions, which have the form <span class="replace">Upper Unicode character</span> <span class="basis"> < </span> <span class="basis"> > </span>. In the example above, we used: <span class="code">I B N L Z</span>. These are for Important, Basis, Note (a footnote), Link, and Zero (a comment) markup. </p>
<h1 id="Introduction" class="heading py-2 "><a href="#" title="go to top of document">Introduction</a><a class="raku-anchor" title="direct link" href="#Introduction">§</a></h1>
<p id="5c1a6be">RakuDoc has a variety of <span class="basis">components</span> that allow for rich structured documents, provide markup hints to renderers without assuming an output format, extract information from compiled programs, provide information to programs, and enable custom developer extensions. </p>
<p id="6cb35c8">This document describes a revision of RakuDoc modifying the original speculation <a href="https://design.raku.org/S26.html">S26</a> that was implemented as Raku was developed. RakuDoc is intended to be backwards compatible with the POD6 markup language based on S26. </p>
<p id="51f5e1f">RakuDoc is extensible and renderers are free to provide extra functionality beyond the minimum set of instructions described here. </p>
<p id="a778933">The markup language is called <span class="basis">RakuDoc</span> with the <span class="important">CamelCase</span> spelling in order to highlight both the <span class="important">Raku</span> and <span class="important">Doc</span> parts for a newcomer. Some authors may prefer <span class="basis">Rakudoc</span> with <span class="important">Titlecase</span> spelling, which is considered a possible but non-canonical variant. </p>
<p id="e821636">The file extension for a file containing RakuDoc source is <span class="basis">.rakudoc</span>. </p>
<div class="nested"><p id="182319d">As it will become apparent, whitespace and indentation plays an important role in RakuDoc. There are <a href="https://unicode-explorer.com/articles/space-characters">quite a few horizontal whitespace characters</a>; no equivalence is made between them by Rakudo. For example, tabs and spaces are treated as two separate horizontal whitespace characters, with no assumption that a tab is equivalents, say to four (or 2, 8, etc as per style manual) spaces. </p>
<p id="42371de">Consequently, mixing spaces and tabs may <span class="basis">appear</span> to create the same visual margin in some editor, but they may be <span class="basis">treated</span> as different margins when parsing RakuDoc. </p>
<p id="27e2b14">It is recommended that RakuDoc authors choose a single whitespace character (eg, tab or space) for margin alignment. </p></div>
<div class="id-target" id="Two use cases for RakuDoc"></div><h1 id="Two_use_cases_for_RakuDoc" class="heading py-2 "><a href="#" title="go to top of document">Two use cases for RakuDoc</a><a class="raku-anchor" title="direct link" href="#Two use cases for RakuDoc">§</a></h1>
<p id="838eb9a">RakuDoc can be thought of as having components that are closely connected to a program or module that is being documented (<span class="basis">code-oriented RakuDoc</span>), and components that can be used for text-oriented documents, such as the source for a webpage or a book (<span class="basis">text-oriented RakuDoc</span>). </p>
<p id="5b5c9d2">Code-oriented RakuDoc is expected to be "consumed" by users in an editor or Integrated Design Environment (IDE), while text-oriented RakuDoc is consumed in some rendered version, such as an HTML web page, a command-line manpage, or a chapter in an e-book. </p>
<p id="426cbc4">When RakuDoc components are viewed in an editor or IDE to provide information about variables, methods, roles, classes and the like, the information could be made available in a pop-up whenever a documented term is selected in some way (e.g. hovering a mouse over it). In the editor context, RakuDoc blocks and markup should then be treated as a comment to the code. Editors are not expected to render the RakuDoc other than to show the RakuDoc components verbatim, but may do so if it seems expedient. </p>
<p id="2deb86e">When RakuDoc components are viewed in a rendered version (for example, as HTML), components related to a running program should be ignored. </p>
<p id="6d9f3df">Within the body of a program there may be several sections of code, which is called the <span class="basis">ambient context</span>, interleaved between sections of RakuDoc. </p>
<p id="df03123">Sections of code that are intended to be examples within the documentation (i.e. code that is not actual interleaved executable code) can be specified in <span class="code">=code</span> blocks, which are treated as integral parts of the RakuDoc, not as source code in ambient context. </p>
<p id="923ecb8">Consider a source file containing the definition of a class. When the file is edited in an IDE (e.g. the class is being developed or maintained) the code-oriented RakuDoc is useful to help the developer understand the internal structure and function of specific elements within the code. </p>
<p id="b6cf261">Furthermore, when the class is imported into another Raku program the IDE will be able to access the information in declarator blocks attached to specific terms, without needing the source code to be available. </p>
<p id="e8d6fe6">However, by including text-oriented RakuDoc in the same file, end-user documentation can be provided for the class within the same source file. By passing the source through a renderer, a documentation file (e.g. a README.md file for a github repo) can be generated. </p>
<p id="23c8980">This document describes the minimum version of RakuDoc that a renderer or editor must recognise along with some expected rendering behaviors for text-oriented renderers. <span class="important">"Expected behaviors"</span> means that a renderer should approximate the behavior as far as possible given the limitations of the output format, and that the approximation should be a reasonable interpretation of the standard described here. </p>
<p id="46ace8e">The RakuDoc design assumes certain types of customisability, such as the ability to define new blocks or markup instructions. In order to access blocks or functionality not described in this document, the file containing such RakuDoc instructions should contain a <span class="code">use</span> statement that loads a module that provides the information needed to render the extensions. The information provided by this module may be renderer-specific. </p>
<h1 id="Components" class="heading py-2 "><a href="#" title="go to top of document">Components</a><a class="raku-anchor" title="direct link" href="#Components">§</a></h1>
<p id="57f766f">RakuDoc has four main types of components, which are distinguished by their scope and by effect they have on other components. </p>
<div class="defn-term">Directives</div>
<div class="defn-text"><p id="898ea92">Directives define how blocks work. Directives have a similar syntax to regular blocks, but they actually operate on other blocks. New directives cannot be defined. Directives specify <span class="basis">behaviours</span> rather than content. </p>
</div>
<div class="defn-term">Blocks</div>
<div class="defn-text"><p id="dfa61cc">Blocks define complete text components, such as a new paragraph or a code sample or a table. New kinds of blocks can be defined. Blocks contain <span class="basis">actual content</span> which is to be directly rendered in some way. </p>
</div>
<div class="defn-term">Markup instructions</div>
<div class="defn-text">Markup instructions typically define inline items embedded within a block. Some markup instructions only affect the visual rendering of their contents. Others may have side-effects (such as including items into an index or glossary). New markup instructions can be defined. </div>
<div class="defn-term">Metadata options</div>
<div class="defn-text">Options provide information to a block. They may produce side-effects or alter the way a block should be rendered. A document writer can associate any metadata option with any block or directive. A renderer is only required to comply with those listed in this document. </div>
<div class="id-target" id="Directive syntax"></div><h2 id="Directive_syntax" class="heading py-2 "><a href="#" title="go to top of document">Directive syntax</a><a class="raku-anchor" title="direct link" href="#Directive syntax">§</a></h2>
<p id="0cd74ac">These are the syntax forms for each directive. The <span class="code">=</span> of each directive must be the first non-whitespace character on a given line. </p>
<ul class="item-list"><li class="item" data-bullet="•" style="--level:0;"> <p id="cc0d908"><span class="basis">=begin</span> specifies the start of a delimited block </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="6a4f7c6"><span class="basis">=end</span> specifies the end of a delimited block </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="d01d69d"><span class="basis">=for</span> specifies the start of an extended block </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="dbb40c8"><span class="basis">=finish</span> ends ambient code and is followed by text </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="621000b"><span class="basis">=alias</span> specifies a text substitution available in subsequent <span class="code">A<...></span> markup instructions. The general syntax for an alias directive is: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"> =alias ALIAS_NAME Text for substitution<br> = Optional extra text</span>
</pre>
</div>
</div></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="cae64b8"><span class="basis">=config</span> specifies default options to be applied to specific types of blocks or markup instructions within the remainder of the current block-scope. These default options apply from immediately after the <span class="code">=config</span> directive up to the end of the innermost surrounding block. The general syntax for configuration directives is: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
=config <span class="replace">BLOCK_TYPE</span> <span class="replace">CONFIG OPTIONS</span>
= <span class="replace">OPTIONAL EXTRA CONFIG OPTIONS</span>
</pre>
</div>
</div>
<p id="0ad1c1e">If the block-type is single uppercase character <span class="replace">X</span>, the <span class="code">=config</span> directive applies the specified configuration options to the <span class="replace">X</span> markup instruction. For example: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
=config <span class="basis">C</span> :allow<B I>
</pre>
</div>
</div>
<p id="5fd3fad">This configures the <span class="code">C<></span> markup instruction to recognize nested <span class="code">B<></span> and <span class="code">I<></span> markup instructions (both of which would otherwise be treated as verbatim within a <span class="code">C<></span> instruction). </p>
<p id="39742a9">To avoid ambiguities <a href="#Naming_rules">Naming rules</a> are applied to blocks and markup instructions. </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="34eafb0"><span class="basis">=place</span> specifies a source of information that is to be placed in the current block. The general syntax of <span class="basis">=place</span> is </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
=place <span class="replace">URL</span> <span class="replace">OPTIONS</span>
= <span class="replace">MORE OPTIONS IF NECESSARY</span>
</pre>
</div>
</div></li>
</ul>
<div class="id-target" id="Block syntax"></div><h2 id="Block_syntax" class="heading py-2 "><a href="#" title="go to top of document">Block syntax</a><a class="raku-anchor" title="direct link" href="#Block syntax">§</a></h2>
<p id="16a3596">Even though visually similar in some contexts, a block is not a directive...nor vice versa. </p>
<p id="64d137a">Blocks may be specified in three ways: </p>
<ul class="item-list"><li class="item" data-bullet="•" style="--level:0;"> <p id="10137d4"><span class="basis">Delimited form</span> </p>
<p id="be5a1e5">A <span class="basis">delimited block</span> starts with the directive <span class="code">=begin</span> as the first non-whitespace on a line, followed by a valid Raku identifier indicating the name of the block, followed optionally by metadata (see "Metadata" below), followed by content lines. A delimited block is only terminated by an <span class="code">=end</span> directive followed by the same block name. A delimited block that is not terminated by an <span class="code">=end same-block-name</span> instruction throws an error. </p>
<p id="840a700">For example, to specify a <span class="code">para</span> block in delimited form: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_markup"> =begin para</span><span class="rainbow-rakudoc_markup"> </span><span class="rainbow-rakudoc_markup">:</span><span class="rainbow-keyword"></span><span class="rainbow-rakudoc_markup">meta</span><data><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> This text is the content of the block.<br><br> The preceding blank line is also a part of the block,<br> as are these two non-blank lines.<br> =end para</span><span class="rainbow-rakudoc_markup"></span>
</pre>
</div>
</div>
<p id="2401fac">The general syntax is: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
=begin <span class="replace">BLOCK_TYPE</span> <span class="replace">OPTIONAL CONFIG INFO</span>
= <span class="replace">OPTIONAL EXTRA CONFIG INFO</span>
<span class="replace">BLOCK CONTENTS</span>
=end <span class="replace">BLOCK_TYPE</span>
</pre>
</div>
</div></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="eb1dde8"><span class="basis">Extended form</span> </p>
<p id="7981972">An <span class="basis">extended block</span> begins with the directive <span class="code">=for</span> as the first non-whitespace on a line, followed by the name of the block, followed by optional metadata. The next non-blank lines after the metadata specify the content of the block, which is terminated either by the first entirely blank line after the content or by the first line that begins with a RakuDoc directive. For example, to specify a <span class="code">para</span> block in extended format: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_markup"> =for para</span><span class="rainbow-rakudoc_markup"> </span><span class="rainbow-rakudoc_markup">:</span><span class="rainbow-keyword"></span><span class="rainbow-rakudoc_markup">meta</span><data><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> This text is the content of the block.<br><br></span><span class="rainbow-rakudoc_markup"></span><span class="rainbow-rakudoc_text"> This text is NOT content of the block.<br> After a blank line, a new block is started.</span>
</pre>
</div>
</div>
<p id="2401fac">The general syntax is: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
=for <span class="replace">BLOCK_TYPE</span> <span class="replace">OPTIONAL CONFIG INFO</span>
= <span class="replace">OPTIONAL EXTRA CONFIG INFO</span>
<span class="replace">BLOCK DATA</span>
</pre>
</div>
</div></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="b014175"><span class="basis">Abbreviated form</span> </p>
<p id="15d7860">In an <span class="basis">abbreviated block</span>, the name of the block immediately follows an <span class="code">=</span> sign, which must be the first non-whitespace character on the line. Everything after the block name (up to the first blank line or directive line) is considered the content of the block. For example, to specify a <span class="code">para</span> block in abbreviated form: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"> =para This text is the content of the block.<br><br> This text is NOT content of the block.<br> After a blank line, a new block is started.</span>
</pre>
</div>
</div>
<p id="4205bbc">Note that abbreviated blocks cannot be specified with metadata. Any apparent metadata elements placed after an abbreviated block name are instead considered to be part of the block contents. </p>
<p id="70eda09">Where an extended or abbreviated block uses a blank line as the block terminator, the blank line is not included as part of the content of the block. All subsequent whitespace, whether horizontal or vertical (spaces, tabs, new lines), is ignored. Note that horizontal and vertical whitespace can be included inside a delimited block, and may be significant (eg, Verbatim blocks). </p></li>
</ul>
<div class="id-target" id="Markup instruction syntax"></div><h2 id="Markup_instruction_syntax" class="heading py-2 "><a href="#" title="go to top of document">Markup instruction syntax</a><a class="raku-anchor" title="direct link" href="#Markup instruction syntax">§</a></h2>
<p id="b2b32f1">The general syntax of a markup instruction is </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"><Instruction><opening marker><content>|<meta list><closing marker></span>
</pre>
</div>
</div>
<ul class="item-list"><li class="item" data-bullet="•" style="--level:0;"> <p id="3dde2e9"><span class="basis"><Instruction></span> </p>
<p id="19e7f39">This is a single uppercase letter, or a unicode entity with the UPPER property </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="570fd93"><span class="basis"><opening marker></span> </p>
<p id="106a154">This is either one-or-more <span class="code"><</span> characters or a single <span class="code">«</span> character (i.e. The Unicode entity <span class="code">E<|0x00AB></span>) </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="5afccb6"><span class="basis"><content></span> </p>
<p id="b2c4666">This is a string that does not contain the <span class="code">|</span> character (i.e. Unicode entity <span class="code">E<|0x007C></span>), unless that character is inside a nested markup instruction. </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="a779464"><span class="basis"><meta list></span> </p>
<p id="32ea770">Is a list of strings separated by <span class="code">,</span> or <span class="code">;</span>, depending on the semantics imposed by the <Instruction> </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="20432e4"><span class="basis"><closing marker></span> </p>
<p id="7b656dd">Is one-or-more <span class="code">></span> or a single <span class="code">»</span> (i.e. Unicode entity <span class="code">E<|0x00BB></span>). The closing marker must be symmetrical with the markup instruction's opening marker. That is, it must consist of the same number of <span class="code">></span> or <span class="code">»</span> as there were <span class="code"><</span> or <span class="code">«</span> in the opening marker. </p></li>
</ul>
<p id="c82f38e">For example: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
This is <span class="basis">U<unusual></span> text, and this is <span class="basis">I<important></span>.
And this is a <span class="basis">L<link to the Raku Programming Language|https://raku.org></span>.
</pre>
</div>
</div>
<p id="3391a7f">Which would be rendered as: </p>
<div class="nested"><p id="35a426d">For example: This is <span class="unusual">unusual</span> text, and this is <span class="important">important</span>. And this is a <a href="https://raku.org">link to the Raku Programming Language</a>. </p></div>
<div class="id-target" id="Metadata syntax"></div><h2 id="Metadata_syntax" class="heading py-2 "><a href="#" title="go to top of document">Metadata syntax</a><a class="raku-anchor" title="direct link" href="#Metadata syntax">§</a></h2>
<p id="338f42c">Metadata is specified using a Raku option pair, where the value portion is always parsed using Raku semantics. The following table contains some typical examples. </p>
<table class="table is-striped is-bordered"> <thead>
<tr><th>Value is...</th><th>Specify with...</th></tr>
</thead> <tbody>
<tr><td>True</td><td>:key</td></tr>
<tr><td>False</td><td>:!key</td></tr>
<tr><td>Literal</td><td>:key<answer></td></tr>
<tr><td>List</td><td>:key("foo", 42)</td></tr>
<tr><td>Hash</td><td>:key{ :note('Rosebud, they said'), :emphasize }</td></tr>
</tbody>
</table>
<p id="c5b25d4">Numerical values can be specified in any Raku-compatible format (42, 42.0, 42e0, 0x2a, 0d42, 0o52, 0b101010). Strings can either be specified using single or double quotes, or angle brackets (<span class="code">'foo'</span>, <span class="code">"bar"</span>, <span class="code"> <baz> </span>). Note that if a string with whitespace is specified in angle brackets, it is in fact a list of strings: <span class="code"> <foo bar baz> </span> is the same as <span class="code"> ('foo','bar','baz') </span>. </p>
<p id="b86b698">Within the context of the parser of the Raku Programming Language, it is also possible to refer to any compile-time value inside the meta-data. </p>
<p id="d825d96">Requiring Raku semantics for the value component of a metadata option means that for compliance to this specification, RakuDoc markup is prohibited within a metadata option. For example, <span class="code"> :bullet( E<|BALLOT BOX WITH X> ) </span> is prohibited. However, Raku has a syntax for Unicode characters, so <span class="code"> :bullet«\c[BALLOT BOX WITH CHECK]» </span> is possible. Note the <span class="code"> «...» </span> syntax which stringifies the contents with interpolation. </p>
<p id="b9698f1">A renderer may provide a mechanism for allowing RakuDoc within a metadata option but the value part must still conform to Raku semantics, for example, </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>Raku highlighting</label>
<div><pre class="nohighlights">
:caption(<span class="rainbow-string_delimiter">'</span><span class="rainbow-string">This is a heading with I<important markup> in it</span><span class="rainbow-string_delimiter">'</span>)
</pre>
</div>
</div>
<p id="24d19b4">The outer single quotes ensures that the parser passes a plain string to the renderer, which may then post-process the string. </p>
<p id="e2c9158">The metadata of an extended block or abbreviated block may extend beyond the first line declaring the block. Each subsequent line must start with an <span class="code">=</span> in the first virtual column, meaning that it must vertically align with the <span class="code">=</span> of the RakuDoc block declaration, and it must be followed by at least one horizontal whitespace character. </p>
<p id="c82f38e">For example: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_markup"> =for head1</span><span class="rainbow-rakudoc_markup"> </span><span class="rainbow-rakudoc_markup">:</span><span class="rainbow-keyword"></span><span class="rainbow-rakudoc_markup">a-first-line-key</span><firstvalue><span class="rainbow-rakudoc_markup"> </span><span class="rainbow-rakudoc_markup">:</span><span class="rainbow-keyword"></span><span class="rainbow-rakudoc_markup">another-first-line-key</span><xyz><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> = :a-second-line-key(42)<br> = :a-third-line-key<third><br> Content for the header block</span><span class="rainbow-rakudoc_markup"></span>
</pre>
</div>
</div>
<h1 id="Directives" class="heading py-2 "><a href="#" title="go to top of document">Directives</a><a class="raku-anchor" title="direct link" href="#Directives">§</a></h1>
<p id="a6cf5a8">Directives are similar in form to <span class="important">block</span> instructions, but they do not have the extended or delimited forms. If a directive name is preceded by a <span class="code">=begin</span>, <span class="code">=for</span> or <span class="code">=end</span>, then an error will be thrown. </p>
<h2 id="Aliases" class="heading py-2 "><a href="#" title="go to top of document">Aliases</a><a class="raku-anchor" title="direct link" href="#Aliases">§</a></h2>
<p id="9e406c0">The <span class="code">=alias</span> directive provides a way to define block-scoped synonyms for longer RakuDoc sequences, (meta)object declarators from the code, or even entire chunks of ambient source. These synonyms can then be inserted into subsequent RakuDoc using the <a href="#Alias_placements"><span class="code">A<> formatting code</span></a>. </p>
<p id="f28ef43">An <span class="code">=alias</span> is scoped from immediately after its declaration up to the end of the innermost surrounding RakuDoc block. </p>
<p id="fb34b07">The alias directive takes two arguments. The first is an identifier (which is usually specified in uppercase, though this is not mandatory). The second argument consists of one or more lines of replacement text. </p>
<p id="46495cd">Each <span class="code">=alias</span> directive creates a block-scoped RakuDoc macro that can be invoked during document generation by placing the identifier (i.e. the first argument of the alias) in an <span class="code">A<></span> formatting code. This formatting code is then replaced by the text returned by the new macro. </p>
<p id="f51d8b1">The replacement text returned by the alias macro begins at the first non-whitespace character after the alias's identifier, and continues to the end of the line. You can extend the replacement text over multiple lines by starting the following line(s) with an <span class="code">=</span> (at the same level of indentation as the <span class="code">=alias</span> directive itself) followed by at least one whitespace. Each additional line of replacement text uses the original line's (virtual) left margin, as specified by the indentation of the replacement text on the <span class="code">=alias</span> line. </p>
<p id="c82f38e">For example: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text">=alias PROGNAME Earl Irradiatem Evermore<br>=alias VENDOR 4D Kingdoms<br>=alias TERMS_URLS =item </span><span class="rainbow-rakudoc_markup">L<</span><span class="rainbow-rakudoc_text">http://www.4dk.com/eie</span><span class="rainbow-rakudoc_markup">></span><span class="rainbow-rakudoc_text"><br>= =item </span><span class="rainbow-rakudoc_markup">L<</span><span class="rainbow-rakudoc_text">http://www.4dk.co.uk/eie.io/</span><span class="rainbow-rakudoc_markup">></span><span class="rainbow-rakudoc_text"><br>= =item </span><span class="rainbow-rakudoc_markup">L<</span><span class="rainbow-rakudoc_text">http://www.fordecay.ch/canttouchthis</span><span class="rainbow-rakudoc_markup">></span><span class="rainbow-rakudoc_text"><br><br>The use of </span><span class="rainbow-rakudoc_markup">A<</span><span class="rainbow-rakudoc_text">PROGNAME</span><span class="rainbow-rakudoc_markup">></span><span class="rainbow-rakudoc_text"> is subject to the terms and conditions<br>laid out by </span><span class="rainbow-rakudoc_markup">A<</span><span class="rainbow-rakudoc_text">VENDOR</span><span class="rainbow-rakudoc_markup">></span><span class="rainbow-rakudoc_text">, as specified at:<br><br></span><span class="rainbow-rakudoc_markup">A<</span><span class="rainbow-rakudoc_text">TERMS_URLS</span><span class="rainbow-rakudoc_markup">></span>
</pre>
</div>
</div>
<p id="f7babe7">This would produce: </p>
<div class="nested"><p id="44101f5">The use of Earl Irradiatem Evermore is subject to the terms and conditions laid out by 4D Kingdoms, as specified at: </p>
<p id="c65af2e">
<ul class="item-list"><li class="item" data-bullet="•" style="--level:0;"> <p id="70bf44a"><a href="http://www.4dk.com/eie">http://www.4dk.com/eie</a> </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="52b253d"><a href="http://www.4dk.co.uk/eie.io/">http://www.4dk.co.uk/eie.io/</a> </p></li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="869f63d"><a href="http://www.fordecay.ch/canttouchthis">http://www.fordecay.ch/canttouchthis</a> </p></li>
</ul>
</p></div>
<p id="b92bc32">The advantage of using aliases is, obviously, that the same alias can be reused in multiple places in the documentation. Then, if the replacement text ever has to be changed, it need only be modified in a single place: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"> =alias PROGNAME Count Krunchem Constantly<br> =alias VENDOR Last Chance Receivers Intl<br> =alias TERMS_URLS </span><span class="rainbow-rakudoc_markup">L<</span><span class="rainbow-rakudoc_text">http://www.c11.com/generic_conditions</span><span class="rainbow-rakudoc_markup">></span>
</pre>
</div>
</div>
<p id="5f864b5">Alias placement codes may also specify a default display text, before the alias name and separated from it by a <span class="code">|</span>. When a display is specified, it will be used if the requested alias cannot be found (and an <span class="important">"unknown alias"</span> warning will be issued in that case): </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
The use of A<<span class="basis">this program </span>| SOFTWARE> is subject to the terms and conditions
laid out by A<<span class="basis">our company </span>| COMPANY>, as specified at:
A<<span class="basis">(Please visit our website) </span>| OURTERMS>
</pre>
</div>
</div>
<p id="64ea2c2">produces ... </p>
<div class="nested"><p id="4345386">The use of this program is subject to the terms and conditions laid out by our company , as specified at: (Please visit our website) </p></div>
<p id="efa32d9">Furthermore, since none of the aliases were specified in this document, error messages will be produced by the renderer (perhaps at the end of the rendered page). </p>
<div class="id-target" id="Block specifiers"></div><h2 id="Block_specifiers" class="heading py-2 "><a href="#" title="go to top of document">Block specifiers</a><a class="raku-anchor" title="direct link" href="#Block specifiers">§</a></h2>
<p id="cb1496d">The <span class="code">=begin</span>, <span class="code">=end</span>, and <span class="code">=for</span> directives all specify types of blocks. They have already been illustrated in multiple examples and will not be described further here. </p>
<h2 id="Config" class="heading py-2 "><a href="#" title="go to top of document">Config</a><a class="raku-anchor" title="direct link" href="#Config">§</a></h2>
<p id="b2f18fb">All block forms can be associated with metadata options. Typically the metadata are specified for a block using the <span class="basis">extended</span> or <span class="basis">delimited</span> forms. </p>
<p id="4e7f3b7">If the same option needs to be added to multiple blocks, this can be done using a <span class="code">config</span> directive, and then the <span class="basis">abbreviated</span> block form can be used in the <a href="#Block_scope">same block scope</a>. </p>
<p id="cc689f3">For example, suppose we want all <span class="code">=code</span> blocks to be labeled with a `:delta` within some section of a document (<a href="#Developer_or_delta_notes">More information on developer notes</a>). Rather than add a <span class="code">:delta</span> modifier to every individual <span class="code">=code</span>, we could configure every =code block to be automatically given the same developer note, like so: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
<span class="basis">=config code :delta(v2.3.2+, 'oFun enhancements') </span>
=code method droll { say 'what a cool operator' }
=code method drool { say 'what a slob' }
=code method drill { say 'keep up' }
</pre>
</div>
</div>
<p id="64b309c">Within the same block scope, eg., between <span class="code">=begin section</span> and <span class="code">=end section</span> instructions, one or more <span class="code">=config</span> directives can be specified to define the default behaviour of specific block types. Successive <span class="code">=config</span> directives within the same scope are cumulative in effect. Because <span class="code">=config</span> directives specify <span class="important">default</span> behaviours, whenever a particular kind of metadata is explicitly specified for an instance of that block type, that option overrides the defaults set by any active <span class="code">=config</span> blocks. For example: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
<span class="basis">=config item1 :bullet« \c[Earth Globe Europe-Africa] » </span>
<span class="basis">=config item2 :bullet« \c[Hand with Index and Middle Fingers Crossed] » </span>
=comment In the following list, =item1 and =item2 will now have non-standard bullets
The major sources of sustainable energy are:
=item1 geothermal
=item1 fusion
=item2 (eventually)
=begin section
<span class="basis">=config item1 :toc :headerlevel(2)</span>
=comment The following items still have non-standard bullets but now they will
also be added to the table of contents as if they were =head2 blocks
Important items are:
=item1 small scale fusion
=item1 room temperature superconductors
=end section
=comment The following list items will NOT be added to the Table of Contents
because the section containing that particular =config has now ended.
They will still have the non-standard Earth bullets though,
because those two =config directives are still in scope.
=item1 matter-antimatter annihilation
=item1 zero-point energy
</pre>
</div>
</div>
<p id="77da4c0">When an option needs to be associated with all blocks, the config statement may take a whatever <span class="code">*</span> instead of a specific block name, like so: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"> =config * :!error</span>
</pre>
</div>
</div>
<p id="6bc5843">This particular example signals to the renderer that no warning messages should be issued if errors are encountered by <span class="important">any</span> block type in the current block scope. </p>
<p id="247f9fa">The general principle is that more block-specific configurations of metadata take precedence over more generic configurations. For example, suppose in the same block scope, we have: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text">=config * :!error<br>=config item :error<br><br></span><span class="rainbow-rakudoc_markup">=for item</span><span class="rainbow-rakudoc_markup"> </span><span class="rainbow-rakudoc_markup">:</span><span class="rainbow-keyword">!</span><span class="rainbow-rakudoc_markup">error</span><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> Item 1<br><br></span><span class="rainbow-rakudoc_markup"></span><span class="rainbow-rakudoc_markup">=for item</span><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> Item 2<br><br></span><span class="rainbow-rakudoc_markup"></span><span class="rainbow-rakudoc_markup">=for numitem</span><span class="rainbow-rakudoc_markup"><br></span><span class="rainbow-rakudoc_text"> Item 3</span><span class="rainbow-rakudoc_markup"></span>
</pre>
</div>
</div>
<p id="dd7bdf9">Then the configuration would applied in the following order: </p>
<ol class="item-list"><li class="item" data-bullet="1." style="--level:0;"> <p id="d866576">=for item :!error (specific metadata applied to a specific block) </p></li>
<li class="item" data-bullet="2." style="--level:0;"> <p id="86fe916">=config item :error (default metadata applied to a specific kind of block) </p></li>
<li class="item" data-bullet="3." style="--level:0;"> <p id="3297ce6">=config * :!error (default metadata applied to any kind of block) </p></li>
</ol>
<p id="594c8f4">Which means that <span class="important">Item 1</span> would never generate a warning (because its <span class="code">item</span> block is specifically configured not to do so), while <span class="important">Item 2</span> could generate warnings (because <span class="code">item</span> blocks are generically configured to do so), and <span class="important">Item 3</span> would never never generate a warning (because generic blocks are generically configured not to do so). </p>
<p id="217ef78">There is more discussion of <span class="code">=config</span> in the context of <a href="#Formatting_codes">Formatting codes</a>. </p>
<div class="id-target" id="Document termination"></div><h2 id="Document_termination" class="heading py-2 "><a href="#" title="go to top of document">Document termination</a><a class="raku-anchor" title="direct link" href="#Document termination">§</a></h2>
<p id="bc7fc72">The <span class="code">=finish</span> directive indicates the end of all ambient contexts within the document. This means that the parser will treat all the remaining text in the file as a string. </p>
<p id="0d7fd7f">Any text after the <span class="code">=finish</span> block can be accessed as a string within the program (i.e. the ambient code) via the <span class="code">$=finish</span> variable. This can be used to provide data to a program, such as a test. </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label><b>allow</b> styling</label>
<div><pre class="nohighlights">
use JSON::Fast;
my %h = from-json( <span class="basis">$=finish</span> );
say %h.raku;
# more lines of code
<span class="basis">=finish
{ "key1": "a string value", "key2": "another value" }</span>
</pre>
</div>
</div>
<p id="3f66755">This will generate the following output: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>text</label>
<div><pre class="nohighlights">
{:key1("a string value"), :key2("another value")}
</pre>
</div>
</div>
<div class="id-target" id="Table constructors"></div><h2 id="Table_constructors" class="heading py-2 "><a href="#" title="go to top of document">Table constructors</a><a class="raku-anchor" title="direct link" href="#Table constructors">§</a></h2>
<p id="a01bb3f">The <span class="code">=row</span> and <span class="code">=column</span> instructions are directives, not blocks, and they are described in more detail in the section on the <a href="#Procedural_description_of_tables">procedural <span class="code">=table</span> block</a>. </p>
<div class="id-target" id="Placement from external sources"></div><h2 id="Placement_from_external_sources" class="heading py-2 "><a href="#" title="go to top of document">Placement from external sources</a><a class="raku-anchor" title="direct link" href="#Placement from external sources">§</a></h2>
<p id="3eb6881">The <span class="code">=place</span> instruction is a directive that tells the renderer to obtain text, information, or an object from another source. </p>
<p id="c908858">The rendered version of the data placed in the text is considered to form its own block scope. </p>
<p id="207c136">An in-line version of <span class="code">=place</span> is <span class="code">P<...></span>, which is described in more detail in the section on markup codes. </p>
<p id="7c0037b">The schema of the URL specified in a <span class="code">=place</span> directive specifies where to look for the external content: </p>
<table class="table is-striped is-bordered"> <thead>
<tr><th>Schema</th><th>Where to look for the resource</th></tr>
</thead> <tbody>
<tr><td><p id="244b2ee"><span class="code">http(s):</span></p></td><td>Look on the web</td></tr>
<tr><td><p id="6b522ec"><span class="code">file:</span> </p></td><td>Look on the local filesystem</td></tr>
<tr><td><p id="3ed2593"><span class="code">rakudoc:</span></p></td><td>Look in the usual places for Raku documentation</td></tr>
<tr><td><p id="3f64426"><span class="code">man:</span> </p></td><td>Look via a local man(1)</td></tr>
<tr><td><p id="1a88657"><span class="code">defn:</span> </p></td><td>Look in the current document</td></tr>
</tbody>
</table>
<p id="e0691d0">Meanwhile, the kind of content being placed is inferred from the final extension of the URL. For example: </p>
<table class="table is-striped is-bordered"> <thead>
<tr><th>Extension</th><th>How to treat the contents</th></tr>
</thead> <tbody>
<tr><td><p id="c2f9a3c"><span class="code">.txt</span> </p></td><td>Render the contents as plaintext</td></tr>
<tr><td><p id="4df7774"><span class="code">.rakudoc</span></p></td><td>Render the contents as RakuDoc</td></tr>
<tr><td><p id="c1dcdbd"><span class="code">.html</span> </p></td><td>Render the contents as XHTML</td></tr>
<tr><td><p id="26ba1fe"><span class="code">.md</span> </p></td><td>Render the contents as Markdown</td></tr>
<tr><td><p id="5db293c"><span class="code">.json</span> </p></td><td>Render the contents as JSON</td></tr>
<tr><td><p id="26b8eed"><span class="code">.jpg</span> </p></td><td>Render the contents as an image</td></tr>
<tr><td><p id="118dbca"><span class="code">.mp4</span> </p></td><td>Render the contents as a video</td></tr>
</tbody>
</table>
<p id="3e99375">Renderers are not required to render anything other than plaintext and RakuDoc, but may also support other formats if they wish. </p>
<p id="030f7dc">In the case where a URL does not end in a recognized extension: </p>
<div class="raku-code">
<button class="copy-code" title="Copy code"><i class="far fa-clipboard"></i></button>
<label>RakuDoc</label>
<div><pre class="nohighlights">
<span class="rainbow-rakudoc_text"> =place https://example.org/landingpage<br><br> =place rakudoc:App::Rak<br><br> =place file:/usr/share/legal/std_disclaimer</span>
</pre>
</div>
</div>
<p id="5301705">...then the type of content (and hence rendering) may be inferred from the schema: </p>
<table class="table is-striped is-bordered"> <thead>
<tr><th>Schema</th><th>Inferred content type if no final extension</th></tr>
</thead> <tbody>
<tr><td><p id="244b2ee"><span class="code">http(s):</span></p></td><td>XHTML</td></tr>
<tr><td><p id="6b522ec"><span class="code">file:</span> </p></td><td>plaintext</td></tr>
<tr><td><p id="3ed2593"><span class="code">rakudoc:</span></p></td><td>RakuDoc</td></tr>
</tbody>