Explicitly specify how to use the Zsh shell snippet
It turns out to be unclear to some users

It's a valuable asset of Pyenv and https://github.com/pyenv/pyenv/issues/3275 showed it has stoppped being discoverable

[no ci]

* perf: replace a series of if statements with a case block. Add error
handling for case where unknown option is provided.
Same setup as rbenv-init for reading arguments.

* perf, docs: Recommend users to specify the shell for `pyenv init -`
Speeds up the startup by about 40% (in local testing, from ~50ms to ~30ms).
Reflect this in `pyenv init` hint text.

* style: remove unnecessary `root` variable in pyenv-init
* style: remove unnecessary variable declarations at the top of file in pyenv-init.

* perf: replace `cat <<` calls with `echo`
The builtin `echo` is about 100x faster. In tests, saves about 2-3ms.

* docs: document the `pyenv init - <shell>` performance boost in the Advanced Configuration section.

* style: test_helper.bash: avoid unnecessary ".." in produced PATH

* docs: fix a false statement about completions location in the Advanced Configuration section.

`shell` does not fall through to `local`, and `local to `global`.

There's a complaint that this results in duplicate PATH entries in nested shells, will deal with that separately

Co-authored-by: native-api <vano@mail.mipt.ru>

HTML and Markdown need to be separated by an empty line to co-exist, otherwise the Markdown isn't parsed correctly.

* Reorganize readme, add gif

1. Details in 'Getting Pyenv' and 'Setup for your shell' are collapsed. User can expand relevant
   sections depending on their platform and shell.

2. 'How It Works' and 'Advanced Configuration' are moved to the bottom of the README.md
   just before 'Contributing' section at the end.

3. Added a GIF in the 'Usage' section to showcase
   - Listing python versions available for install.
   - Installing a specific python version.
   - Listing installed python versions.
   - Switching to another python version for a directory.
   - Testing by moving terminal into the directory and moving back.

* Update GIF to show prefix resolution

* Collapse upgrade notes

* Cross-mention Linux and MacOS instlalation scenarios

---------

Co-authored-by: Ivan Pozdeev <vano@mail.mipt.ru>

Closes #3069

[Fig](https://fig.io) has been sunlit for new users, with access being removed in September

[no ci]

This PR corrects a small but important detail in the documentation regarding how the system searches for executable files. The original text incorrectly stated that the operating system performs this search. The corrected text clarifies that it is actually the shell that performs the search.

Fixes breakage in WSL with Pyenv-win installed in the host system;
doesn't affect other supported installation scenarios.

Co-authored-by: Ivan Pozdeev <vano@mail.mipt.ru>

Recent feedback showed that it's not visible enough

Co-authored-by: Ivan Pozdeev <vano@mail.mipt.ru>

There was a space at the beginning of the `git clone` command

* Document listing available versions in the tutorial (#1677)
* Reflect 3.7.15's extended support
* Document using development head with Homebrew
* Structurize the Upgrading section
* Fix Pyenv-latest documentation

Added in https://github.com/pyenv/pyenv/pull/2463

The original instructions were added 2 years ago in 0f2d659732. Since then, [Fish released](https://github.com/fish-shell/fish-shell/releases/tag/3.2.0) [a more declarative instruction for this operation](https://fishshell.com/docs/current/cmds/fish_add_path.html), which is now the recommended way of manipulating `PATH` in Fish.

We're going to eliminate the need to mandatorily use `pyenv init --path`.
We can't delete it yet for backward compatibility.
Besides, there's one other use case for it: to enable shims but without
shell integration, e.g. for noninteractive shells.

To be a full-fledged replacement for `pyenv init -` however,
it needs to do rehashing.

Now the setup is to add to both rc and profile:
1) set PYENV_ROOT
   (can do it unconditionally -- since if you change it,
   you need to update all places anyway since any of them can be run first)
2) Add `pyenv` to PATH if not already there
3) eval "$(pyenv init -)"

Not a breaking change, old setup will continue to work.