From 9d680c43a29404e06e8c7cb39d30604e4e21fa9d Mon Sep 17 00:00:00 2001
From: Etienne Millon <me@emillon.org>
Date: Thu, 11 Jul 2024 17:47:54 +0200
Subject: [PATCH] split extra-objects

---
 doc/reference/extra-objects.rst | 29 +++++++++++++++++++++++++++++
 doc/reference/foreign.rst       | 29 +----------------------------
 doc/reference/index.rst         |  1 +
 3 files changed, 31 insertions(+), 28 deletions(-)
 create mode 100644 doc/reference/extra-objects.rst

diff --git a/doc/reference/extra-objects.rst b/doc/reference/extra-objects.rst
new file mode 100644
index 000000000000..1076ec065a12
--- /dev/null
+++ b/doc/reference/extra-objects.rst
@@ -0,0 +1,29 @@
+Extra Objects
+-------------
+
+It's possible to specify native object files to be packaged with OCaml
+libraries or linked into OCaml executables. Do this by using the
+``extra_objects`` field of the ``library`` or ``executable`` stanzas.
+For example:
+
+.. code:: dune
+
+    (executable
+     (public_name main)
+     (extra_objects foo bar))
+
+    (rule
+     (targets foo.o bar.o)
+     (deps foo.c bar.c)
+     (action (run ocamlopt %{deps})))
+
+This example builds an executable which is linked against a pair of native
+object files, ``foo.o`` and ``bar.o``. The ``extra_objects`` field takes a
+list of object names, which correspond to the object file names with their path
+and extension omitted.
+
+In this example, the sources corresponding to the objects (``foo.c`` and
+``bar.c``)  are assumed to be present in the same directory as the OCaml source
+code, and a custom ``rule`` is used to compile the C source code into object
+files using ``ocamlopt``. This is not necessary; one can instead compile foreign
+object files manually and place them next to the OCaml source code.
diff --git a/doc/reference/foreign.rst b/doc/reference/foreign.rst
index 426fe1d5fe14..3d132bb99853 100644
--- a/doc/reference/foreign.rst
+++ b/doc/reference/foreign.rst
@@ -16,37 +16,10 @@ Foreign Archives
 
 See :doc:`foreign-archives`.
 
-.. _extra-objects:
-
 Extra Objects
 -------------
 
-It's possible to specify native object files to be packaged with OCaml
-libraries or linked into OCaml executables. Do this by using the
-``extra_objects`` field of the ``library`` or ``executable`` stanzas.
-For example:
-
-.. code:: dune
-
-    (executable
-     (public_name main)
-     (extra_objects foo bar))
-
-    (rule
-     (targets foo.o bar.o)
-     (deps foo.c bar.c)
-     (action (run ocamlopt %{deps})))
-
-This example builds an executable which is linked against a pair of native
-object files, ``foo.o`` and ``bar.o``. The ``extra_objects`` field takes a
-list of object names, which correspond to the object file names with their path
-and extension omitted.
-
-In this example, the sources corresponding to the objects (``foo.c`` and
-``bar.c``)  are assumed to be present in the same directory as the OCaml source
-code, and a custom ``rule`` is used to compile the C source code into object
-files using ``ocamlopt``. This is not necessary; one can instead compile foreign
-object files manually and place them next to the OCaml source code.
+See :doc:`extra-objects`.
 
 .. _flags-flow:
 
diff --git a/doc/reference/index.rst b/doc/reference/index.rst
index d779e9fb13a8..dc2587a3accd 100644
--- a/doc/reference/index.rst
+++ b/doc/reference/index.rst
@@ -49,6 +49,7 @@ These documents specify the various features and languages present in Dune.
        foreign
        foreign-stubs
        foreign-archives
+       extra-objects
 
   .. grid-item::