Overhaul documentation

.github/ISSUE_TEMPLATE/config.yml

@@ -5,4 +5,4 @@ contact_links:
     about: Get help with using the plugin
   - name: 💡 Idea
     url: https://github.com/PatrickF1/fzf.fish/discussions/new?category=ideas
-    about: Suggest a new feature or an improvement to existing features
+    about: Suggest an improvement or addition to the plugin

README.md

@@ -10,65 +10,69 @@
 
 Augment your [Fish][] command line with mnemonic key bindings to efficiently find what you need using [fzf][].
 
-## Features
+## Search commands
 
-Use `fzf.fish` to interactively find and insert the shell entities listed below into your command line. <kbd>Tab</kbd> to select multiple entries. If you trigger a search while your command line cursor is touching a word, that word will be used to seed the fzf query and will be replaced by your selection. All searches include a preview of the entity hovered over so you can seamlessly determine if it's what you're looking for. The previews also make fzf.fish a handy browsing tool.
+Use `fzf.fish` to interactively find and insert file paths, git commit hashes, and other entities into your command line. <kbd>Tab</kbd> to select multiple entries. If you trigger a search while your cursor is on a word, that word will be used to seed the fzf query and will be replaced by your selection. All searches include a preview of the entity hovered over so you can seamlessly decide if it's what you're looking for.
 
-### File paths
+### 📁 Search Directory
 
 ![gif directory](../assets/directory.gif)
 
