docs: some general improvements (#715)

1 files changed, 37 insertions, 16 deletions

diff --git a/doc/mason.txt b/doc/mason.txt
index 5a2f2c37..3c654f60 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -8,25 +8,41 @@ Author: William Boman
 ==============================================================================
 INTRODUCTION                                              *mason-introduction*
 
-`mason.nvim` is a Neovim plugin that allow you to easily manage external
+`mason.nvim` is a Neovim plugin that allows you to easily manage external
 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 to Neovim's `:h stdpath` by default. Executables are
+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.
 
+-----------------
+MASON.NVIM LUA API
                                                          *mason-api-reference*
-API reference:
-    https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md
+Mason offers a public Lua API that allows you to further customize or
+extend Mason. You may find documentation for it in the link below.
+
+https://github.com/williamboman/mason.nvim/blob/main/doc/reference.md
+
+Note ~
+    APIs not listed in the document are not considered public and are subject
+    to unannounced breaking changes.
 
+-----------------
+EXTENSION PLUGINS
                                                             *mason-extensions*
-Extensions:
-    - https://github.com/williamboman/mason-lspconfig.nvim
+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.
+    https://github.com/williamboman/mason-lspconfig.nvim
 
-3rd party extensions: https://github.com/williamboman/mason.nvim/wiki/Extensions
+3rd party extensions ~
+    https://github.com/williamboman/mason.nvim/wiki/Extensions
 
 ==============================================================================
 REQUIREMENTS                                              *mason-requirements*
@@ -41,7 +57,7 @@ perfect substitutes). The _minimum_ recommended requirements are:
 -   For Windows systems: pwsh, git, tar, and 7zip or peazip or archiver
     or winzip or WinRAR
 
-Note that `mason.nvim` will regularly shell out to external package managers,
+Note that Mason will regularly shell out to external package managers,
 such as `cargo` and `npm`. Depending on your personal usage, some of these
 will also need to be installed. Refer to `:checkhealth mason` for a full list.
 
@@ -49,20 +65,21 @@ will also need to be installed. Refer to `:checkhealth mason` for a full list.
 QUICK START                                                 *mason-quickstart*
 
 -----------------
-Setting up mason.nvim
+SETTING UP MASON.NVIM
 
-The only thing needed to get started with mason.nvim is to make sure to call
-the `setup()` function:
+First you'll need to set up Mason. This is done by calling the `setup()`
+function:
 >lua
     require("mason").setup()
 <
-This will enhance the Neovim session's PATH environment with the location of
-executables installed with mason.nvim.
+Mason will do the following during setup:
+    1) enhance the Neovim session's PATH environment
+    2) register commands (|mason-commands|)
 
-Refer to |mason-settings| for available settings.
+Refer to |mason-settings| for all available settings.
 
 -----------------
-Installing packages
+INSTALLING PACKAGES
 
 Install a package via |:MasonInstall|, for example:
 >vim
@@ -92,7 +109,7 @@ Note: ~
     access to more features to allow further customization.
 
 -----------------
-The Mason window
+THE MASON WINDOW
 
 To view the UI for mason, run: >vim
     :Mason
@@ -129,6 +146,10 @@ null-ls.nvim          https://github.com/jose-elias-alvarez/null-ls.nvim
 nvim-dap              https://github.com/mfussenegger/nvim-dap
 nvim-lint             https://github.com/mfussenegger/nvim-lint
 
+See also ~
+    Execute external commands: |:!cmd|.
+    Launch an embedded terminal: |terminal|.
+    Launch background jobs: |jobstart| & |uv.spawn()| (via |vim.loop|)
 
 ==============================================================================
 COMMANDS                                                      *mason-commands*