Improve manual (#1826)

manual/debug.wiki

@@ -2,30 +2,30 @@
 
 == Use the right compiler flags
 === OCaml flags
-Make sure to use "-g" flags when compiling and linking ocaml bytecode.
+Make sure to use {{{-g}}} flags when compiling and linking ocaml bytecode.
 Js_of_ocaml will attempt to preserve variable names.
 
 === Js_of_ocaml flags
-  * [--pretty]     - format the generated JavaScript in a readable way and try to keep OCaml variable names.
-  * [--no-inline]  - prevent function inlining.
-  * [--debug-info] - annotate the JavaScript file with locations from the OCaml sources.
-  * [--source-map] - enable source-map support
+  * {{{--pretty}}}     - format the generated JavaScript in a readable way and try to keep OCaml variable names.
+  * {{{--no-inline}}}  - prevent function inlining.
+  * {{{--debug-info}}} - annotate the JavaScript file with locations from the OCaml sources.
+  * {{{--source-map}}} - enable source-map support
 
 == JavaScript stacktrace
-Js_of_ocaml can attach a JavaScript [Error] that embed the current
-stacktrace to an OCaml exception. The [Error] can be attached with
+Js_of_ocaml can attach a JavaScript {{{Error}}} that embed the current
+stacktrace to an OCaml exception. The {{{Error}}} can be attached with
 {{{Js.Js_error.attach_js_backtrace}}} and extracted using
 {{{Js.Js_error.of_exn}}}. Un-handled OCaml exception will throw any
-JavaScript [Error] attached to them, allowing the JS engine to display
+JavaScript {{{Error}}} attached to them, allowing the JS engine to display
 the stacktrace nicely.
 
-Js_of_ocaml will attach an [Error] automatically when raising an OCaml
+Js_of_ocaml will attach an {{{Error}}} automatically when raising an OCaml
 exception (with {{{raise}}}, not with {{{raise_notrace}}}) if
 {{{Printexc.backtrace_status() = true}}} and either the environment
-variable [OCAMLRUNPARAM] is set with [b=1] or the program was compiled
-with [--enable with-js-error].
+variable {{{OCAMLRUNPARAM}}} is set with {{{b=1}}} or the program was compiled
+with {{{--enable with-js-error}}}.
 
-Note that creating JavaScript [Error]s is costly and can degrade performance a lot.
+Note that creating JavaScript {{{Error}}}s is costly and can degrade performance a lot.
 This is the reason why such feature is not enabled by default.
 
 == Breakpoint

manual/effects.wiki

@@ -3,7 +3,7 @@
 Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
 flag. This is based on partially transforming the program to
 continuation-passing style.
-As a consequence, [[tailcall|tail calls]] are also fully optimized.
+As a consequence, [[tailcall|tail calls]] could be fully optimized (if CPS transformed).
 This is not the default for now since the generated code can be slower,
 larger and less readable.
 The transformation is based on an analysis to detect parts of the code that cannot involves effects and keep it in direct style.

manual/environment-variable.wiki

@@ -3,8 +3,8 @@
 To resolve an environment variable, js_of_ocaml will perform the
 following steps, in the given order:
 
-- If the variable was set at compile time with the [--setenv VAR] flag, return it.
-- If running nodejs and the variable is set in the process environment ([process.env]), return it.
-- If the variable is set in [globalThis.jsoo_env], return it. This can be used
+* If the variable was set at compile time with the {{{--setenv VAR}}} flag, return it.
+* If running nodejs and the variable is set in the process environment ({{{process.env}}}), return it.
+* If the variable is set in {{{globalThis.jsoo_env}}}, return it. This can be used
   to set an environment variable inside a web-browser.
-- Return Not_found
+* Return Not_found

manual/linker.wiki

@@ -35,6 +35,6 @@ function primitive_name(..){
    the returned value of the primitive; when no annotation is provided,
    the linker assumes that the primitive may have side-effects.
  * **{{{//Requires}}}** is used if other primitives need to be loaded first
- * **version_constraint** looks like "{{{< 4.12.0}}}"
+ * **version_constraint** looks like {{{< 4.12.0}}}
  * **{{{//Version}}}** is optional and is rarely used
 All JavaScript code following a **{{{//Provides}}}** annotation is associated to this annotation, until the next **{{{//Provides}}}** annotation.

manual/options.wiki

@@ -1,36 +1,36 @@
 = Main Command-Line options
 
-|= Option name            |= Description                           |
-| --version               | Display the version of the compiler    |
-| -o <file>               | Set the output filename to <file>      |
-| --source-map            | Generate sourcemap                     |
-| --opt {1,2,3}           | Set the compilation profile
-                            (default 1). See **Optimization**
-                             section below.                        |
-| --pretty                | Pretty print javascript output         |
-| --target-env            | Build javascript for the requested
-                            environment (default "isomorphic").
-                            Isomorphic javascript runs in both the
-                            browser & nodejs. "nodejs" & "browser"
-                            options bundle less javascript, but
-                            drop support for APIs incompatible with
-                            the selected runtime.                  |
-| --no-inline             | Disable code inlining                  |
-| --debug-info            | Output debug information               |
-| -I dir                  | Add <dir> to the list of
-                            include directories                    |
-| --file file[:target]    | Register <file> to the pseudo filesystem
-                            and choose the destination <target>. The
-			    <target> can be a directory or a file
-			    (default /static/)                     |
-| --enable <option>       | Enable option <option>                 |
-| --disable <option>      | Disable option <option>                |
+|= Option name               |= Description                           |
+| {{{--version}}}            | Display the version of the compiler    |
+| {{{-o <file>}}}            | Set the output filename to <file>      |
+| {{{--source-map}}}         | Generate sourcemap                     |
+| {{{--opt {1,2,3} }}}       | Set the compilation profile
+                               (default 1). See **Optimization**
+                                section below.                        |
+| {{{--pretty}}}             | Pretty print javascript output         |
+| {{{--target-env}}}         | Build javascript for the requested
+                               environment (default {{{isomorphic}}}).
+                               Isomorphic javascript runs in both the
+                               browser & nodejs. {{{nodejs}}} & {{{browser}}}
+                               options bundle less javascript, but
+                               drop support for APIs incompatible with
+                               the selected runtime.                  |
+| {{{--no-inline}}}          | Disable code inlining                  |
+| {{{--debug-info}}}         | Output debug information               |
+| {{{-I dir}}}               | Add <dir> to the list of
+                               include directories                    |
+| {{{--file file[:target]}}} | Register <file> to the pseudo filesystem
+                               and choose the destination <target>. The
+                               <target> can be a directory or a file
+                               (default /static/)                     |
+| {{{--enable <option>}}}    | Enable option <option>                 |
+| {{{--disable <option>}}}   | Disable option <option>                |
 
 =Optimizations
- * For Debugging: "--pretty --no-inline --debug-info" + eventually "--disable staticeval --disable share"
- * For Production: "--opt 3". It minimize the generated javascript by applying
+ * For Debugging: {{{--pretty --no-inline --debug-info}}} + eventually {{{--disable staticeval --disable share}}}
+ * For Production: {{{--opt 3}}}. It minimize the generated javascript by applying
    various optimizations until a fix-point is reached
-==List of option to "--disable" or "--enable"
+==List of option to {{{--disable}}} or {{{--enable}}}
 
 |= Option name   |= Default |= Description                           |
 | pretty         | false    | Pretty print the javascript output     |

manual/overview.wiki

@@ -23,6 +23,9 @@ Js_of_ocaml is composed of multiple packages:
   * js_of_ocaml-toplevel, lib and tools to build an ocaml toplevel to
     javascript.
 
+There is also a compiler targeting WebAssembly provided by the
+wasm_of_ocaml package, see <<a_manual chapter="wasm_overview" |wasm_of_ocaml>>.
+
 Note: All code examples in this manual use Js_of_ocaml's ppx syntax.
 It is, however, possible to use Js_of_ocaml purely as a compiler
 while using a different package (e.g. gen_js_api, brr) to
@@ -87,8 +90,8 @@ functions are optimized:
 Effect handlers are fully supported with the
 {{{--enable=effects}}} flag. Effect support is disabled by
 default for now since effects are not widely used at the moment and the
-generated code can be slower, larger and less readable. See the dedicated
-manual section about effects for details.
+generated code can be slower, larger and less readable. See the [[effects|dedicated
+manual section]] for details.
 
 Data representation differs from the usual one. Most notably,
 integers are 32 bits (rather than 31 bits or 63 bits), which is their

manual/separate-compilation.wiki

@@ -23,9 +23,9 @@ separate compilation with some differences.
 
 The general idea is generate one JavaScript file containing the
 JavaScript runtime and JavaScript files for every compilation unit (or
-library) needed to run the program. One can then link (or
-"concatenate") all individual JavaScript files together, respecting
-the order induced by dependencies, into a single JavaScript file.
+library) needed to run the program. One can then link all individual
+JavaScript files together, respecting the order induced by
+dependencies, into a single JavaScript file.
 
 === 1. Build the runtime
 

manual/wasm_overview.wiki

@@ -5,7 +5,7 @@
 Wasm_of_ocaml is a compiler from OCaml bytecode programs to WebAssembly.
 It provides an alternative way to run pure OCaml programs in JavaScript environments like browsers and Node.js.
 
-The compiler is provided by the wasm_of_ocaml-package. The <<a_manual chapter="overview" |Js_of_ocaml libraries>> are compatible with this compiler.
+The compiler is provided by the wasm_of_ocaml-compiler package. The <<a_manual chapter="overview" |Js_of_ocaml libraries>> are compatible with this compiler.
 
 == Installation
 
@@ -49,8 +49,8 @@ supported in general. However,
 Compared to Js_of_ocaml, dynlink is not supported, and it is not possible to build an OCaml toplevel. The virtual filesystem is not implemented either.
 
 OCaml 5.x code using effect handlers can be compiled in two different ways:
-one can enable the CPS transformation from `js_of_ocaml` by passing the
-`--effects=cps` flag. Without the flag `wasm_of_ocaml` will instead default to
-`--effects=jspi` and emit code utilizing
- [the JavaScript-Promise Integration extension](https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md).
+one can enable the CPS transformation from {{{js_of_ocaml}}} by passing the
+{{{--effects=cps}}}{ flag. Without the flag {{{wasm_of_ocaml}}} will instead default to
+{{{--effects=jspi}}} and emit code utilizing
+ [[https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md|the JavaScript-Promise Integration extension]].
 The CPS transformation is not the default since the generated code is slower, larger and less readable. On the other hand, the JSPI extension is not yet enabled by default in Web browsers, and performing effects is slower when using this extension.