~Reorder options,~ fix brew instructions, spelling

[johnwhitington]

This PR reflects three lessons learned when writing the new ocaml.org "Up and Running" guide ocaml/ocaml.org#1165 :

1. Having the binary distribution at the top of this page, when it is not the recommended installation mechanism for most users, is confusing.
2. Brew will shortly be updated opam: depend on gpatch Homebrew/homebrew-core#64301 to make opam depend on gpatch, thus removing this instruction from the OS X instructions.
3. OSX is now spelled macOS

EDIT @rjbou: split the PR, reordering question that was blocking the PR is meant to go to another PR

[rjbou]

Thanks for this PR!
I'm wondering, why binary install is not the recommended installation mechanism ?

[johnwhitington]

Not my area of expertise I'm afraid. The comments from @Octachron on the linked thread are on the mismatch between the idea of what is recommended, and its position on the page, not the core issue of what is recommended.

I suppose it is because your distribution's package manager can keep opam up to date automatically?

[johnwhitington]

The patch to Homebrew has now landed, by the way.

[rjbou]

It's the first recommended way because it is always the last version that can be retrieved using it, distributions have their own delays to propagate a new version (from instantly to several months). It one of the reason why I've added repology badges, to know which version is available at the moment for the distro.
@AltGr @dra27 any thought on that ?

[rjbou]

Except point 1. that is discussed, 2. & 3. are lgtm!

[avsm]

Advantages of native distros are that they include all the right patches and dependencies to work. E.g. on macOS, gpatch will be installed. Also the binary installer does not include opam-install whereas the full package does. Overall, I think it's a good idea to recommend the OS distro first and then the binary installer if the version is lagging.

[rjbou]

If there is no opamroot, install script will advice to run opam init, that checks for dependencies. And when it is already here, an opam reinit is advised in all blog posts, that also check for deps. But yes, they are not installed by the install script itself.

On the presentation, binary install is more light than distros part. When you look at the page, you see that there is binary install and distros ones. If binary install is at the bottom, it won't be seen anymore.

Binary install script is however incomplete, it needs to be more explicit, display current last version, and notify that dev version can be installed too.

[dra27]

Apologies for the long delay on further feedback for this mostly uncontended and excellent update to the docs!

Would it be OK for this to be rebased - potentially with the order of the paragraphs not changed in order to get the corrections and other improvements in and then spin off another PR which does the re-ordering and which can have more discussion as required?

That said, we discussed this this morning! The problem here is that often distributions will be behind the latest version and so while we want the user who skims quickly just to see the OS package manager instructions, we also don't want the binary install instructions completely buried, for those trying to figure out how to install betas, etc. Could we instead do the reordering as proposed but add a bit in the "How to install opam" section which signposts the 3 different ways of installing (OS package manager, binary release, source release) with anchor links to the sections? Something along the lines of; "You probably want to use your OS package manager's opam package, although these can be behind the latest version (and don't package pre-release versions) which can be installed using our signed opam binaries. Finally, opam can always be built from sources, with only a C++ compiler and make, as detailed below.

[johnwhitington]

Would it be OK for this to be rebased - potentially with the order of the paragraphs not changed in order to get the corrections and other improvements in and then spin off another PR which does the re-ordering and which can have more discussion as required?

The uncontested parts (2) and (3) above are tiny single-word or single-line changes, so this would be the right approach, I think.

[rjbou]

@rjbou split PR without reordering and merge

[rjbou]

updated