From 74f812c7d9ab87cc540083921c326f2d45359a59 Mon Sep 17 00:00:00 2001
From: Benjamin Sigonneau <benjamin.sigonneau@sandboxaq.com>
Date: Thu, 7 Nov 2024 15:33:00 +0100
Subject: [PATCH] Move to howto, add more explanations, fix typos

Signed-off-by: Benjamin Sigonneau <benjamin.sigonneau@sandboxaq.com>
---
 doc/advanced/index.rst                       |  1 -
 doc/advanced/override-default-entrypoint.rst | 41 ----------------
 doc/howto/index.rst                          |  1 +
 doc/howto/override-default-entrypoint.rst    | 51 ++++++++++++++++++++
 4 files changed, 52 insertions(+), 42 deletions(-)
 delete mode 100644 doc/advanced/override-default-entrypoint.rst
 create mode 100644 doc/howto/override-default-entrypoint.rst

diff --git a/doc/advanced/index.rst b/doc/advanced/index.rst
index 50ede4bb709..ddc575b1f9a 100644
--- a/doc/advanced/index.rst
+++ b/doc/advanced/index.rst
@@ -12,4 +12,3 @@ These documents describe some advanced or very specific features of Dune.
    ocaml-syntax
    variables-artifacts
    custom-cmxs
-   override-default-entrypoint
diff --git a/doc/advanced/override-default-entrypoint.rst b/doc/advanced/override-default-entrypoint.rst
deleted file mode 100644
index 4600c4c0c87..00000000000
--- a/doc/advanced/override-default-entrypoint.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-Overriding the default entry point
-----------------------------------
-
-In some cases, it may be necessary to override the default main entry point of
-an Ocaml program. For example, this is the case if you want to let your program
-handle argument wildcards expansion on Windows.
-
-Fortunately, the ``foreign_stubs`` stanza can be leveraged for that usage.
-
-Let's consider a ``hello.ml`` file and the following ``main.c`` file that
-redefines the entry point:
-
-.. code:: C
-
-    #include <stdio.h>
-
-    #include "caml/mlvalues.h"
-    #include "caml/callback.h"
-
-    CAMLextern void caml_do_exit (int);
-
-    int main_os(int argc, char_os **argv)
-    {
-        printf("Do stuff before calling the actual Ocaml program\n");
-
-        caml_main(argv);
-        caml_do_exit(0);
-        return 0;
-    }
-
-
-Then the following will compile the ``hello.exe`` binary and make it use the entry
-point defined in ``main.c``:
-
-.. code:: dune
-
-    (executable
-     (name hello)
-     (foreign_stubs
-      (language c)
-      (names main)))
diff --git a/doc/howto/index.rst b/doc/howto/index.rst
index 91362367a07..164a6432d9e 100644
--- a/doc/howto/index.rst
+++ b/doc/howto/index.rst
@@ -21,3 +21,4 @@ These guides will help you use Dune's features in your project.
    bundle
    toplevel
    rule-generation
+   override-default-entrypoint
diff --git a/doc/howto/override-default-entrypoint.rst b/doc/howto/override-default-entrypoint.rst
new file mode 100644
index 00000000000..e6036211fea
--- /dev/null
+++ b/doc/howto/override-default-entrypoint.rst
@@ -0,0 +1,51 @@
+How to override the default entry point
+---------------------------------------
+
+In some cases, it may be necessary to override the default main entry point of
+an OCaml program. For example, this is the case if you want to let your program
+handle argument wildcards expansion on Windows.
+
+Let's consider a trivial "Hello world" program, contained in a ``hello.ml``
+file:
+
+.. code:: ocaml
+
+    let () = print_endline "Hello, world!"
+
+The default entry point is a C ``main`` function, originally defined in
+`runtime/main.c <https://github.com/ocaml/ocaml/blob/trunk/runtime/main.c>`_. It
+can be overriden by defining a ``main`` function that will at some point call
+the OCaml runtime. Let's write such a minimal example in a ``main.c`` file:
+
+.. code:: C
+
+    #include <stdio.h>
+
+    #include "caml/misc.h"
+    #include "caml/mlvalues.h"
+    #include "caml/sys.h"
+    #include "caml/callback.h"
+
+    /* This is the new entry point */
+    int main(int argc, char_os **argv)
+    {
+        /* Here, we just print a statement */
+        printf("Do stuff before calling the OCaml runtime\n");
+
+        /* Before calling the OCaml runtime */
+        caml_main(argv);
+        caml_do_exit(0);
+        return 0;
+    }
+
+The :doc:`foreign_stubs </reference/foreign-stubs>` stanza can be leveraged to
+compile and link our OCaml program with the new C entry point defined in
+``main.c``:
+
+.. code:: dune
+
+    (executable
+     (name hello)
+     (foreign_stubs
+      (language c)
+      (names main)))