Address review comments

Signed-off-by: Sudha Parimala <sudharg247@gmail.com>

Author: Sudha247

doc/tutorials/dune-package-management/oxcaml.md

@@ -1,37 +1,42 @@
-# Example: Setting up an OxCaml project
+# Setting up an OxCaml project
 
-As an example to adding custom repositories and pinning projects, let's look at
-setting up a basic OxCaml project. [OxCaml](https://oxcaml.org/) is a compiler
-branch with fast moving set of extenstions to OCaml. Some tweaks are required to
-set up an OxCaml project with dune package management.
+As an example of how to add custom repositories and pin dependencies in projects
+using `dune pkg`, let's look at setting up a basic OxCaml project.
+[OxCaml](https://oxcaml.org/) is a compiler branch with fast moving set of
+extensions to OCaml. Some tweaks are required to set up a project that compiles
+with OxCaml when using dune package management.
 
-## Setting up the workspace
+## Setting up the `dune-workspace`
 
-OxCaml has a custom `opam-repository` that we need in order to pull in its
-dependencies. This is specified in the `dune-workspace`.
+OxCaml has a custom `opam-repository` that provides compatible dependencies.
+This is specified in the `dune-workspace`.
 
-::::{dropdown} `dune-workspace`
-:icon: file-code
+```{code-block} dune
+(lang dune 3.20)
 
-:::{literalinclude} oxcaml/dune-workspace
-:language: dune
-:emphasize-lines: 3-5
-:::
+(pkg enabled)
 
-::::
+(repository
+ (name oxcaml)
+ (url git+https://github.com/oxcaml/opam-repository))
+
+(lock_dir
+ (repositories overlay oxcaml upstream))
+```
 
 In the `dune-project`, we also need to add a constraint to depend on the OxCaml
 compiler. Otherwise, the solver may pick up the latest upstream compiler, which
 does not support the OxCaml extensions.
 
-::::{dropdown} `dune-project`
-:icon: file-code
-
-:::{literalinclude} oxcaml/dune-project
-:language: dune
-:::
+```{code-block} dune
+(lang dune 3.20)
 
-::::
+(package
+ (name hello-oxcaml)
+ (depends
+  (ocaml-variants
+   (= 5.2.0+ox))))
+```
 
 Let's add a test program that uses OxCaml syntax.
 
@@ -46,35 +51,66 @@ Let's add a test program that uses OxCaml syntax.
 
 And to build it, we add a `dune` file.
 
-::::{dropdown} `dune`
-:icon: file-code
-
-:::{literalinclude} oxcaml/dune
-:language: dune
-:::
-
-::::
+```{code-block} dune
+(executable
+ (public_name main))
+```
 
 ## Building the project
 
-As usual, let's lock the dependencies and build the project with:
+As usual, let's build the project with:
 
 ```
-$ dune pkg lock
-Solution for dune.lock:                                                        
-- conf-autoconf.0.2
-- conf-which.1
-- ocaml-variants.5.2.0+ox
-
-$ dune build && dune exec ./main.exe
+$ dune exec ./main.exe
 ...
 43
 ```
-We have successfully built the project with the OxCaml compiler.
+We have successfully built the project with the OxCaml compiler and run the executable.
 
 ## Developer tools
 
 Note that OxCaml provides its own forks of the developer tools
 `ocaml-lsp-server`, `ocamlformat`, etc. Make sure to include constraints for the
 tools in the `dune-workspace` if you intend to use them for your development
 workflows.
+
+For `ocamlformat` it would look something like this:
+
+```{code-block} dune
+
+(lang dune 3.20)
+
+(pkg enabled)
+
+(repository
+ (name oxcaml)
+ (url "git+https://github.com/oxcaml/opam-repository"))
+
+(pin
+ (name ocamlbuild)
+ (url "git+https://github.com/Sudha247/ocamlbuild#oxcaml+dune")
+ (package
+   (name ocamlbuild)
+   (version 0.15.0+ox)))
+
+(pin
+ (name odoc-parser)
+ (url "git+https://github.com/Sudha247/odoc#replace-symlinks")
+ (package
+   (name odoc-parser)
+   (version 3.1.0+ox)))
+
+(lock_dir
+ (path "dune.lock")
+ (repositories :standard oxcaml))
+
+(lock_dir
+ (path "dev-tools.locks/ocamlformat")
+ (pins ocamlbuild)
+ (constraints
+   (ocaml-lsp-server (= 1.19.0+ox))
+   (ocaml-variants (= 5.2.0+ox)))
+ (repositories overlay oxcaml upstream))
+```
+
+Observe that this includes pins to dependencies `ocamlbuild` and `odoc-parser` as they are required by the OxCaml version of `ocamlformat`.

doc/tutorials/dune-package-management/oxcaml/dune

@@ -1,4 +1,5 @@
 let () =
+  (* The `local_` keyword requires OxCaml *)
   let local_ i = 42 in
   let j = i + 1 in
   print_endline (Printf.sprintf "%d" j)