From 8cd721b3df5deb4f04e30cee0247d69960c723e5 Mon Sep 17 00:00:00 2001 From: hhugo Date: Tue, 4 Feb 2025 00:27:34 +0100 Subject: [PATCH] Improve manual (#1826) --- manual/debug.wiki | 24 +++++++------- manual/effects.wiki | 2 +- manual/environment-variable.wiki | 8 ++--- manual/linker.wiki | 2 +- manual/options.wiki | 56 ++++++++++++++++---------------- manual/overview.wiki | 7 ++-- manual/separate-compilation.wiki | 6 ++-- manual/wasm_overview.wiki | 10 +++--- 8 files changed, 59 insertions(+), 56 deletions(-) diff --git a/manual/debug.wiki b/manual/debug.wiki index 71bc2b15e7..5224bfb858 100644 --- a/manual/debug.wiki +++ b/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 diff --git a/manual/effects.wiki b/manual/effects.wiki index 5794e8bf43..49669ab15e 100644 --- a/manual/effects.wiki +++ b/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. diff --git a/manual/environment-variable.wiki b/manual/environment-variable.wiki index e45e11b7fc..99edb3ae1b 100644 --- a/manual/environment-variable.wiki +++ b/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 \ No newline at end of file +* Return Not_found \ No newline at end of file diff --git a/manual/linker.wiki b/manual/linker.wiki index 344ff6b58e..f12de22b11 100644 --- a/manual/linker.wiki +++ b/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. diff --git a/manual/options.wiki b/manual/options.wiki index 7ef4fabb35..bf8a0f76f6 100644 --- a/manual/options.wiki +++ b/manual/options.wiki @@ -1,36 +1,36 @@ = Main Command-Line options -|= Option name |= Description | -| --version | Display the version of the compiler | -| -o | Set the output filename to | -| --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 to the list of - include directories | -| --file file[:target] | Register to the pseudo filesystem - and choose the destination . The - can be a directory or a file - (default /static/) | -| --enable