~xigoi/xidoc

ref: a184101f7f6642adcc1c61d1aec23a56600feb66 xidoc/docs/commands.xd -rw-r--r-- 25.3 KiB
a184101fAdam Blažek Forgot a dot? 4 months ago
                                                                                
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
[inject head.xd]
[style
  [rule .command>h3,.command>h4;
    [: font-size; inherit]
  ]
  [rule pre;
    [: white-space; pre-wrap]
  ]
  [rule pre.language-xidoc>code.language-xidoc;
    [:! white-space; pre-wrap]
  ]
  [rule table;
    [: border-collapse; collapse]
    [: width; 100%]
    [: table-layout; fixed]
  ]
  [rule td,th;
    [: border; 1px solid #888]
  ]
  [rule td>div,th>div;
    [: overflow-x; auto]
    [: padding; 0rem 1rem]
  ]
  [rule td>div>table;
    [: table-layout; initial]
  ]
]
[def cmd; name signature explanation;
  [html-add-attrs .command #[arg name];
    [section [code xidoc; [(][arg-expand name] [arg-expand signature][)]];
      [arg explanation]
    ]
  ]
]
[def cmd-nilad; name explanation;
  [html-add-attrs .command #[arg name];
    [section [code xidoc; [(][arg-expand name][)]];
      [arg explanation]
    ]
  ]
]
[def param; name; [ms [arg name]]]
[def cmd-ref; name; [link [code xidoc; [(][arg-expand name][)]]; #[arg name]]]
[def ex; xidoc;
  [table cc;
    [header-row Example; Output]
    [row
      [code-block xidoc; [arg-raw xidoc]];
      [<div> [arg xidoc]];
    ]
  ]
]
[def math-cmd; name signature;
  [row
    [code xidoc; [(][arg-expand name] [arg-expand signature][)]];
    [render [(]$$ [(][arg-expand name] [arg-expand signature][)][)]];
  ]
]
[def math-cmd-nilad; name;
  [row
    [code xidoc; [(][arg-expand name][)]];
    [render [(]$$ [(][arg-expand name][)][)]];
  ]
]
[def experimental;
  [color red; [() Experimental]]
]

[p This is a reference of all xidoc commands. A question mark [ms ?] before a parameter means that it's optional. An asterisk [ms *] before a parameter means that it can take any number of values.]

[section Top-level commands;
  [p These commands can be used anywhere within xidoc, unless overridden by other commands.]

  [section Basic constructs;
    [cmd #; anything;
      Comment. Always returns nothing, ignoring what's inside.
      [ex I [# don't] like xidoc.]
    ]
    [cmd-nilad (;
      Returns a left square bracket.
      [ex I'm a sad robot :[(]]
    ]
    [cmd (); text;
      Wraps [param text] in square brackets.
      [ex [() this-is-not-a-command]]
    ]
    [cmd-nilad );
      Returns a right square bracket.
      [ex I'm a happy robot :[)]]
    ]
    [cmd-nilad [;];
      Returns a semicolon. Useful for “escaping” semicolons in commands that take multiple arguments.
      [ex [list This[;] is[;] only[;] one[;] item]]
    ]
    [cmd \; text;
      Removes the least common indentation from all lines of [arg text], then returns it without expanding. A [" smarter] version of [cmd-ref raw].
      [ex
[code-block nim; [\
  for word in ["This", "correctly", "removes", "indentation"]:
    echo word
]]
      ]
    ]
    [cmd expand; text;
      After expanding [param text], expands it again. Useful for complex command definitions.
    ]
    [cmd hide; text;
      Expands [param text] for its side effects, but doesn't return anything.
    ]
    [cmd pass; code;
      Directly produces the given [param code] without escaping it. Useful if you want to go outside the capabilities of xidoc. The [param code] is still expanded so you can parametrize it, see the [cmd-ref pass-raw] command if you don't want this.
      [if-html [ex [pass <em>Haha!</em> I'm in! <code>'; DROP TABLE xidoc;</code> Oh no, this is a static site…]]]
    ]
    [cmd pass-raw; code;
      Directly produces the given [param code] without escaping it. Useful if you want to go outside the capabilities of xidoc. Works as a combination of [cmd-ref pass] and [cmd-ref raw].
    ]
    [cmd add-to-head; directive;
      Adds the [param directive] to the head of the document. Returns nothing.
    ]
    [cmd raw; text;
      Returns the given [param text] without expanding it.
      [ex [raw [I can use [as many brackets [as I want]], but [they] still have to [[be balanced]]].]]
    ]
    [cmd render; text;
      After expanding [param text], renders it. Useful for complex command definitions.
      [ex [render [raw [it This will be italic despite being inside [ms raw].]]]]
    ]
    [cmd-nilad space;
      Returns a space character. Useful in commands that strip whitespace.
    ]
  ]

  [section Formatting;
    [cmd bf; text;
      Renders [param text] in bold face.
      [ex xidoc is [bf awesome]!]
    ]
    [cmd block-quote; text;
      Creates a block quote.
      [ex [p The first rule in the Zen of Nim is:] [block-quote Copying bad design is not good design.]]
    ]
    [cmd checkboxes; items;
      Renders a list of [param items] with checkboxes. Use [ms [() -]] for an unchecked item, [ms [() v]] for a checked item and [ms [() x]] for a crossed item.
      [ex [checkboxes [v Kill the friend] [- Bury the body] [x Get caught by the police]]]
    ]
    [cmd code; ?language[;] code;
      Renders the [param code] in monospace font. If the [param language] is specified and the target is HTML, the code is syntax-highlighted during compilation using [link Prism; https://prismjs.com/]. See the [link list of supported languages; https://prismjs.com/#supported-languages] to know how to specify the [param language]. xidoc is also supported under the name [ms xidoc]. For generic monospace text, use the [cmd-ref ms] command.
      [ex [code python; [raw print(f"The answer to the universe and stuff is {6 * 7}.")]]]
    ]
    [cmd code-block; ?language[;] code;
      Renders the [param code] as a block in monospace font. If the [param language] is specified and the target is HTML, the code is syntax-highlighted during compilation using [link Prism; https://prismjs.com/]. See the [link list of supported languages; https://prismjs.com/#supported-languages] to know how to specify the [param language]. xidoc is also supported under the name [ms xidoc].
      [ex [code-block javascript; [raw
const factorial = (n) => {
  let result = 1n;
  for (let i = 1; i <= n; i++) {
    result *= BigInt(i);
  }
  return result;
}
]]]
    ]
    [cmd color; color text;
      Colors the [param text] in the given CSS-style [param color].
      [ex You can use [color red; names] or [color #00f; codes]!]
    ]
    [cmd header-row; *fields;
      Creates a header row for a table with the given fields. Has to be used inside a [cmd-ref table] command.
      [ex
[table
  [header-row xidoc; HTML; [LaTeX]]
  [row [code xidoc; [() table]]; [code html; <table></table>]; [code latex; \begin{table}{[...]}\end{table}]]
]]
    ]
    [cmd it; text;
      Renders [param text] in italics.
      [ex xidoc is [it fantastic!]]
    ]
    [cmd lang; language[;] text;
      Renders [param text] in the specified [param language].
      [ex [" Hello!] [lang czech; [" Ahoj!]]]
    ]
    [cmd link; ?text[;] address;
      Adds a link to the given [param address] with an optional [param text] visually replacing the address.
      [ex [link xidoc; http://xidoc.nim.town/] is made in [link Nim; https://nim-lang.org/].]
    ]
    [cmd list; *items;
      Creates an unordered list of [param items].
      [ex Supported targets: [list HTML; [LaTeX]; Gemtext]]
    ]
    [cmd ms; text;
      Renders [param text] in monospace. If you want to show code, it's recommended to use the [cmd-ref code] or [cmd-ref code-block] command instead.
      [ex In HTML, this will produce [ms <code>]. In [LaTeX], this will produce [ms \texttt].]
    ]
    [cmd ordered-list; *items;
      Creates an ordered list of [param items].
      [ex TOP 5 LIST OF SMALLEST POSITIVE INTEGERS: [ordered-list 1; 2; 3; 4; 5]]
    ]
    [cmd p; text;
      Creates a paragraph with the given [param text].
    ]
    [cmd row; *fields;
      Creates a row for a table with the given fields. Has to be used inside a [cmd-ref table] command.
      [ex
[table
  [header-row xidoc; HTML; [LaTeX]]
  [row [code xidoc; [() table]]; [code html; <table></table>]; [code latex; \begin{table}{[...]}\end{table}]]
]]
    ]
    [cmd section; ?title[;] text;
      Creates a section with the given [param title] and [param text] (or without a title if not given). If it's inside another section, it will be a subsection. If it's inside a subsection, it will be a subsubsection. In HTML, this nesting can continue further.
      [ex [section Inception; Are we going too deep?]]
    ]
    [cmd show-title; title;
      Renders the given [param title] without setting it as the title of the document.
    ]
    [cmd spoiler; visible[;] secret;
      Hides the [param secret] text until the [param visible] text is clicked. Works only in environments that support interactivity.
      [ex [spoiler In the series [it The Simpsons], the surname of the main characters is; [it Simpson]]]
    ]
    [cmd table; ?spec[;] content;
      Creates a table with the given [param content], which should consist of [cmd-ref row] commands. The [param spec] is used to help [LaTeX] align the table.
      [ex
[table
  [header-row xidoc; HTML; [LaTeX]]
  [row [code xidoc; [() table]]; [code html; <table></table>]; [code latex; \begin{table}{[...]}\end{table}]]
]]
    ]
    [cmd term; phrase;
      Introduces [param phrase] as a new term. Useful in definitions.
      [ex A [term group] is a monoid where every element has an inverse.]
    ]
    [cmd title; title[;] ?author;
      Renders the given [param title] and sets it as the title of the document. If an [param author] is specified, their name is mentioned under the title.
    ]
    [cmd unit; ?number[;] unit;
      Renders a [param unit] or a quantity expressed with a [param number] and [param unit]. Also works inside math commands.
      [ex [unit 6378; km], [$ [unit 60; [/ km; h]]]]
    ]
  ]

  [section Unicode characters;
    [cmd "; text;
      Puts the given text in quotation marks appropriate for the current language.
      [ex [" Hello!] [lang czech; [" Ahoj!]]]
    ]
    [cmd-nilad --;
      Returns an en dash: [ms –]
      [ex 80[--]100% of people don't know the difference between a dash and a hyphen.]
    ]
    [cmd-nilad ---;
      Returns an em dash: [ms —]
      [ex Em dash [---] the character many people don't know how to write.]
    ]
    [cmd-nilad ...;
      Returns an ellipsis: [ms [...]]
      [ex You can't just substitute three dots for an ellipsis[...]]
    ]
  ]

  [section Math;
    [cmd $; latex;
      Renders [LaTeX] inline math.
      [ex Einstein's famous equation is [$ E = m c^2].]
    ]
    [cmd $$; latex;
      Renders [LaTeX] block math.
      [ex [$$ (A+B)^n = \sum_{k=0}^n {n \choose k} A^{n-k} B^k]]
    ]
    [cmd $$&; latex;
      Renders [LaTeX] aligned block math (with the [ms align] environment).
      [ex [$$& ((f \circ g) \circ h)(x) &= f(g(h(x))) \\ &= (f \circ (g \circ h))(x)]]
    ]
    [cmd matext; latex;
      Renders the given [LaTeX] [param math] using [link maTeXt; https://xigoi.srht.site/matext/] and presents it as preformatted text.
      [ex [matext \vec x \cdot \vec y = \sum_{i=0}^n x_i \cdot y_i]]
    ]
    [cmd dfn; ?name[;] text;
      Renders a mathematical definition paragraph with an optional [param name].
      [ex [dfn An [term inertial system] is a system where the law of inertia holds.]]
    ]
    [cmd example; ?name[;] text;
      Renders a mathematical example paragraph with an optional [param name].
    ]
    [cmd exercise; ?name[;] text;
      Renders a mathematical exercise paragraph with an optional [param name].
      [ex [exercise Determine if the Collatz sequence reaches [$ 1] for every initial value.]]
    ]
    [cmd lemma; ?name[;] text;
      Renders a mathematical lemma paragraph with an optional [param name].
    ]
    [cmd proof; ?name[;] text;
      Renders a mathematical proof paragraph with an optional [param name].
      [ex [proof Left as an exercise to the reader.]]
    ]
    [cmd props; *properties;
      Creates a list of mathematical [param properties]. Currently the same as [cmd-ref list].
      [ex [props [$ \forall x,y,z \in G: (xy)z = x(yz)]; [$ \exists e \in G, \forall x \in G: ex = x = xe]; [$ \forall x \in G, \exists x^{-1} \in G: xx^{-1} = e = x^{-1}x]]]
    ]
    [cmd solution; ?name[;] text;
      Renders a paragraph with the solution to a mathematical problem with an optional [param name].
    ]
    [cmd spoiler-solution; ?name[;] text;
      Renders a paragraph with the solution to a mathematical problem with an optional [param name]. In environments that support interactivity, the [param text] is hidden inside a spoiler (see the [cmd-ref spoiler] command).
    ]
    [cmd theorem; ?name[;] text;
      Renders a mathematical theorem paragraph with an optional [param name].
      [ex [theorem Pythagorean; In a right triangle with legs [$ a,b] and hypotenuse [$ c], [$ a^2 + b^2 = c^2].]]
    ]
  ]

  [section Logos;
    [cmd-nilad LaTeX;
      Renders the [LaTeX] logo.
      [ex [LaTeX]]
    ]
    [cmd-nilad xidoc;
      Renders the xidoc logo. Note that the logo might change in the future.
      [ex [xidoc]]
    ]
  ]

  [section Modularity;
    [cmd inject; file;
      Pastes the content of [param file] and renders it.
    ]
    [cmd include; file[;] *(name[;] value);
      Renders the content of [param file] as a separate document and pastes it. You can give arguments to the subdocument, which can be retrieved with the [cmd-ref template-arg] command.
    ]
    [cmd template-arg; name;
      In a document included with [cmd-ref include], returns the given argument passed to [cmd-ref include].
    ]
  ]

  [section Settings;
    [cmd set-doc-lang; language;
      Sets the global [param language] of the document. Returns nothing.
    ]
    [cmd set-syntax-highlighting-theme; theme;
      Sets the [param theme] for syntax highlighting with the [cmd-ref code] and [cmd-ref code-block] commands. The available themes are [ms default], [ms dark], [ms funky], [ms okaidia], [ms twilight], [ms coy], [ms solarized-light], and [ms tomorrow-night]. You can try out these themes on [link the Prism website; https://prismjs.com/]. There is also [ms funky-x], a modification of [ms funky] with a black background instead of weird stripes.
    ]
    [cmd set-title; title;
      Sets the given [param title] as the title of the document.
    ]
  ]

  [section Custom commands;
    [cmd def; name[;] ?params[;] body;
      Defines a command with the given [param name] that expands to [param body]. If [param params], which should be space-separated words, are given, the command can take arguments, which can be accessed using the [cmd-ref arg] command and its variants ([cmd-ref arg-expand], [cmd-ref arg-raw], [cmd-ref arg-raw-escape]). The command will only be visible in the scope where it was defined[;] if you want it to be visible everywhere, use [cmd-ref def-global].
      [ex [def greet; name; Hello, [arg name]!][greet reader]]
    ]
    [cmd def-global; name[;] ?params[;] body;
      Defines a command with the given [param name] that expands to [param body]. If [param params], which should be space-separated words, are given, the command can take arguments, which can be accessed using the [cmd-ref arg] command and its variants ([cmd-ref arg-expand], [cmd-ref arg-raw], [cmd-ref arg-raw-escape]). The command will be visible everywhere[;] if you want it to be visible only in the scope where it was defined, use [cmd-ref def].
      [ex [hide [def-global greet; name; Hello, [arg name]!]][greet reader]]
    ]
    [cmd arg; parameter;
      Inside a command definition ([cmd-ref def]), renders the argument given to the [param parameter].
      [ex [def greet; name; Hello, [arg name]!][greet reader]]
    ]
    [cmd arg-expand; parameter;
      Inside a command definition ([cmd-ref def]), expands the argument given to the [param parameter], but doesn't render it.
    ]
    [cmd arg-raw; parameter;
      Inside a command definition ([cmd-ref def]), returns the argument given to the [param parameter], but doesn't expand it.
    ]
    [cmd arg-raw-escape; parameter;
      Inside a command definition ([cmd-ref def]), returns the argument given to the [param parameter], but doesn't expand it[;] however, the raw string is rendered.
    ]
    [# arg\; parameter;
      Inside a command definition ([cmd-ref def]), returns the argument given to the [param parameter], but doesn't expand it. Strips common indentation.
    ]
    [# arg\-escape; parameter;
      Inside a command definition ([cmd-ref def]), returns the argument given to the [param parameter], but doesn't expand it[;] however, the raw string is rendered. Strips common indentation.
    ]
  ]

  [section Target detection;
    [cmd if-html; text;
      Evaluates [param text] only if the target is HTML, otherwise returns nothing.
      [ex [if-html You can see this only if you're in HTML!]]
    ]
    [cmd if-latex; text;
      Evaluates [param text] only if the target is [LaTeX], otherwise returns nothing.
      [ex [if-latex You can see this only if you're in [LaTeX]!]]
    ]
    [cmd if-gemtext; text;
      Evaluates [param text] only if the target is Gemtext, otherwise returns nothing.
      [ex [if-gemtext You can see this only if you're in Gemtext!]]
    ]
  ]

  [section List manipulation;
    [cmd for-each; name[;] list[;] template;
      Applies the [param template] to each item of the [param list], making it available as [param name].
      [ex [join [space]; [for-each lang; HTML [LaTeX] Gemtext; xidoc compiles to [lang].]]]
    ]
    [cmd join; separator[;] list;
      Joins the [param list] using the given [param separator].
      [ex [join [space]; [for-each lang; HTML [LaTeX] Gemtext; xidoc compiles to [lang].]]]
    ]
  ]

  [section File manipulation;
    [cmd-nilad get-doc-path-absolute;
      Gets the absolute path of the current document.
    ]
    [cmd get-doc-path-relative-to-containing; name;
      Gets the path of the current document, relative to the nearest ancestor that contains a file/directory/symlink with the given [param name].
      [ex Within the Git repository of xidoc, the command reference is located at [ms [get-doc-path-relative-to-containing .git]].]
    ]
    [cmd list-dirs; pattern;
      Lists all directories that match the glob [param pattern], relative to the current file.
      [ex The subdirectories of the [ms src] directory of xidoc are: [join ,[space]; [list-dirs ../src/*]].]
    ]
    [cmd list-files; pattern;
      Lists all files that match the glob [param pattern], relative to the current file.
      [ex The xidoc sources of this documentation are: [join ,[space]; [list-files *.xd]].]
    ]
  ]

  [section Programming;
    [cmd janet-call; function[;] *arguments;
      Calls the given [link Janet; https://janet-lang.org/] [param function] with the given [param arguments] as strings and returns the result, which has to be a string. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that all Janet is evaluated in the same context, which you can make use of, but be careful!
      [ex The circumference of a circle with radius 6 is [janet-call [raw (fn [radius] (describe (* 2 math/pi (scan-number radius))))]; 6].]
    ]
    [cmd janet-eval; code[;] *(name[;] value);
      Evaluates the given [link Janet; https://janet-lang.org/] [param code]. If some pairs of [param name] and [param value] are given, the code will have access to global definitions with the given names and values. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that all Janet is evaluated in the same context, which you can make use of, but be careful!
      [ex The greatest common divisor of 128 and 168 is [janet-eval [raw (do
    (defn gcd [a b]
      (if (= b 0)
        a
        (gcd b (% a b))))
    (describe (gcd
      (scan-number a)
      (scan-number b))))
      ]; a;128 ; b;168].]
    ]
    [cmd js-call; function[;] *arguments;
      Calls the given [link JavaScript; https://developer.mozilla.org/en-US/docs/Web/JavaScript] [param function] with the given [param arguments] as strings and returns the result as a string. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that the JavaScript engine currently used by xidoc is [link Duktape; https://duktape.org/], which supports only ES5 and certain ES6 features. Notably, it doesn't support arrow functions, so for an anonymous function, you need to use the old [code javascript; (function() { … })] syntax. Also note that all JavaScript is evaluated in the same context, which you can make use of, but be careful!
      [ex The area of a circle with radius 6 is [js-call [raw (function(radius) { return Math.PI * radius * radius; })]; 6].]
    ]
    [cmd js-eval; code[;] *(name[;] value);
      Evaluates the given [link JavaScript; https://developer.mozilla.org/en-US/docs/Web/JavaScript] [param code]. If some pairs of [param name] and [param value] are given, the code will have access to global variables with the given names and values. Useful for doing complex logic when xidoc's built-ins don't suffice. Note that the JavaScript engine currently used by xidoc is [link Duktape; https://duktape.org/], which supports only ES5 and certain ES6 features. Notably, it doesn't support arrow functions, so for an anonymous function, you need to use the old [code javascript; (function() { … })] syntax. Also note that all JavaScript is evaluated in the same context, which you can make use of, but be careful!
      [ex The roots of the polynomial [$ 3x^2 - 18x + 24] are [js-eval [raw {
  var discriminant = b*b - 4*a*c;
  var root1 = (-b + Math.sqrt(discriminant)) / (2 * a);
  var root2 = (-b - Math.sqrt(discriminant)) / (2 * a);
  root1 + ", " + root2
}]; a;3 ; b;-18 ; c;24].]
    ]
  ]

  [section HTML-specific;
    [cmd html-add-attrs; attrs[;] cmd;
      If the target is HTML, adds the given [param attributes] to the tag produced by [param cmd]. Supports the [ms .foo] and [ms #foo] syntax for specifying classes and IDs.
      [if-html [ex [html-add-attrs style="color:pink"; [bf Real men don't fear colors.]]]]
    ]
    [cmd js-module; code;
      If the target is HTML, adds the given JavaScript code to the page as a JavaScript module. If you don't need to use any xidoc commands inside the code, it's recommended to use [cmd-ref js-module-raw].
    ]
    [cmd js-module-raw; code;
      Works as a combination of [cmd-ref js-module] and [cmd-ref raw].
      [if-html [ex [<span> #change-me; I will be changed] [js-module-raw document.getElementById("change-me").innerText = "I was changed"]]]
    ]
    [cmd style; stylesheet;
      Styles an HTML document using xidoc's custom syntax for CSS.
      [if-html [ex [style [rule .golden-frame; [: border; 3px solid gold]]][<div> .golden-frame; This text is a work of art!]]]
    ]
  ]

  [section Other top-level commands;
    [cmd draw; ?width[;] ?height[;] description;
      [experimental] Draws a vector image with the given dimensions based on the [param description]. The [param description] format won't be documented until it's stabilized.
      [if-html [ex
[draw 80; 80;
  [Rcu 180,240; 120,120;;; yellow]
  [Lab 60,120; 180,0; 10; red]
  [Lab 180,0; 300,120; 10; red]
  [Rau 180,260; 60,100;;; brown]
]
      ]]
    ]
  ]
]

[section HTML commands;
  When compiling to HTML, you can use tag commands to generate arbitrary tags. For example, [code xidoc; [raw [<> a; .click-here; href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"; CLICK HERE]]] produces a link with the class [ms click-here] and the text [ms CLICK HERE]. Default tags have a shorthand, so this could also be written as [code xidoc; [raw [<a> .click-here; href="https://www.youtube.com/watch?v=dQw4w9WgXcQ"; CLICK HERE]]]. However, the latter syntax doesn't work for custom tags.
]

[section CSS commands;
  [p xidoc includes a simple set of commands that can be used to generate CSS without having to embed a completely different syntax in your document. It can be included using the [cmd-ref style] command. (If you prefer normal CSS, use [code xidoc; [raw [add-to-head [<style> …]]]].)]
  [cmd :; property[;] value;
    Creates a CSS declaration: [code css; property: value[;]].
  ]
  [cmd :!; property[;] value;
    Creates an important CSS declaration: [code css; property: value !important[;]]. Please don't overuse this.
  ]
  [cmd rule; selector[;] declarations;
    Creates a CSS rule: [code css; selector { declarations }].
  ]
  [cmd var; name[;] ?value;
    If a [param value] is given, declares a CSS variable: [code css; --name: value[;]]. If used outside a [cmd-ref rule], it's assigned to [ms :root]. If used without a [param value], it gets the value of the given variable: [code css; var(--name)].
  ]
]

[section Math commands;
  [p These commands are available in [LaTeX] math. That is, inside the [cmd-ref $], [cmd-ref $$] and [cmd-ref $$&] commands. They are meant to make certain common combinations of [LaTeX] commands easier to type.]
  [cmd _; something;
    Produces literal square brackets in the LaTeX code.
    [ex [$ \sqrt[_ 3]{2}]]
  ]
  [p The following commands should be self-explanatory from the examples:]
  [table cc;
    [header-row Command; Output]
    [math-cmd /; q]
    [math-cmd /; p[;] q]
    [math-cmd .; \frac{p}{q}]
    [math-cmd (); \frac{p}{q}]
    [math-cmd {}; \frac{p}{q}]
    [math-cmd <>; \frac{p}{q}]
    [math-cmd |; \frac{p}{q}]
    [math-cmd ||; \frac{p}{q}]
    [math-cmd v.; \frac{p}{q}]
    [math-cmd floor; \frac{p}{q}]
    [math-cmd ceil; \frac{p}{q}]
    [math-cmd dd; x]
    [math-cmd dv; x]
    [math-cmd dv; f[;] x]
    [math-cmd dv^; 2[;] x]
    [math-cmd dv^; 2[;] f[;] x]
    [math-cmd pdv; x]
    [math-cmd pdv; f[;] x]
    [math-cmd pdv^; 2[;] x]
    [math-cmd pdv^; 2[;] f[;] x]
    [math-cmd mat; a&b\\c&d]
    [math-cmd .mat; a&b\\c&d]
    [math-cmd (mat); a&b\\c&d]
    [math-cmd |mat|; a&b\\c&d]
    [math-cmd ||mat||; a&b\\c&d]
    [math-cmd-nilad lim]
    [math-cmd lim; m]
    [math-cmd lim; x[;] 0]
    [math-cmd-nilad liminf]
    [math-cmd-nilad limsup]
    [math-cmd int; x[;] t]
    [math-cmd int; T[;] x[;] t]
    [math-cmd int; t_1[;] t_2[;] x[;] t]
  ]
]