Refresh the building section in the Learn area

[gpetiot]

From users feedback I think we should revisit the "building" section, at the moment there is:

• Getting started > Getting up and running with OCaml:
  • mentioning ocamlc and ocamlopt first
  • mentioning dune as part of the ocaml-platform
  • "starting a new project": dune init, dune build, dune exec
• Getting started > A First Hour with OCaml:
  • "Compiling OCaml programs": only mentioning ocamlopt
• Language > Modules:
  • Automatised Compilation: auto compilation (dune) VS manual compilation (ocamlopt)
• Tutorials > Command-line arguments:
  • using ocamlopt
• Tutorials > File manipulation
  • using ocamlopt
• Tutorials > Calling C libraries:
  • I don't have any experience with that but I think we should link https://dune.readthedocs.io/en/latest/foreign-code.html
• Tutorials > Calling Fortran libraries:
  • using ocamlc, the dune part is probably applicable like for C?
• Guides > Compiling OCaml projects:
  • mentions ocamlc, ocamlopt, ocamlfind and dune, as well as pre-dune build systems
• Guides > Preprocessors and PPXs:
  • preprocessing with ocamlc and ocamlopt
  • preprocessing with dune

I think we should move the "Compiling OCaml projects" page under the section Getting Started, and rename it something like "Building a project with dune", located after "Get up and running" (I think this one should stop after getting everything installed and configured). This page would present the basic usage of dune: init, build, exec, and stress that this is the standard and recommended way of building a project. ocamlfind should be mentioned in the same way after opam.

Every following page should only use dune.

We could add a "Manual compilation" page presenting ocamlc and ocamlopt in the "advanced" section (Guides probably? but I am in favor of creating a new "Advanced usage" section anyway).

What do you think?

[cuihtlauac]

Thanks @gpetiot, that sounds great to me. Use only dune everywhere but in a dedicated section for low-level/manual compilation. Looks so obvious makes me feel ashamed we haven't thought about that earlier. Great to have new eyes.

I also support moving/sorting things around.

[sabine]

I would love to have a proper documentation for how to set up an OCaml project and how to build and run programs. This includes how to work with opam switches.

For some tutorials it may make more sense for them to suggest using an interactive context (REPL or playground), for other tutorials, the recommended workflow will be to set up a project and work on that.

What if we had pages that explain the different workflow/setups (interactive vs project-based), so that the tutorials can reference either the interactive workflow/setup or the project-based workflow/setup. :thinking:

[sabine]

This issue is related to https://github.com/ocaml/ocaml.org/issues/956.