Add a new doc page Why Mill? / How Fast Does Java Compile? (#3990)

docs/modules/ROOT/nav.adoc

@@ -37,12 +37,12 @@
 ** xref:comparisons/gradle.adoc[]
 ** xref:comparisons/sbt.adoc[]
 ** xref:comparisons/unique.adoc[]
+** xref:comparisons/java-compile.adoc[]
 * The Mill CLI
 ** xref:cli/installation-ide.adoc[]
 ** xref:cli/flags.adoc[]
 ** xref:cli/builtin-commands.adoc[]
 ** xref:cli/query-syntax.adoc[]
-** xref:cli/alternate-installation.adoc[]
 * Migrating to Mill
 ** xref:migrating/maven.adoc[]
 // This section gives a tour of the various user-facing features of Mill:

docs/modules/ROOT/pages/cli/installation-ide.adoc

@@ -256,3 +256,124 @@ The easiest way to use a development release is to use one of the
 `MILL_VERSION` environment variable or a `.mill-version` or `.config/mill-version` file.
 
 
+
+== Other installation methods
+
+CAUTION: The installation methods listed below are maintained outside of Mill and may not have
+the same features as the xref:cli/installation-ide.adoc#_bootstrap_scripts[bootstrap scripts]. You can try using them,
+but the officially supported way to use Mill is via the bootstrap script above, so the Mill
+maintainers may be unable to help you if you have issues with some alternate installation method.
+
+CAUTION: Some of the installations via package managers install a fixed version of Mill and
+do not support project-specific selection of the preferred Mill version. If you want to use
+the `MILL_VERSION` environment variable or need support for `.mill-version` or
+`.config/mill-version` files to control the actual used Mill version, please use
+a xref:cli/installation-ide.adoc#_bootstrap_scripts[bootstrap script] instead.
+
+=== OS X
+
+Installation via https://github.com/Homebrew/homebrew-core/blob/master/Formula/m/mill.rb[homebrew]:
+
+[source,sh]
+----
+brew install mill
+----
+
+
+=== Arch Linux
+
+Arch Linux has an https://archlinux.org/packages/extra/any/mill/[Extra package for mill]:
+
+[source,bash]
+----
+pacman -S mill
+
+----
+
+=== FreeBSD
+
+Installation via http://man.freebsd.org/pkg/8[pkg(8)]:
+
+[source,sh]
+----
+pkg install mill
+
+----
+
+=== Gentoo Linux
+
+[source,sh]
+----
+emerge dev-java/mill-bin
+
+----
+
+=== Windows
+
+To get started, download Mill from
+{mill-github-url}/releases/download/{mill-last-tag}/{mill-last-tag}-assembly[Github releases], and save it as `mill.bat`.
+
+If you're using https://scoop.sh[Scoop] you can install Mill via
+
+[source,bash]
+----
+scoop install mill
+----
+
+=== WSL / MSYS2 / Cycgin / Git-Bash
+
+Mill also works on "sh" environments on Windows (e.g.,
+https://www.msys2.org[MSYS2],
+https://www.cygwin.com[Cygwin],
+https://gitforwindows.org[Git-Bash],
+https://docs.microsoft.com/en-us/windows/wsl[WSL]); to get started, follow the instructions in the <<_manual>>
+section. Note that:
+
+* In some environments (such as WSL), Mill might have to be run without a server (using `-i`, `--interactive`, or `--no-server`.)
+
+* On Cygwin, run the following after downloading mill:
+
+[source,bash]
+----
+sed -i '0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}; 0,/-cp "\$0"/{s/-cp "\$0"/-cp `cygpath -w "\$0"`/}' /usr/local/bin/mill
+----
+
+=== Docker
+
+You can download and run
+a https://hub.docker.com/r/nightscape/scala-mill/["Docker image containing OpenJDK, Scala and Mill"] using
+
+[source,bash]
+----
+docker pull nightscape/scala-mill
+docker run -it nightscape/scala-mill
+----
+
+=== Manual
+
+To get started, download Mill and install it into your HOME ".local/bin" via the following
+`curl`/`chmod` command:
+
+[source,bash,subs="verbatim,attributes"]
+----
+sh -c "curl -L {mill-github-url}/releases/download/{mill-last-tag}/{mill-last-tag} > ~/.local/bin/mill && chmod +x ~/.local/bin/mill"
+----
+
+=== Coursier (unsupported)
+
+Installing mill via `coursier` or `cs` is currently not officially supported.
+There are various issues, especially with interactive mode.
+
+=== Asdf (unsupported)
+
+You can install and manage Mill via the Multiple Runtime Version Manager - https://asdf-vm.com/[`asdf`].
+
+Support by `asdf` is currently possible by using the https://github.com/asdf-community/asdf-mill[`asdf-mill` plugin]:
+
+.Steps to install the `mill` plugin and Mill with `asdf`
+[source,bash]
+---
+asdf plugin add mill
+asdf install mill latest
+asdf global mill latest
+---