+locating hook-enabled commands; +in-shell stuff

Authoring-plugins.md

@@ -80,16 +80,29 @@ fi
 Note: **it's important to keep the above comment intact**. This is how pyenv
 detects if a command is capable of providing completion values.
 
+### In-shell commands
+
+Executables named `pyenv-sh-COMMAND` are invoked by the `pyenv` shell function when the user runs `pyenv COMMAND` with Pyenv shell integration enabled.
+
+Unlike regular commands, in-shell commands need to _print_ the code that would be executed in the user's shell to the standard output.
+This code will most likely depend on which type of shell the user has (the `$shell` variable).
 
 ## pyenv hooks
 
-Hooks are bash scripts named like `HOOK_NAME/*.bash`, where "HOOK_NAME" is one
+Hooks are bash scripts named like `HOOK_NAME/*.bash`, where "HOOK_NAME" is the Pyenv subcommand that you are hooking into (more specifically, the argument that the subcommand passes to `pyenv-hooks` in its source code).
-of:
+E.g. as of this writing, Pyenv core commands that support hooks are:
 
 * `exec`
 * `rehash`
 * `which`
 
+And the Python-Build plugin supports hooks for:
+
+* `install
+* `uninstall`
+
+Generally, you can search subcommands for `pyenv-hooks` calls to quickly locate those that support hooks, e.g.: `find "$(pyenv root)" -type f -name 'pyenv-*' -exec grep -HEe "pyenv-hooks [[:alnum:]]" {} +`
+
 Hooks are looked for in `$PYENV_HOOK_PATH`, which is composed of:
 
 1. `$PYENV_HOOK_PATH` (external value)
@@ -103,3 +116,32 @@ Hook scripts are executed at specific points during pyenv operation. They
 provide a low-level entry point for integration with pyenv's functionality. To
 get a better understanding of the possibilities with hooks, read the source
 code of pyenv's hook-enabled commands listed above.
+
+Many subcommands that support hooks define specific shell functions that hook scripts can call to install additional functions to be called at certain points during the subcommand's execution. This is usually done with boilerplate code so e.g. in the core and official plugins, you can generally locate such code by searching for "`"$hook"`" and looking at the surrounding code, e.g.: `find "$(pyenv root)" -type f -name 'pyenv-*' -exec grep -C3 -HEe '"\$hook"' {} +`
+
+Example:
+
+`$(pyenv root)/plugins/my_cool_plugin/etc/pyenv.d/install.bash`:
+
+```bash
+echo "My cool plugin hook running!"
+
+my_cool_plugin_before_install() {
+  echo "About to install: $DEFINITION"
+}
+
+my_cool_plugin_after_install() {
+  echo "Installed: $DEFINITION"
+}
+
+echo "My cool plugin hook setting up additional functions to be called later"
+
+before_install my_cool_plugin_before_install
+after_install my_cool_plugin_after_install
+
+echo "My cool plugin hook completed!"
+```
+
+### Hooking in-shell subcommands
+
+Like in-shell subcommands themselves (see above), hooks for them also need to _print_ the code that would be executed in the user's shell.