Doc: document findlib interaction

[hhugo]

cc @dbuenzli, in case you want to review

[dbuenzli]

Thanks. The convention and mechanics looks good to me. I left a few comments.

[dbuenzli]

One more thing. In case you have a single .js file I think it would be maybe a good idea to suggest calling it runtime.js by convention (or something else but that's what you did in ptime).

[hhugo]

One more thing. In case you have a single .js file I think it would be maybe a good idea to suggest calling it runtime.js by convention (or something else but that's what you did in ptime).

added

[dbuenzli]

I had a quick look at the changes it looks mostly ok to me. Thank you.

If you really want to polish I would rather call the runtime-files page, "How to compile a program" and make it centered on that but I guess most people are not interested in the base invocations and the current organisation is enough for build system fiddlers.

Btw. maybe I dreamt but at some point I thought I had bought you into converting the docs to .mld files :-) I still think it would be worthwhile, the docs should show up on ocaml.org (and in odig doc js-of-ocaml-compiler if you are a local documentation addict).

[hhugo]

If there's no distinction then indeed it may be worth deprecating --toplevel and instruct people to use --dynlink when they want to compile a toplevel or use the Dynlink library (it's not entirely unnatural IIRC ocamlnat uses Dynlink).

I was more tempted to deprecated --dynlink and ask people to use --toplevel. I cannot come up with a good argument either way.

[dbuenzli]

I cannot come up with a good argument either way.

Well you can use Dynlink without using a toplevel no ?

[hhugo]

I cannot come up with a good argument either way.

Well you can use Dynlink without using a toplevel no ?

And you can use the toplevel without dynlink.

In theory, you're not allowed to use Dynlink inside the toplevel.

Dynlink can only be used if Js_of_ocaml_toplevel is initialized.

[dbuenzli]

And you can use the toplevel without dynlink.

Somehow a #load directive is equivalent to dynlinking a module (I remember thinking when I was working on the library linking proposal that a lot of the bytecode toplevel loading business could likely be made to reuse Dynlink, and IIRC ocamlnat does actually use it).

Dynlink can only be used if Js_of_ocaml_toplevel is initialized.

That looks like a jsoo implementation detail. For me toplevel is really the interactive behaviour so it feels a bit strange to me to use the --toplevel flag if I just want to be able to dynamically load bytecode.

But in any case what do these flags do ? What do they enable ? And do they actually do exactly the same thing ?

Based on these answers maybe we can find a new entirely different technical name and deprecate the other twos if you find neither suitable.

[hhugo]

If you really want to polish I would rather call the runtime-files page, "How to compile a program" and make it centered on that but I guess most people are not interested in the base invocations and the current organisation is enough for build system fiddlers.

I'd like to restructure the entire doc eventually but will leave the doc as is for now

Btw. maybe I dreamt but at some point I thought I had bought you into converting the docs to .mld files :-) I still think it would be worthwhile, the docs should show up on ocaml.org (and in odig doc js-of-ocaml-compiler if you are a local documentation addict).

I'd like some kind of agreement with other ocsigen devs before. Mostly concerned about the ocsigen.org website.

[hhugo]

That looks like a jsoo implementation detail. For me toplevel is really the interactive behaviour so it feels a bit strange to me to use the --toplevel flag if I just want to be able to dynamically load bytecode.

But in any case what do these flags do ? What do they enable ? And do they actually do exactly the same thing ?

Based on these answers maybe we can find a new entirely different technical name and deprecate the other twos if you find neither suitable.

Let's move that discussion to #1324