[dune] [doc] Some tweaks to doc + per user flags.

1 files changed, 25 insertions, 23 deletions

diff --git a/dev/doc/build-system.dune.md b/dev/doc/build-system.dune.md
index 36d5e5841b..7349360be8 100644
--- a/dev/doc/build-system.dune.md
+++ b/dev/doc/build-system.dune.md
@@ -3,11 +3,15 @@ Dune-based build system. If you want to enhance the build system
 itself (or are curious about its implementation details), see
 build-system.dev.txt, and in particular its initial HISTORY section.
 
-Quick Start
-===========
+About Dune
+==========
+
+Coq can now be built using [Dune](https://github.com/ocaml/dune).
+
+## Quick Start
 
 You need Dune >= 1.2.1 ; just type `dune build` to build the base Coq
-libraries. No `./configure` step is needed.
+libraries. No call to `./configure` is needed.
 
 Dune will get confused if it finds leftovers of in-tree compilation,
 so please be sure your tree is clean from objects files generated by
@@ -18,31 +22,26 @@ call `make -f Makefile.dune voboot`. It is usually enough to do that
 once per-session.
 
 More helper targets are availabe in `Makefile.dune`, `make -f
-Makefile.dune` will display help.
+Makefile.dune` will display some help.
 
-Dune
-====
+Dune places build artifacts in a separate directory `_build`; it will
+also generate an `.install` file so files can be properly installed by
+package managers.
 
-Coq can now be built using
-[Dune](https://github.com/ocaml/dune). Contrary to other systems,
-Dune, doesn't use a global`makefile` but local build files named
-`dune` that are later composed to form a global build.
+Contrary to other systems, Dune doesn't use a global `Makefile` but
+local build files named `dune` that are later composed to form a
+global build.
 
 As a developer, Dune should take care of all OCaml-related build tasks
-including library management, merlin files, and link order. You are
+including library management, merlin files, and linking order. You are
 are not supposed to modify the `dune` files unless you are adding a
 new binary, library, or plugin.
 
-The current Dune setup also doesn't require a call to `configure`. The
-auto-generated configuration files are properly included in the
-dependency graph so it will be automatically generated by Dune with
-reasonable developer defaults. You can still override the defaults by
-manually calling `./configure`, but note that some configure options
-such as install paths are not used by Dune.
+## Per-User Custom Settings
 
-Dune uses a separate directory `_build` to store build artifacts; it
-will generate an `.install` file so artifacts in the build can be
-properly installed by package managers.
+Dune will read the file `~/.config/dune/config`; see `man
+dune-config`. Among others, you can set in this file the custom number
+of build threads `(jobs N)` and display options `(display _mode_)`.
 
 ## Targets
 
@@ -53,8 +52,10 @@ project, creating an "install" overlay in `_build/install/default`.
 You can build some other target by doing `dune build $TARGET`.
 
 In order to build a single package, you can do `dune build
-$PACKAGE.install`. Dune also provides targets for documentation and
-testing, see below.
+$PACKAGE.install`.
+
+Dune also provides targets for documentation, testing, and release
+builds, please see below.
 
 ## Developer shell
 
@@ -83,7 +84,8 @@ current Coq source tree contains two packages [Coq and CoqIDE], and in
 the OPAM CoqIDE package we don't want to build CoqIDE against the
 local copy of Coq. For this purpose, Dune supports the `-p` option, so
 `dune build -p coqide` will build CoqIDE against the system-installed
-version of Coq libs.
+version of Coq libs, and use a "release" profile that for example
+enables stronger compiler optimizations.
 
 ## Stanzas