-- **Search input:** recursive listing of current directory's non-hidden files
+- **Fzf input:** recursive listing of current directory's non-hidden files
+- **Output:** relative paths of selected files
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F</kbd> (`F` for file)
 - **Preview window:** file with syntax highlighting, directory contents, or file type
 - **Remarks**
   - appends `/` to directories selected so you can hit <kbd>ENTER</kbd> to [immediately cd into it][cd docs] if it is the only token on the command line
   - if the current token is a directory with a trailing slash (e.g. `.config/<CURSOR>`), then that directory is searched instead
   - [ignores files that are also ignored by git](#fd-gi)
 
-### Modified paths
+### 📝 Search Git Status
 
 ![gif git status](../assets/git_status.gif)
 
-- **Search input:** the current repository's `git status`
+- **Fzf input:** the current repository's `git status`
+- **Output:** relative paths of selected lines
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> (`S` for status)
 - **Preview window:** the git diff of the file
 
-### Commit hashes
+### 🪵 Search Git Log
 
 ![gif git log](../assets/git_log.gif)
 
-- **Search input:** the current repository's formatted `git log`
+- **Fzf input:** the current repository's formatted `git log`
+- **Output:** hashes of selected commits
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>L</kbd> (`L` for log)
 - **Preview window:** commit message and diff
 
-### A previously run command
+### 📜 Search Command History
 
 ![gif command history](../assets/command_history.gif)
 
-- **Search input:** Fish's command history
+- **Fzf input:** Fish's command history
+- **Output:** selected commands
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>R</kbd> (`R` for reverse-i-search)
 - **Preview window:** the entire command with Fish syntax highlighting
 
-### Shell variables
+### 🐚 Search Shell Variables
 
 ![gif shell variables](../assets/shell_variables.gif)
 
-- **Search input:** all the variable names of the environment currently [in scope][var scope]
+- **Fzf input:** all the shell variables currently [in scope][var scope]
+- **Output:** selected variables
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>V</kbd> (`V` for variable)
-- **Preview window:** the scope info and values of the variable
-- `$history` is excluded for technical reasons so use the [search command history](#a-previously-run-command) feature instead to inspect it
+- **Preview window:** the variable's scope info and values
+- `$history` is excluded for technical reasons so use [Search Command History](#-search-command-history) instead to inspect it
 
-### Process ids
+### 🖥️ Search Processes
 
 ![gif processes](../assets/processes.gif)
 
-- **Search input:** the pid and command of all running processes, outputted by `ps`
+- **Fzf input:** the pid and command of all running processes, outputted by `ps`
+- **Output:** pids of selected processes
 - **Key binding and mnemonic:** <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd> (`P` for process)
 - **Preview window:** the CPU usage, memory usage, start time, and other information about the process
 
-_The prompt used in the screencasts was created using [IlanCosman/tide](https://github.com/IlanCosman/tide)._
-
 ## Installation
 
 First, install a proper version of these CLI dependencies:
@@ -80,7 +84,7 @@ First, install a proper version of these CLI dependencies:
 | [fd][]   | 8.3.0                    | faster and more colorful alternative to `find` |
 | [bat][]  | 0.16.0                   | smarter `cat` with syntax highlighting         |
 
-The search directory feature uses [fd][] and [bat][] to list and preview files. If your package manager [doesn't install them as `fd` and `bat`](https://github.com/PatrickF1/fzf.fish/wiki/Troubleshooting#search-directory-feature-does-not-work) respectively, then you can symlink them to those names.
+[fd][] and [bat][] only need to be installed if you will use [Search Directory][]. If your package manager [doesn't install them as `fd` and `bat`](https://github.com/PatrickF1/fzf.fish/wiki/Troubleshooting#search-directory-does-not-work) respectively, then you can symlink them to those names.
 
 Next, install this plugin with [Fisher][].
 
@@ -104,58 +108,56 @@ Once you've determined the desired `fzf_configure_bindings` command, add it to y
 
 ### Always pass some options to fzf
 
-fzf supports setting default options via the [FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#environment-variables) environment variable. If it is set, fzf implicitly prepends it to the options passed to it on every execution, scripted and interactive.
+fzf supports global default options via the [FZF_DEFAULT_OPTS](https://github.com/junegunn/fzf#environment-variables) environment variable. If set, fzf implicitly prepends its value to the options it receives on every execution, scripted and interactive.
 
-By default, `fzf.fish` will set a sane `FZF_DEFAULT_OPTS` every time before it executes fzf. However, if you export your own `FZF_DEFAULT_OPTS` variable, then `fzf.fish` will forgo setting it and yours will be used instead. See [functions/\_fzf_wrapper.fish](functions/_fzf_wrapper.fish) for more details.
+`fzf.fish` locally sets [a sane `FZF_DEFAULT_OPTS` whenever it executes fzf](functions/_fzf_wrapper.fish). If you export your own `FZF_DEFAULT_OPTS`, then yours will be used instead.
 
-### Pass fzf options for a specific feature
+### Pass fzf options for a specific command
 
-The following variables can store custom options that will be passed to fzf by their respective feature:
+The following variables can store custom options that will be passed to fzf by their respective command:
 
-| Feature                | Variable              |
+| Command                | Variable              |
 | ---------------------- | --------------------- |
-| Search directory       | `fzf_dir_opts`        |
-| Search git status      | `fzf_git_status_opts` |
-| Search git log         | `fzf_git_log_opts`    |
-| Search command history | `fzf_history_opts`    |
-| Search shell variables | `fzf_shell_vars_opts` |
-| Search processes       | `fzf_processes_opts`  |
+| Search Directory       | `fzf_dir_opts`        |
+| Search Git Status      | `fzf_git_status_opts` |
+| Search Git Log         | `fzf_git_log_opts`    |
+| Search Command History | `fzf_history_opts`    |
+| Search Shell Variables | `fzf_shell_vars_opts` |
+| Search Processes       | `fzf_processes_opts`  |
 
-They are always appended last to fzf's argument list. Because fzf uses the option appearing last when options conflict, your custom options can override hardcoded options. Custom fzf options unlocks a variety of possibilities in customizing and augmenting each feature such as:
+They are appended last to fzf's options list. Because fzf uses the last instance of an option if it is specified multiple times, custom options will always take precedence. Custom fzf options unlock a variety of customizations and augmentations such as:
 
 - add [key bindings](https://www.mankier.com/1/fzf#Key/Event_Bindings) within fzf to operate on the selected line:
   - [open file in Vim](https://github.com/junegunn/fzf/issues/1360)
   - [preview image files](https://gitter.im/junegunn/fzf?at=5947962ef6a78eab48620792)
-  - [copy to clipboard](https://betterprogramming.pub/boost-your-command-line-productivity-with-fuzzy-finder-985aa162ba5d)
-  - git checkout commit
   - git reset file
 - adjust the preview command or window
 - [re-populate fzf's input list on demand](https://github.com/junegunn/fzf/issues/1750)
 - change the [search mode](https://github.com/junegunn/fzf#search-syntax)
 
 Find more ideas and implementation tips in the [Cookbook](https://github.com/PatrickF1/fzf.fish/wiki/Cookbook).
 
-### Change the commands used to preview directories and regular files
+### Change how Search Directory previews directories and regular files
 
-The search directory feature, by default, calls `ls` to preview directories and `bat` to preview [regular files](https://stackoverflow.com/questions/6858452).
+[Search Directory][], by default, calls `ls` to preview directories and `bat` to preview [regular files](https://stackoverflow.com/questions/6858452).
 
-To change the directory preview command (e.g. to use one of the many `ls` replacements such as `exa`), set the command in the `fzf_preview_dir_cmd` variable:
+To change the directory preview command (e.g. to use one of the many `ls` replacements such as `exa`), set `fzf_preview_dir_cmd` to the desired command:
 
 ```fish
 set fzf_preview_dir_cmd exa --all --color=always
 ```
 
-And to change the file preview command (e.g. to `cat` to avoid installing a new dependency, or to add custom logic such as image preview), set the command in the `fzf_preview_file_cmd` variable:
+And to change the file preview command (e.g. to `cat` to avoid having to install `bat`, or to add logic for previewing images), set `fzf_preview_file_cmd` to the desired command:
 
 ```fish
-set fzf_preview_file_cmd cat
+set fzf_preview_file_cmd cat -n
 ```
 
-Omit the target path for both variables as `fzf.fish` will itself [specify the target to preview](functions/_fzf_preview_file.fish#L7).
+Omit the target path for both variables as `fzf.fish` will itself [specify the argument to preview](functions/_fzf_preview_file.fish).
 
-### Change the files searched
+### Change what files are listed in Search Directory
 
-To pass custom options to `fd` when it is executed to populate the list of files for the search directory feature, set the `fzf_fd_opts` variable. For example, to include hidden files but not `.git`, put this in your `config.fish`:
+To pass custom options to `fd` when it is executed to populate the list of files for [Search Directory][], set them in `fzf_fd_opts`. For example, to include hidden files but not `.git`:
 
 ```fish
 set fzf_fd_opts --hidden --exclude=.git
@@ -168,8 +170,8 @@ set fzf_fd_opts --hidden --exclude=.git
 Find answers to these questions and more in the [project Wiki](https://github.com/PatrickF1/fzf.fish/wiki):
 
 - How does `fzf.fish` [compare](https://github.com/PatrickF1/fzf.fish/wiki/Prior-Art) to other popular fzf plugins for Fish?
-- Why isn't this [feature working](https://github.com/PatrickF1/fzf.fish/wiki/Troubleshooting) for me?
-- How can I [customize](https://github.com/PatrickF1/fzf.fish/wiki/Cookbook) this feature?
+- Why isn't this [command working](https://github.com/PatrickF1/fzf.fish/wiki/Troubleshooting)?
+- How can I [customize](https://github.com/PatrickF1/fzf.fish/wiki/Cookbook) this command?
 - How can I [contribute](https://github.com/PatrickF1/fzf.fish/wiki/Contributing) to this plugin?
 
 [awesome badge]: https://awesome.re/mentioned-badge.svg
@@ -181,4 +183,5 @@ Find answers to these questions and more in the [project Wiki](https://github.co
 [fisher]: https://github.com/jorgebucaran/fisher
 [fzf]: https://github.com/junegunn/fzf
 [latest release badge]: https://img.shields.io/github/v/release/patrickf1/fzf.fish
+[search directory]: #-search-directory
 [var scope]: https://fishshell.com/docs/current/#variable-scope

functions/_fzf_configure_bindings_help.fish

@@ -1,24 +1,24 @@
 function _fzf_configure_bindings_help --description "Prints the help message for fzf_configure_bindings."
     echo "\
 USAGE:
-    fzf_configure_bindings [--FEATURE=[KEY_SEQUENCE]...]
+    fzf_configure_bindings [--COMMAND=[KEY_SEQUENCE]...]
 
 DESCRIPTION
-    fzf_configure_bindings installs key bindings for fzf.fish's features and erases any bindings it
+    fzf_configure_bindings installs key bindings for fzf.fish's commands and erases any bindings it
     previously installed. It installs bindings for both default and insert modes. fzf.fish executes
     it without options on fish startup to install the out-of-the-box key bindings.
 
-    By default, feature are bound to a mnemonic key sequence, shown below. Each feature's binding
+    By default, commands are bound to a mnemonic key sequence, shown below. Each command's binding
     can be configured using a namesake corresponding option:
-        FEATURE            |  DEFAULT KEY SEQUENCE         |  CORRESPONDING OPTION
-        Search directory   |  Ctrl+Alt+F (F for file)      |  --directory
-        Search git log     |  Ctrl+Alt+L (L for log)       |  --git_log
-        Search git status  |  Ctrl+Alt+S (S for status)    |  --git_status
-        Search history     |  Ctrl+R     (R for reverse)   |  --history
-        Search variables   |  Ctrl+V     (V for variable)  |  --variables
-        Search processes   |  Ctrl+Alt+P (P for process)   |  --processes
-    Override a feature's binding by specifying its corresponding option with the desired key
-    sequence. Disable a feature's binding by specifying its corresponding option with no value.
+        COMMAND            |  DEFAULT KEY SEQUENCE         |  CORRESPONDING OPTION
+        Search Directory   |  Ctrl+Alt+F (F for file)      |  --directory
+        Search Git Log     |  Ctrl+Alt+L (L for log)       |  --git_log
+        Search Git Status  |  Ctrl+Alt+S (S for status)    |  --git_status
+        Search History     |  Ctrl+R     (R for reverse)   |  --history
+        Search Variables   |  Ctrl+V     (V for variable)  |  --variables
+        Search Processes   |  Ctrl+Alt+P (P for process)   |  --processes
+    Override a command's binding by specifying its corresponding option with the desired key
+    sequence. Disable a command's binding by specifying its corresponding option with no value.
 
     Because fzf_configure_bindings erases bindings it previously installed, it can be cleanly
     executed multiple times. Once the desired fzf_configure_bindings command has been found, add it
@@ -30,9 +30,9 @@ DESCRIPTION
     Pass -h or --help to print this help message and exit.
 
 EXAMPLES
-    Default bindings but bind search directory to Ctrl+F and search variables to Ctrl+Alt+V
+    Default bindings but bind Search Directory to Ctrl+F and Search Variables to Ctrl+Alt+V
         \$ fzf_configure_bindings --directory=\cf --variables=\e\cv
-    Default bindings but disable search history
+    Default bindings but disable Search History
         \$ fzf_configure_bindings --history=
     An agglomeration of different options
         \$ fzf_configure_bindings --git_status=\cg --history=\ch --variables= --processes=