Changing the Markdown files in doc/pages to be amenable for use on OCaml.org

[sabine]

This patch does two one thing:

• Modify the documentation to be integrated into ocaml.org for Retiring opam2web in favor of ocaml.org ocaml-opam/opam2web#227 by adding YAML headers and removing the menu
• Line editing on the documentation (this is work in progress - more is coming, unless there's a good reason to stop)

Note:

• unless we can find another place to host the man pages long-term, I see no other viable option than to remove the references to the man pages. Maybe we do want to look for a place where they can be hosted long-term?
• Hosting the markdown on ocaml.org is an interim solution only. When odoc is able to build the opam manual, ocaml.org will pull the opam manuals from docs-data.ocaml.org (the package documentation server).
• sibling patch that generates markdown for the man-pages: Convert man pages to Markdown with YAML header #5594
• corresponding work-in-progress patch on ocaml.org: Move opam docs from opam.ocaml.org ocaml.org#1367

[sabine]

Thanks @rjbou. Indeed, this will change before it needs a review.

[rjbou]

On the man pages, is it possible to generate them and refer to them as doc md files ?

[rjbou]

On line editing, please update :D Documentation needs an update (for example, the Upgrade guide is quite obsolete on New features section). It is nice to have an external view, it helps to have something more understandable.

Is it possible to have different PRs, one for documentation update and the other that moves files around and update them (eg the header) to make it ocaml.org doc compliant ?

[sabine]

Ah, certainly, if the man pages can be turned into .md instead of HTML, that would work!

When the line editing is finished, I'll separate into two PRs, line editing to merge first, then this one.

[rjbou]

Perfect! Thanks!