doc: split foreign.rst

[emillon]

This splits the monolithic foreign.rst into 4 pages:

• foreign_stubs
• foreign_archives (and foreign_library)
• extra_objects
• flags in foreign code

This is given its own toc in the index, and some xrefs are added.

[emillon]

@Leonidas-from-XIV the only content changes are the added xrefs in the flags document and the removed intro in the now-deleted document.

[Leonidas-from-XIV]

I am not sure splitting the document into multiple pages is an improvement since I liked that the topic of dealing with foreign code was fairly contained on one page, but will defer to your judgement on that.

Thanks for specifying the content changes, that has made it significantly nicer to review! I wrote some comments as I looked through the newly split pages though.

[emillon]

I am not sure splitting the document into multiple pages is an improvement since I liked that the topic of dealing with foreign code was fairly contained on one page, but will defer to your judgement on that.

Thanks for the feedback, there's a balance to find here:

• on the one hand, the monolithic page was the only place where foreign_stubs (and friends) were documented, and they contain unrelated documentation (if you're looking for the syntax of (foreign_stubs), it's not likely you're interested in knowing about the history of use_standard_c_and_cxx_flags
• on the other hand, the "here are all your options regarding foreign code in Dune" aspect is now lost.

What I suggest is creating an issue about creating the following doc: an how-to guide which would be "how to use non-ocaml code in my project", with sections corresponding to foreign_stubs (you're in control of this C code) and foreign_archives with optionally foreign_library (this is already built somewhere / there's another build system in there). How does that sound?