docs: rewrite parse-legacy-file docs

docs/plugins/create.md

@@ -234,106 +234,274 @@ No parameters provided.
 
 ## Optional Scripts
 
-<!-- TODO(jthegedus): rework from bin/latest-stable to bin/pre-plugin-remove -->
-
 ### `bin/latest-stable` <Badge type="warning" text="recommended" vertical="middle" />
 
-If this callback is implemented asdf will use it to determine the latest stable
-version of your tool instead of trying deduce it for you on its own.
-`asdf latest` deduces the latest version by looking at the last version printed
-by the `list-all` callback, after a few types of versions (like release
-candidate versions) are excluded from the output. This default behavior is
-undesirable when your plugin's `list-all` callback prints different variations
-of the same tool and the last version isn't the latest stable version of the
-variation you'd like to default to. For example with Ruby the latest stable
-version should be the regular implementation of Ruby (MRI), but truffleruby
-versions are printed last by the `list-all` callback.
+**Description**
 
-This callback is invoked with a single "filter" string as its only argument.
-This should be used for filter all latest stable versions. For example with
-Ruby, the user may choose to pass in `jruby` to select the latest stable version
-of `jruby`.
+Determine the latest stable version of a tool. If absent, the asdf core will `tail` the `bin/list-all` output which may be undesirable.
 
-<!-- TODO(jthegedus): removed information -->
+**Implementation Details**
 
-<!-- Each of these scripts should tailor their output to the current operating
-system. For example, when on Ubuntu the deps script could output the
-dependencies as apt-get packages that must be installed. The script should also
-tailor its output to the value of `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE`
-when the variables are set. They are optional and will not always be set.
+- The script should print the latest stable version of the tool to stdout.
+- Non-stable or release candidate versions should be omitted.
+- A filter query is provided as the first argument to the script. This should be used to filter the output by version number or tool provider.
+  - For instance, the output of `asdf list all ruby` from the [ruby plugin](https://github.com/asdf-vm/asdf-ruby) lists versions of Ruby from many providers: `jruby`, `rbx` & `truffleruby` amongst others. The user provided filter could be used by the plugin to filter the semver versions and/or provider.
+    ```
+    > asdf latest ruby
+    3.2.2
+    > asdf latest ruby 2
+    2.7.8
+    > asdf latest ruby truffleruby
+    truffleruby+graalvm-22.3.1
+    ```
+- Success should exit with `0`.
+- Failure should exit with a non-zero status.
 
-The help callback script MUST NOT output any information that is already covered
-in the core asdf-vm documentation. General asdf usage information must not be
-present. -->
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf global <tool> latest`: set the global version of a tool to the latest stable version for that tool.
+- `asdf local <name> latest`: set the local version of a tool to the latest stable version for that tool.
+- `asdf install <tool> latest`: installs the latest version of a tool.
+- `asdf latest <tool> [<version>]`: outputs the latest version of a tool based on the optional filter.
+- `asdf latest --all`: outputs the latest version of all tools managed by asdf and whether they are installed.
+
+**Call signature from asdf core**
+
+The script should accept a single argument, the filter query.
+
+```bash:no-line-numbers
+"${plugin_path}"/bin/latest-stable ""
+"${plugin_path}"/bin/latest-stable "$query"
+```
 
 ---
 
 ### `bin/help.overview`
 
-`bin/help.overview` - This script should output a general description about the
-plugin and the tool being managed. No heading should be printed as asdf will
-print headings. Output may be free-form text but ideally only one short
-paragraph. This script must be present if you want asdf to provide help
-information for your plugin. All other help callback scripts are optional.
+**Description**
 
-This is not one callback script but rather a set of callback scripts that each
-print different documentation to STDOUT. The possible callback scripts are
-listed below. Note that `bin/help.overview` is a special case as it must be
-present for any help output to be displayed for the script.
+Output a general description about the plugin and the tool being managed.
+
+**Implementation Details**
+
+- This script is required for any help output to be displayed for the plugin.
+- No heading should be printed as asdf core will print headings.
+- Output may be free-form text but ideally only one short paragraph.
+- Must not output any information that is already covered in the core asdf-vm documentation.
+- Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE`).
+- Success should exit with `0`.
+- Failure should exit with a non-zero status.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf help <name> [<version>]`: Output documentation for plugin and tool
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}"/bin/help.overview
+```
 
 ---
 
 ### `bin/help.deps`
 
