diml/lambda-term — pull request #6 by avysk (2014-05-08 14:56:21+00:00)
Title: Fix doc build

Hello,

I've noticed that lambda-term documentation is corrupted in some places. So I started some investigation and discovered that OASIS filters every mli file through camlp4o, and camlp4o messes with comments, losing some and putting some in different place (see https://github.com/ocaml/camlp4/issues/6). Of course, after that ocamldoc doesn't build proper documentation.

So I've added one flag to configure: uglydocworkaround (off by default). If it is on, then doc-building phase of OASIS has PostCommand, which basically rebuilds the documentation again. Unfortunately, OASIS insists on pushing -syntax camlp4o in every ocamldoc call, so here is the place where ugliness comes: I've added in PostCommand '-pp cat' which asks ocamldoc to do trivial pre-processing. This overrides -syntax given by OASIS and builds proper documentation from interface files.

I had to do also a couple of small related changes:
(1) myocamlbuild.ml and _tags in the root were interfering with ocamlbuild call in PostCommand, so I've replaced them with a small change in _oasis (that's commit cc42a4f, you may want to consider it even if you don't want this whole ugly thing).
(2) LTerm_widget had no module docstring, so ocamldoc was taking the first section header and duplicating it as module docstring (commit 2b0e736, should be good thing to have by itself.)

The problem in generated API docs this ugly thing fixes (on my machine) are:
- lost class docstring in LTerm_widget.frame-c.html
- lost headers "Labels" and "Buttons" in LTerm_widget.html
- lost docstring for classes label and frame in LTerm_widget.html
- lost class docstring in LTerm_widget.label-c.html
- duplicated "The children of the widget." in LTerm_widget.t-c.html (first one appended to class t documentation)
- missing frame and label descriptions in index_classes.html

Example:

Broken:
![screen shot 2014-05-08 at 17 49 35](https://cloud.githubusercontent.com/assets/130091/2916901/30013f4a-d6c0-11e3-87d0-a23187b2bc12.png)

Fixed:
![screen shot 2014-05-08 at 17 49 49](https://cloud.githubusercontent.com/assets/130091/2916899/2b6d018a-d6c0-11e3-8d61-b7561738fafb.png)

(Disclaimer: I've tested this only on Mac OS with ocaml 4.01.0 & co. installed with latest opam. Also this would work only on Unices, because of usage of cat, ln and rm)

I would understand perfectly if you don't want this hack. I hope that commit cc42a4f may turn out useful even then, though.