From cf2f6c03bad1a0aa24268858d0a57aed30bd45ff Mon Sep 17 00:00:00 2001
From: Jeremie Dimino <jeremie@dimino.org>
Date: Sat, 3 Mar 2018 10:34:41 +0000
Subject: [PATCH] Update README

---
 README.md | 61 +++++++------------------------------------------------
 1 file changed, 7 insertions(+), 54 deletions(-)

diff --git a/README.md b/README.md
index e6ad4355..a66a5659 100644
--- a/README.md
+++ b/README.md
@@ -193,64 +193,17 @@ to find different approaches to constructing build rules.
 Known issues
 ------------
 
-### Optional libraries inside a multilib directory
-
-https://github.com/ocaml/dune/issues/51
-
-If a directory contains several libraries and some are marked as
-optional (by adding `(optional)` in the `(library ...)` stanza), then
-the dependencies will still be required to perform the build.
-
-This could be sorted out with some refactoring, but there is a simple
-workaround, so it is low-priority.
-
-#### Workaround
-
-Put each optional library in a separate directory.
-
 ### mli only modules
 
-https://github.com/ocaml/dune/issues/9
+These are supported, however using them might cause make it impossible
+for non-jbuilder users to use your library. We tried to use them for
+some internal module generated by Jbuilder and it broke the build of
+projects not using Jbuilder:
 
-Due to the low-level details of OCaml compilation, it is currently
-possible to write a module that has only a `.mli` and no `.ml`
-file. This works as long as the mli contains only type declarations.
+https://github.com/ocaml/dune/issues/567
 
-This is not a properly supported feature of the compiler, and in
-particular it is not possible to alias such modules or use them as the
-argument of a functor. Moreover, if you do write a value declaration,
-or even just define an exception in the `.mli`, then you won't get an
-error until the point where you link an executable using this module.
-
-For these reason, mli only modules are not recommended by Jbuilder
-until the compiler support them properly.
-
-#### Workaround
-
-As long as a module type contains no value declaration, it is possible
-to turn in to an implementation by using a recursive module:
-
-```ocaml
-module rec M : sig
-  type t = A | B
-end = M
-include M
-```
-
-So if you have a module without a `.ml` file, simply generate a `.ml`
-from the `.mli` using this trick. For instance you can add the
-following rule into your jbuild file:
-
-```scheme
-(rule (with-output-to foo.ml
-       (progn
-        (echo "module rec HACK : sig\n")
-        (cat foo.mli)
-        (echo "\nend = HACK\ninclude HACK\n"))))
-```
-
-In fact, jbuilder will automatically add this rule if you have a
-module without implementation. However it will print a warning.
+So, while they are supported, you should be careful where you use
+them. Using a `.ml` only module is still preferable.
 
 Implementation details
 ----------------------