-<!-- TODO(jthegedus): note, this script requires bin/help.overview -->
+**Description**
 
-This script should output the list of dependencies tailored to the operating
-system. One dependency per line.
+Output the list of dependencies tailored to the operating system. One dependency per line.
+
+```bash:no-line-numbers
+git
+curl
+sed
+```
+
+**Implementation Details**
+
+- This script requires `bin/help.overview` for its output to be considered.
+- Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE`).
+- Success should exit with `0`.
+- Failure should exit with a non-zero status.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf help <name> [<version>]`: Output documentation for plugin and tool
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}"/bin/help.deps
+```
 
 ---
 
 ### `bin/help.config`
 
-<!-- TODO(jthegedus): note, this script requires bin/help.overview -->
+**Description**
 
-This script should print any required or optional configuration that may be
-available for the plugin and tool. Any environment variables or other flags
-needed to install or compile the tool (for the users operating system when
-possible). Output can be free-form text.
+Output any required or optional configuration for the plugin and tool. For example, describe any environment variables or other flags needed to install or compile the tool.
+
+**Implementation Details**
+
+- This script requires `bin/help.overview` for its output to be considered.
+- Output can be free-form text.
+- Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE`).
+- Success should exit with `0`.
+- Failure should exit with a non-zero status.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf help <name> [<version>]`: Output documentation for plugin and tool
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}"/bin/help.config
+```
 
 ---
 
 ### `bin/help.links`
 
-<!-- TODO(jthegedus): note, this script requires bin/help.overview -->
+**Description**
 
-This should be a list of links relevant to the plugin and tool (again, tailored
-to the current operating system when possible). One link per line. Lines may be
-in the format `<title>: <link>` or just `<link>`.
+Output a list of links relevant to the plugin and tool. One link per line.
+
+```bash:no-line-numbers
+Git Repository:	https://github.com/vlang/v
+Documentation:	https://vlang.io
+```
+
+**Implementation Details**
+
+- This script requires `bin/help.overview` for its output to be considered.
+- One link per line.
+- Format must be either:
+  - `<title>: <link>`
+  - or just `<link>`
+- Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE`).
+- Success should exit with `0`.
+- Failure should exit with a non-zero status.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf help <name> [<version>]`: Output documentation for plugin and tool
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}"/bin/help.links
+```
 
 ---
 
 ### `bin/list-bin-paths`
 
-List executables for the specified version of the tool. Must print a string with
-a space-separated list of dir paths that contain executables. The paths must be
-relative to the install path passed. Example output would be:
+**Description**
 
-```shell
+List directories containing executables for the specified version of the tool.
+
+**Implementation Details**
+
+- If this script is not present, asdf will look for binaries in the `"${ASDF_INSTALL_PATH}"/bin` directory & create shims for those.
+- Output a space-separated list of paths containing executables.
+- Paths must be relative to `ASDF_INSTALL_PATH`. Example output would be:
+
+```bash:no-line-numbers
 bin tools veggies
 ```
 
-This will instruct asdf to create shims for the files in `<install-path>/bin`,
-`<install-path>/tools` and `<install-path>/veggies`
+This will instruct asdf to create shims for the files in:
+- `"${ASDF_INSTALL_PATH}"/bin`
+- `"${ASDF_INSTALL_PATH}"/tools`
+- `"${ASDF_INSTALL_PATH}"/veggies`
 
-If this script is not specified, asdf will look for the `bin` dir in an
-installation and create shims for those.
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf install <tool> [version]`: initially create shims for binaries.
+- `asdf reshim <tool> <version>`: recreate shims for binaries.
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}/bin/list-bin-paths"
+```
 
 ---
 
 ### `bin/exec-env`
 
-Setup the env to run the binaries in the package.
+**Description**
+
+Prepare the environment before executing the shims for the binaries for the tool.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf which <command>`: Display the path to an executable
+- `asdf exec <command> [args...]`: Executes the command shim for current version
+- `asdf env <command> [util]`: Runs util (default: `env`) inside the environment used for command shim execution.
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}/bin/exec-env"
+```
 
 ---
 
