docs: update help docs (#1370)

7 files changed, 45 insertions, 13 deletions

diff --git a/README.md b/README.md
index b11c6848..16520998 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,7 @@ Although many packages are perfectly usable out of the box through Neovim builti
 party plugins to further integrate these. The following plugins are recommended:
 
 -   LSP: [`lspconfig`][lspconfig] & [`mason-lspconfig.nvim`][mason-lspconfig.nvim]
--   DAP: [`nvim-dap`][nvim-dap]
+-   DAP: [`nvim-dap`][nvim-dap] & [`nvim-dap-ui`][nvim-dap-ui]
 -   Linters: [`null-ls.nvim`][null-ls.nvim] or [`nvim-lint`][nvim-lint]
 -   Formatters: [`null-ls.nvim`][null-ls.nvim] or [`formatter.nvim`][formatter.nvim]
 
@@ -61,6 +61,7 @@ party plugins to further integrate these. The following plugins are recommended:
 [mason-lspconfig.nvim]: https://github.com/williamboman/mason-lspconfig.nvim
 [null-ls.nvim]: https://github.com/jose-elias-alvarez/null-ls.nvim
 [nvim-dap]: https://github.com/mfussenegger/nvim-dap
+[nvim-dap-ui]: https://github.com/rcarriga/nvim-dap-ui
 [nvim-lint]: https://github.com/mfussenegger/nvim-lint
 
 ## Screenshots
diff --git a/doc/mason.txt b/doc/mason.txt
index c7fc564b..93c98b79 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -15,10 +15,11 @@ editor tooling such as LSP servers, DAP servers, linters, and formatters
 through a single interface. It runs everywhere Neovim runs (across Linux,
 macOS, Windows, etc.), with only a small set of external requirements needed.
 
-Packages are installed in Neovim's `:h stdpath` by default. Executables are
-linked to a single `bin/` directory, which `mason.nvim` will add to the
-Neovim's PATH during setup, allowing easy access for the builtin
-shell/terminal as well as other 3rd party plugins.
+Packages are installed in Neovim's data directory (`:h standard-path`) by
+default. Executables are linked to a single `bin/` directory, which
+`mason.nvim` will add to Neovim's PATH during setup, allowing seamless access
+from Neovim builtins (shell, terminal, etc.) as well as other 3rd party
+plugins.
 
 -----------------
 MASON.NVIM LUA API
@@ -39,8 +40,7 @@ Extension plugins help fill gaps with the rest of the Neovim ecosystem.
 
 mason-lspconfig ~
     `mason-lspconfig` bridges Mason with the `lspconfig` plugin - making
-    it easier to use both plugins together. Strongly recommended for Windows
-    users.
+    it easier to use both plugins together.
     https://github.com/williamboman/mason-lspconfig.nvim
 
 3rd party extensions ~
@@ -157,7 +157,7 @@ builtins, it is recommended to use other 3rd party plugins to further
 integrate these. The following plugins are recommended:
 
 -   LSP: `lspconfig` & `mason-lspconfig.nvim`
--   DAP: `nvim-dap`
+-   DAP: `nvim-dap` & `nvim-dap-ui`
 -   Linters: `null-ls.nvim` or `nvim-lint`
 -   Formatters: `null-ls.nvim` or `formatter.nvim`
 
@@ -166,6 +166,7 @@ lspconfig             https://github.com/neovim/nvim-lspconfig
 mason-lspconfig.nvim  https://github.com/williamboman/mason-lspconfig.nvim
 null-ls.nvim          https://github.com/jose-elias-alvarez/null-ls.nvim
 nvim-dap              https://github.com/mfussenegger/nvim-dap
+nvim-dap-ui           https://github.com/rcarriga/nvim-dap-ui
 nvim-lint             https://github.com/mfussenegger/nvim-lint
 
 See also ~
diff --git a/lua/mason/ui/components/help/dap.lua b/lua/mason/ui/components/help/dap.lua
index 6344e234..e17f9587 100644
--- a/lua/mason/ui/components/help/dap.lua
+++ b/lua/mason/ui/components/help/dap.lua
@@ -5,6 +5,9 @@ local p = require "mason.ui.palette"
 return function(state)
     return Ui.HlTextNode {
         {
+            p.Bold "What is DAP?",
+        },
+        {
             p.none "The ",
             p.highlight_secondary "D",
             p.none "ebugger ",
@@ -23,5 +26,8 @@ return function(state)
             p.none "capabilities - such as pausing execution, stepping through statements,",
         },
         { p.none "and inspecting variables." },
+        {},
+        { p.none "For more information, see:" },
+        { p.none " - https://microsoft.github.io/debug-adapter-protocol/" },
     }
 end
diff --git a/lua/mason/ui/components/help/formatter.lua b/lua/mason/ui/components/help/formatter.lua
index 45e83e9b..fcdd7b6b 100644
--- a/lua/mason/ui/components/help/formatter.lua
+++ b/lua/mason/ui/components/help/formatter.lua
@@ -4,6 +4,9 @@ local p = require "mason.ui.palette"
 ---@param state InstallerUiState
 return function(state)
     return Ui.HlTextNode {
+        {
+            p.Bold "What is a formatter?",
+        },
         { p.none "A code formatter is a tool that reformats code to fit a certain" },
         { p.none "formatting convention. This usually entails things like adjusting" },
         { p.none "indentation, breaking long lines into smaller lines, adding or" },
diff --git a/lua/mason/ui/components/help/init.lua b/lua/mason/ui/components/help/init.lua
index 0b4a57a6..dc1103b4 100644
--- a/lua/mason/ui/components/help/init.lua
+++ b/lua/mason/ui/components/help/init.lua
@@ -49,11 +49,12 @@ local function GenericHelp(state)
     local keymap_tuples = {
         { "Toggle help", "g?" },
         { "Toggle package info", settings.current.ui.keymaps.toggle_package_expand },
+        { "Toggle package installation log", settings.current.ui.keymaps.toggle_package_install_log },
         { "Apply language filter", settings.current.ui.keymaps.apply_language_filter },
         { "Install package", settings.current.ui.keymaps.install_package },
         { "Uninstall package", settings.current.ui.keymaps.uninstall_package },
         { "Update package", settings.current.ui.keymaps.update_package },
-        { "Update all installed packages", settings.current.ui.keymaps.update_all_packages },
+        { "Update all outdated packages", settings.current.ui.keymaps.update_all_packages },
         { "Check for new package version", settings.current.ui.keymaps.check_package_version },
         { "Check for new versions (all packages)", settings.current.ui.keymaps.check_outdated_packages },
         { "Cancel installation of package", settings.current.ui.keymaps.cancel_installation },
@@ -115,11 +116,12 @@ local function GenericHelp(state)
             { p.Bold "How do I use installed packages?" },
             { p.muted "Mason only makes packages available for use. It does not automatically integrate" },
             { p.muted "these into Neovim. You have multiple different options for using any given" },
+            { p.muted "package, and you are free to pick and choose as you see fit." },
             {
-                p.muted "package, and you are free to pick and choose as you see fit. See ",
-                p.highlight ":h mason-how-to",
+                p.muted "See ",
+                p.highlight ":help mason-how-to-use-packages",
+                p.muted " for a recommendation.",
             },
-            { p.muted "for a recommendation." },
         },
         Ui.EmptyLine(),
         Ui.HlTextNode {
@@ -129,9 +131,11 @@ local function GenericHelp(state)
         Ui.CascadingStyleNode({ "INDENT" }, {
             Ui.HlTextNode {
                 {
+                    p.none "- ",
                     p.highlight "https://github.com/williamboman/mason.nvim/blob/main/CONTRIBUTING.md",
                 },
                 {
+                    p.none "- ",
                     p.highlight "https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md",
                 },
             },
diff --git a/lua/mason/ui/components/help/linter.lua b/lua/mason/ui/components/help/linter.lua
index d0809de3..a4683352 100644
--- a/lua/mason/ui/components/help/linter.lua
+++ b/lua/mason/ui/components/help/linter.lua
@@ -4,10 +4,13 @@ local p = require "mason.ui.palette"
 ---@param state InstallerUiState
 return function(state)
     return Ui.HlTextNode {
+        {
+            p.Bold "What is a linter?",
+        },
         { p.none "A linter is a static code analysis tool used to provide diagnostics around" },
         { p.none "programming errors, bugs, stylistic errors and suspicious constructs." },
         { p.none "Linters can be executed as a standalone program in a terminal, where it" },
         { p.none "usually expects one or more input files to lint. There are also Neovim plugins" },
-        { p.none "that integrate these diagnostics directly inside the editor, for a richer experience." },
+        { p.none "that integrate these diagnostics inside the editor." },
     }
 end
diff --git a/lua/mason/ui/components/help/lsp.lua b/lua/mason/ui/components/help/lsp.lua
index 6ced6ee1..d288cbb2 100644
--- a/lua/mason/ui/components/help/lsp.lua
+++ b/lua/mason/ui/components/help/lsp.lua
@@ -5,6 +5,9 @@ local p = require "mason.ui.palette"
 return function(state)
     return Ui.HlTextNode {
         {
+            p.Bold "What is LSP?",
+        },
+        {
             p.none "The ",
             p.highlight_secondary "L",
             p.none "anguage ",
@@ -19,5 +22,16 @@ return function(state)
         {
             p.none "like auto complete, go to definition, find all references etc.",
         },
+        {},
+        {
+            p.none "The term ",
+            p.highlight_secondary "LSP",
+            p.none " is often used to reference a server implementation of",
+        },
+        { p.none "the LSP protocol." },
+        {},
+        { p.none "For more information, see:" },
+        { p.none " - https://microsoft.github.io/language-server-protocol/" },
+        { p.none " - ", p.highlight ":help lsp" },
     }
 end