From 2e6aee8af5ad5fa55fb6c409979099a783125272 Mon Sep 17 00:00:00 2001 From: Hugo Heuzard Date: Mon, 3 Feb 2025 21:58:23 +0100 Subject: [PATCH] Improve manual --- manual/debug.wiki | 24 ++++++++++++------------ manual/environment-variable.wiki | 8 ++++---- manual/overview.wiki | 7 +++++-- manual/wasm_overview.wiki | 2 +- 4 files changed, 22 insertions(+), 19 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/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/overview.wiki b/manual/overview.wiki index 6dce5ca01f..d9eb38742e 100644 --- a/manual/overview.wiki +++ b/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 <>. + 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 diff --git a/manual/wasm_overview.wiki b/manual/wasm_overview.wiki index 2a7653bfec..da74c75270 100644 --- a/manual/wasm_overview.wiki +++ b/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 <> are compatible with this compiler. +The compiler is provided by the wasm_of_ocaml-compiler package. The <> are compatible with this compiler. == Installation