@@ -344,6 +512,15 @@ string with the relative executable path. This allows the plugin to
 conditionally override the shim's specified executable path, otherwise return
 the default path specified by the shim.
 
+**Description**
+
+Get the executable path for the specified version of the tool.
+
+**Implementation Details**
+
+- Must print a string with the relative executable path.
+- Conditionally override the shim's specified executable path, otherwise return the default path specified by the shim.
+
 ```shell
 Usage:
   plugin/bin/exec-path <install-path> <command> <executable-path>
@@ -355,6 +532,26 @@ Output:
   bin/foox
 ```
 
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+- `asdf which <command>`: Display the path to an executable
+- `asdf exec <command> [args...]`: Executes the command shim for current version
+- `asdf env <command> [util]`: Runs util (default: `env`) inside the environment used for command shim execution.
+
+**Call signature from asdf core**
+
+```bash:no-line-numbers
+"${plugin_path}/bin/exec-path" "$install_path" "$cmd" "$relative_path"
+```
+
 ---
 
 ### `bin/uninstall`
@@ -388,31 +585,77 @@ No parameters provided.
 
 ### `bin/list-legacy-filenames`
 
-Register additional setter files for this plugin. Must print a string with a
-space-separated list of filenames.
+**Description**
 
-```shell
-.ruby-version .rvmrc
+List legacy configuration filenames for determining the specified version of the tool.
+
+**Implementation Details**
+
+- Output a space-separated list of filenames.
+  ```bash:no-line-numbers
+  .ruby-version .rvmrc
+  ```
+- Only applies for users who have enabled the `legacy_version_file` option in their `"${HOME}"/.asdfrc`.
+
+**Environment Variables available to script**
+
+- `ASDF_INSTALL_TYPE`: `version` or `ref`
+- `ASDF_INSTALL_VERSION`:
+  - Full version number if `ASDF_INSTALL_TYPE=version`.
+  - Git ref (tag/commit/branch) if `ASDF_INSTALL_TYPE=ref`.
+- `ASDF_INSTALL_PATH`: The path to where the tool _has been_, or _should be_ installed.
+
+**Commands that invoke this script**
+
+Any command which reads a tool version.
+
+**Call signature from asdf core**
+
+No parameters provided.
+
+```bash:no-line-numbers
+"${plugin_path}/bin/list-legacy-filenames"
 ```
 
-Note: This will only apply for users who have enabled the `legacy_version_file`
-option in their `~/.asdfrc`.
-
 ---
 
 ### `bin/parse-legacy-file`
 
-This can be used to further parse the legacy file found by asdf. If
-`parse-legacy-file` isn't implemented, asdf will simply `cat` the file to
-determine the version. The script will be passed the file path as its first
-argument. Note that this script should be **deterministic** and always return
-the same exact version when parsing the same legacy file. The script should
-return the same version regardless of what is installed on the machine or
-whether the legacy version is valid or complete. Some legacy file formats may
-not be suitable.
+**Description**
+
+Parse the legacy file found by asdf to determine the version of the tool. Useful to extract version numbers from files like JavaScript's `package.json` or Golangs `go.mod`.
+
+**Implementation Details**
+
+- If not present, asdf will simply `cat` the legacy file to determine the version.
+- Should be **deterministic** and always return the same exact version:
+  - when parsing the same legacy file.
+  - regardless of what is installed on the machine or whether the legacy version is valid or complete. Some legacy file formats may not be suitable.
+- Output a single line with the version:
+  ```bash:no-line-numbers
+  1.2.3
+  ```
+
+**Environment Variables available to script**
+
+No environment variables specifically set before this script is called.
+
+**Commands that invoke this script**
+
+Any command which reads a tool version.
+
+**Call signature from asdf core**
+
+The script should accept a single argument, the path to the legacy file for reading its contents.
+
+```bash:no-line-numbers
+"${plugin_path}/bin/parse-legacy-file" "$file_path"
+```
 
 ---
 
+<!-- TODO(jthegedus): rework from bin/post-plugin-add to bin/pre-plugin-remove -->
+
 ### `bin/post-plugin-add`
 
 This can be used to run any post-installation actions after the plugin has been