profiles, contexts, build-dirs, WTF ?

[nobrowser]

This will be a bit of a rant, so I apologize in advance. It will also be a "broken record" to those who read caml-list. But maybe this is where I should have brought it up in the first place.

The dune manual is terrible . It looks like a compendium of code comments from all the source modules, with a sprinkling of syntax examples related to each of the features; but completely lacks any "big picture" story, ie. what is each feature supposed to do for me? I see a concept like build context mentioned, without explanation; I hopefully search for other occurences of it, dreaming of finding the explanation there; oops, no luck either.

I can get a bit of the way simply copying the example syntax from the Hello World chapter, but then I want to do something just a little bit fancy, like optionally building tests with bisect_ppx (Issue #57 ), and I'm out to sea. @diml suggested using contexts for that; but I don't know what to make of his suggestion because I don't understand contexts. What good does it do to modify the settings for the default context when I want the normal way (without bisect_ppx) to be the default? And even more basic: assuming I'm willing to invert the default/non-default labels, how do I actually make a non-default context to be used? Maybe these questions have answers, but again, there is no way for me to get them by reading the manual.

I think the doc should be rewritten from scratch, after someone who understands the features and concepts (probably a Jane Street person) carefully thinks about them and about the best way to explain them.

Again, sorry about the rant. :-(

[rgrinberg]

This will be a bit of a rant, so I apologize in advance. It will also be a "broken record" to those who read caml-list. But maybe this is where I should have brought it up in the first place.

Indeed. Your bad tone is what stopped me from responding to you there.

As for the rest, we know the documentation is flawed in some parts, but there's plenty of good parts as well. What's preventing us from fixing it aren't incoherent rants from users, but the lack of resources.

Your issues with bisect_ppx stem from the fact that dune simply does not support it well at the moment.

It would be helpful if you point out some well written documentation (preferably written by you) so that I have a better idea of what you expect.

To go help fo using dune, I suggest asking on discuss.ocaml.org. If you find that there's not enough responses, try fixing your attitude.

[nobrowser]

Your issues with bisect_ppx stem from the fact that dune simply does not support it well at the moment.

And I thought that I did a passable job of showing this was not so:

1. Adding specific support just for bisect_ppx would be a bad idea

2. OTOH, given a working and documented generic mechanism (like maybe contexts), I could figure out how to integrate it myself, and so could anyone else.

It would be helpful if you point out some well written documentation

To stay with build systems, I like the scons documentation at https://scons.org/documentation.html. Note that there is both a manual and a design paper.

I suggest asking on discuss.ocaml.org

I'm afraid that when a web forum becomes the main communication platform for a community, I disengage.