forked from finanalyst/rakuast-rakudoc-render
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.html
362 lines (328 loc) · 20.6 KB
/
README.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
<!DOCTYPE html>
<html class="theme-light" >
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>RakuDoc renderer</title>
<link rel="icon" href="https://irclogs.raku.org/favicon.ico">
<style>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.index-entry{text-shadow:1px 1px orange}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}div.id-target{display:none}div.nested{margin-left:5rem}div.index-section{margin-left:calc(var(--level)*1rem)}div.index-section>a.index-ref{white-space:nowrap;display:inline-block;width:5em;overflow:hidden;text-overflow:ellipsis}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;transform:translate(-5em, -1em)}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}.procedural-cell-left{text-align:left}.procedural-cell-centre{text-align:center}.procedural-cell-center{text-align:center}.procedural-cell-right{text-align:right}.procedural-cell-top{vertical-align:text-top}.procedural-cell-middle{vertical-align:baseline}.procedural-cell-bottom{vertical-align:text-bottom}.procedural-cell-label{font-weight:bold}li.item{padding-left:.4rem;margin-left:calc(var(--level)*1rem)}li.item::marker{content:attr(data-bullet)}
</style>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/css/bulma.min.css"/>
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
crossorigin=""
/>
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"
integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
crossorigin=""
></script>
<script src="https://unpkg.com/leaflet-providers@latest/leaflet-providers.js"
></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 ) };
document.addEventListener('DOMContentLoaded', function () {
// set up functions needing document variables.
var matchTocState = function ( state ) {
if ( state ) {
document.getElementById("TOC").classList.add('is-hidden');
persist_tocState( 'closed' );
}
else {
document.getElementById("TOC").classList.remove('is-hidden');
persist_tocState( 'open');
}
}
var setTocState = function ( state ) {
if ( state === 'closed') {
document.getElementById("TOC").classList.add('is-hidden');
document.getElementById("navbar-toc-toggle").checked = false;
}
else {
document.getElementById("TOC").classList.remove('is-hidden');
document.getElementById("navbar-toc-toggle").checked = true;
}
};
// initialise if localStorage not set
let theme = persisted_theme();
if (! (theme && change_theme(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 == null ) {
tocState = 'closed';
persist_tocState( tocState );
}
setTocState( 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') });
// 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.
// $('.copy-code').click( function() {
// var codeElement = $(this).next().next(); // skip the label and get the div
// var container = document.createElement('div');
// container.innerHTML = codeElement.html();
// 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);
// });
});
function swap_toc_index(activate) {
let disactivate = (activate == 'toc') ? 'index' : 'toc';
document.getElementById( activate + '-tab').classList.add('is-active');
document.getElementById( disactivate + '-menu').classList.add('is-hidden');
document.getElementById( disactivate + '-tab').classList.remove('is-active');
document.getElementById( 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-128x128">
<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="checkbox">
<input id="navbar-toc-toggle" type="checkbox" />
Show contents
</label>
</div>
<div class="navbar-end">
<div class="navbar-item">
<button id="changeTheme" class="button">Change theme</button>
</div>
</div>
</nav>
<section class="section">
<div class="container">
<div id="RakuDoc_renderer"></div><h1 class="title is-centered">RakuDoc renderer</h1>
<p class="subtitle">Renders RakuDoc sources into an output format dependent on templates</p>
</div>
</section>
<div class="columns">
<div id="TOC" class="column is-one-quarter">
<div class="container px-4">
<div class="tabs" id="tabs">
<ul>
<li class="is-active" id="toc-tab">
<a>Table of Contents</a>
</li>
<li id="index-tab">
<a>Index</a>
</li>
</ul>
</div>
<div class="container">
<aside id="toc-menu" class="menu">
<div class="toc"><h2 class="toc-caption">Table of Contents</h2>
<ul class="toc-list">
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#Overview">Overview</a></li>
<ul>
<li><a href="#Table_of_outputs_and_renderers">Table of outputs and renderers</a></li>
</ul>
<li><a href="#Documentation">Documentation</a></li>
<li><a href="#RenderTextify_utility">RenderTextify utility</a></li>
<li><a href="#Wrapping">Wrapping</a></li>
<li><a href="#Troubleshooting">Troubleshooting</a></li>
<li><a href="#Credits">Credits</a></li>
</ul>
</div>
</aside>
<aside id="index-menu" class="menu is-hidden">
<p>No Index for this page</p>
</aside>
</div>
</div>
</div>
<div class="column">
<div class="container px-4">
<div class="id-target" id=""></div><h2 id="SYNOPSIS" class="heading"><a href="#" title="go to top of document">SYNOPSIS</a></h2>
<ul><li class="item" data-bullet="•" style="--level:0;"> Clone the repository</li>
<li class="item" data-bullet="•" style="--level:0;"> Install using zef as follows (flag is important)</li>
</ul>
<pre class="code-block">zef install . -/precompile-install
</pre>
<div class="id-target" id=""></div><h2 id="Overview" class="heading "><a href="#" title="go to top of document">Overview</a></h2>
<p id="887ec44">This distribution is intended to provide several renderers from RakuDoc v2 into commonly used output formats. </p>
<p id="fed50d3">The basic render engine is <span class="code">RakuDoc::Render</span>, which renders into Text. It is designed to be extended to other output formats by subclassing. </p>
<p id="da74a31">Currently, the other renderers in this distribution are: </p>
<div class="id-target" id=""></div><h3 id="Table_of_outputs_and_renderers" class="heading"><a href="#" title="go to top of document">Table of outputs and renderers</a></h3>
<table class="table">
<tr><th class="">Output</th><th class="">Renderer</th><th class="">Documentation</th></tr>
<tr><td class="">Text</td><td class=""><p id="7cf4d1f"><span class="code">RakuDoc::To::Generic</span> </p>
</td><td class=""><p id="17989ba"><a href="Render.html">a wrapper for <span class="important">RakuDoc::Render</span></a> </p>
</td></tr>
<tr><td class="">Markdown</td><td class=""><p id="1108ad6"><span class="code">RakuDoc::To::Markdown</span> </p>
</td><td class=""><p id="5a1f886"><a href="RakuDoc-To-Markdown.html">Markdown</a> </p>
</td></tr>
<tr><td class="">HTML</td><td class=""><p id="108de6e"><span class="code">RakuDoc::To::HTML</span> </p>
</td><td class=""><p id="dba7e54"><a href="RakuDoc-To-HTML.html">A minimal, single file, 'all in' HTML</a> </p>
</td></tr>
<tr><td class="">HTML-Extra</td><td class="">in development</td><td class="">HTML output using Bulma CSS, Graphviz, Leaflet-Maps, Latex, assumes internet</td></tr></table>
<p id="385bc98">This is software using bleeding edge Rakudo, so look <a href="#Troubleshooting">at troubleshooting below</a>. </p>
<p id="c686f12">Using the <span class="important">Generic</span> renderer, the <span class="basis">canonical method</span> for generating rendered text is possible (which sends output to STDOUT, so pipe to a file), namely </p>
<pre class="code-block">RAKUDO_RAKUAST=1 raku --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output
</pre>
<p id="58b8f3d">Some <a href="#Wrapping">naive wrapping and width modification</a> is possible using environment variables. </p>
<p id="4f9cdd1">The file <a href="https://github.com/Raku/RakuDoc-GAMMA/blob/main/rakudociem-ipsum.rakudoc">rakudociem-ipsum.rakudoc</a> is the file for testing RakuDoc v2 compliance. It can be obtained with: </p>
<pre class="code-block">bin/get-compliance-document
</pre>
<p id="e6059ff">In order to avoid environment variables, eg for Windows, a RakuDoc file can be rendered to Text using the <a href="#RenderTextify_utility">RenderTextify</a>. It avoids some installation problems, stores the output and offers some other output options, eg. </p>
<pre class="code-block">bin/RenderTextify rakudociem-ipsum
</pre>
<p id="416d7d2">(the .rakudoc extension may be omitted if desired) </p>
<div class="id-target" id=""></div><h2 id="Documentation" class="heading "><a href="#" title="go to top of document">Documentation</a></h2>
<p id="9ae1d19">The two main documentation sources are: </p>
<ul><li class="item" data-bullet="•" style="--level:0;"> <p id="108d8e2"><a href="Render.html">An overview of the generic renderer</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="ed6608e"><a href="Templates.html">The templating system</a> </p>
</li>
</ul>
<p id="525d438">Other modules are also documented: </p>
<ul><li class="item" data-bullet="•" style="--level:0;"> <p id="47d5dc9"><a href="Processed.html">Processed - objects to keep track of intermediate state</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="095d72e"><a href="PromiseStrings.html">PStr - Strings containing forward references</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="bcabfa0"><a href="ScopedData.html">ScopedData - an object to keep track of data valid for a block scope</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="24de9e0"><a href="default-text-templates.html">a table of the minimum set of templates to render any RakuDoc source</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="382f337"><a href="MarkUpMeta.html">a grammar for parsing the meta data of a Markup code</a> </p>
</li>
<li class="item" data-bullet="•" style="--level:0;"> <p id="c6789ca"><a href="Numeration.html">an object for numerating items headings</a> </p>
</li>
</ul>
<div class="id-target" id=""></div><h2 id="RenderTextify_utility" class="heading "><a href="#" title="go to top of document">RenderTextify utility</a></h2>
<p id="422ea35">The utility <span class="code">bin/RenderTexify</span> can be called with a RakuDoc source and it saves the result directly to a file, rather than to STDOUT. </p>
<p id="c976c61">For example, </p>
<pre class="code-block">bin/RenderTextify rakudociem-ipsum
</pre>
<p id="6d462ae">will produce the file </p>
<pre class="code-block">rakudociem-ipsum.rakudoc.text
</pre>
<p id="a1f873a">The executable <span class="code">bin/RenderTexify</span> can also be called with the flags <span class="code">test</span> and <span class="code">pretty</span> and the name of a file to render. The use case of these options is to see what templates receive from the rendering engine when developing new templates. </p>
<p id="7bcda11">The file is output to text files with the flag and <span class="code">.text</span> appended to the name. The file format <span class="code">.rakudoc</span> is assumed, and added if missing. </p>
<p id="c976c61">For example, </p>
<pre class="code-block">bin/RenderTextify --pretty rakudociem-ipsum
</pre>
<p id="6d462ae">will produce the file </p>
<pre class="code-block">rakudociem-ipsum.rakudoc.pretty.text
</pre>
<div class="id-target" id=""></div><h2 id="Wrapping" class="heading "><a href="#" title="go to top of document">Wrapping</a></h2>
<p id="1860541">The text output will be naively wrapped (the algorithm is still being developed), either by setting the environment variable POSTPROCESSING=1 or using RenderTextify. For example, </p>
<pre class="code-block">POSTPROCESSING=1 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output
</pre>
<p id="7fa2f84">or </p>
<pre class="code-block">bin/RenderTextify --post-processing doc
</pre>
<p id="96f3270">If the environment variable WIDTH (--width) is also set, the text output will be wrapped to the value. WIDTH by default is set at 80 chars. To set at 70, use: </p>
<pre class="code-block">POSTPROCESSING=1 WIDTH=70 RAKUDO_RAKUAST=1 raku --rakudoc=Generic doc.rakudoc > store-output
</pre>
<p id="7fa2f84">or </p>
<pre class="code-block">bin/RenderTextify --post-processing --width=70 doc
</pre>
<div class="id-target" id=""></div><h2 id="Troubleshooting" class="heading "><a href="#" title="go to top of document">Troubleshooting</a></h2>
<p id="50d54e8">In order to get the RakuDoc render test file (rakudociem-ipsum) to work, a recent version of the Rakudoc compiler is needed, after v2024.06. </p>
<p id="53029b4">If the cannonical command above fails, perhaps with a message such as </p>
<pre class="code-block">===SORRY!===
This element has not been resolved. Type: RakuAST::Type::Simple
</pre>
<p id="347a187">then try </p>
<pre class="code-block">RAKUDO_RAKUAST=1 raku -I. -MRakuDoc::Render --rakudoc=Generic rakudociem-ipsum.rakudoc > store-output
</pre>
<p id="4c23d02">The command above may also generate an error, such as </p>
<pre class="code-block"> ===SORRY!=== Error while compiling ..... (OO::Monitors)
Variable '$cond' is not declared. Perhaps you forgot a 'sub' if this
was intended to be part of a signature?
at ....
------> macro wait-condition(⏏$cond) is export {
because the RakuAST compiler does not yet handle macros, and (OO::Monitors) uses them.
</pre>
<p id="87645ef">The first step is to re-run the test files, eg., </p>
<pre class="code-block">prove6 -I.
</pre>
<p id="02a05a0">This causes a recompilation of the modules in this distribution to be recompiled because the tests run <span class="code">isa-ok</span> on each module. </p>
<p id="0f6ea09">This is sometimes not sufficient. The next step is to use the utility <span class="code">bin/force-compile</span> in the root of the repo. It deletes the <span class="code">.precomp</span> files in the current directory, and runs <span class="code">prove6 -I.</span>. </p>
<div id="Credits"> </div>
<div class="id-target" id=""></div><h2 id="AUTHOR" class="heading"><a href="#" title="go to top of document">AUTHOR</a></h2>
Richard Hainsworth aka finanalyst
<div id="Placement"> </div>
<div class="id-target" id=""></div><h2 id="VERSION" class="heading"><a href="#" title="go to top of document">VERSION</a></h2>
v0.3.1
</div>
<div class="container px-4">
</div>
</div>
</div>
<footer class="footer main-footer">
<div class="container px-4">
<nav class="level">
<div class="level-item">
Rendered from <span class="footer-field">docs/README</span>
</div>
<div class="level-item">
Rendered at 17:31 UTC on 2024-07-06</span>
</div>
<div class="level-item">
Source last modified at 09:54 UTC on 2024-06-30</span>
</div>
</nav>
</div>
</footer>
</body>
</html>