README: recommend using Dune OCaml syntax

Resolves #294.

[skip ci]

README.md

@@ -51,7 +51,8 @@ details of how it is generated are in the [worked example](#Example).
 Refer to [**aantron/bisect-starter-dune**][dune-repo], which produces
 [this report][dune-report].
 
-1. [Depend on Bisect_ppx in your `opam` file](https://github.com/aantron/bisect-starter-dune/blob/master/bisect-starter-dune.opam#L10):
+1. [Depend on Bisect_ppx](https://github.com/aantron/bisect-starter-dune/blob/master/bisect-starter-dune.opam#L10)
+   in your `opam` file:
 
     ```
     depends: [
@@ -60,52 +61,69 @@ Refer to [**aantron/bisect-starter-dune**][dune-repo], which produces
     ```
 
 2. [Mark the code under test for preprocessing by
-   `bisect_ppx`](https://github.com/aantron/bisect-starter-dune/blob/master/dune#L4)
-   (but don't preprocess the tester itself):
+   `bisect_ppx`](https://github.com/aantron/bisect-starter-dune/blob/master/dune#L4) in your `dune` file:
+
+    ```ocaml
+    (* -*- tuareg -*- *)
+
+    let preprocess =
+      match Sys.getenv "BISECT_ENABLE" with
+      | "yes" -> "(preprocess (pps bisect_ppx))"
+      | _ | exception _ -> ""
+
+    let () = Jbuild_plugin.V1.send @@ {|
 
-    ```scheme
     (library
      (public_name my_lib)
-     (preprocess (pps bisect_ppx --conditional)))
+     |} ^ preprocess ^ {|)
+
+    |}
     ```
 
+    This uses Dune's
+    [OCaml syntax](https://dune.readthedocs.io/en/stable/advanced-topics.html#ocaml-syntax)
+    to completely take `bisect_ppx` out as a dependency, except when the
+    environment variable `BISECT_ENABLE` is set to `yes`. This is so that you
+    can release your project without it depending on `bisect_ppx` for non-`dev`
+    builds.
+
+    After [ocaml/dune#57][dune-57], Dune will have a lighter-weight built-in
+    syntax for conditional preprocessing.
+
+    For now, the OCaml syntax can be understood as prepending a few lines of
+    OCaml code to a regular `dune` file, and then replacing the `preprocess`
+    stanza with `|} ^ preprocess ^ {|`. See
+    [here](https://github.com/aantron/bisect-starter-dune/commit/24ffb2153d3c42ff166c78a9f55095bd12f10f4e#diff-cabdb1014252d39ac018f447e7d5fbc2)
+    for a neat summary of the patch.
+
 3. Build and run your test binary. In addition to testing your code, when
    exiting, it will write one or more files with names like
-   `bisect0123456789.coverage`.
+   `bisect0123456789.coverage`:
 
     ```
     BISECT_ENABLE=yes dune runtest --force
     ```
 
-    `BISECT_ENABLE=yes` turns on instrumentation. If you run `dune runtest` (or
-    any other build) without it, Bisect_ppx will pass the code through
-    unchanged (i.e., without adding instrumentation).
+    The `--force` flag forces all your tests to run, which is needed for an
+    accurate coverage report.
+
+    To run tests without coverage, do
 
-    At the moment, if you switch between building with and without
-    instrumentation, you have to run `dune clean` in between the builds.
+    ```
+    dune runtest
+    ```
 
 4. Generate the [coverage report][dune-report] in `_coverage/index.html`:
 
     ```
     bisect-ppx-report html
     ```
 
-4. For releasing, you have two options:
+    You can also generate a short summary in the terminal:
 
-    - If you don't want a dependency on package `bisect_ppx`, you have to
-      manually remove `(preprocess (pps bisect_ppx))` from your `dune` files.
-    - If a dependency on Bisect_ppx is okay, you don't have to do anything. A
-      regular build command, without `BISECT_ENABLE=yes` will produce
-      uninstrumented code:
-
-      ```
-      ["dune" "build" "-p" name "-j" $jobs]
-      ```
-
-    This choice is due to a limitation of Dune that we hope to address in
-    [ocaml/dune#57][dune-57]. After that, `BISECT_ENABLE=yes` won't be
-    necessary anymore, and you will be able to release without a dependency on
-    Bisect_ppx, without having to edit any files.
+    ```
+    bisect-ppx-report summarys
+    ```
 
 [dune-repo]: https://github.com/aantron/bisect-starter-dune#readme
 [dune-report]: https://aantron.github.io/bisect-starter-dune/