From c4b30fbb932bd3ec1e3f33c9924b1f354c725622 Mon Sep 17 00:00:00 2001 From: Damien Dart Date: Fri, 16 Feb 2024 22:04:24 +0000 Subject: [PATCH] Do some documentation-updatin'. --- .config/nvim/init.vim | 2 +- .vim/doc/toolbox.txt | 41 +++++++++++++++++++--------------- .vim/plugin/fuzzy-files.vim | 12 +++------- .vim/plugin/fuzzy-grep.vim | 14 +++--------- .vim/plugin/fuzzy-snippets.vim | 4 +++- .vim/plugin/plugins.vim | 2 +- .vimrc | 11 +++++---- README.md | 31 ++++++++++++++++--------- 8 files changed, 62 insertions(+), 55 deletions(-) diff --git a/.config/nvim/init.vim b/.config/nvim/init.vim index 6ec581a..b7089d5 100644 --- a/.config/nvim/init.vim +++ b/.config/nvim/init.vim @@ -1,6 +1,6 @@ " Damien Dart's "init.vim" for Neovim. " -" See also "$HOME/.vimrc". +" See also "$TOOLBOX_ROOT/.vimrc". " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/.vim/doc/toolbox.txt b/.vim/doc/toolbox.txt index f596e59..8f97aca 100644 --- a/.vim/doc/toolbox.txt +++ b/.vim/doc/toolbox.txt @@ -11,28 +11,31 @@ d8888P .d8888b. .d8888b. 88 88d888b. .d8888b. dP. .dP ~ ============================================================================== CONTENTS *toolbox-contents* - 1. Introduction ............................................. |toolbox| - 2. Fuzzy-finders ...................................... |toolbox-fuzzy| - 3. Notetaking gubbins ................................. |toolbox-notes| - 4. Miscellaneous ....................................... |toolbox-misc| + 1. Introduction .............................................. |toolbox| + 2. Fuzzy-finders ....................................... |toolbox-fuzzy| + 3. Notetaking gubbins .................................. |toolbox-notes| + 4. Miscellaneous ........................................ |toolbox-misc| ============================================================================== INTRODUCTION *toolbox* -The following a brief overview of the custom Vim functionality provided by -Damien Dart's dotfiles. +The following is a little cheat-sheet for some of the more frequently-used +Vim gubbins provided by my dotfiles. For more information about anything else, +please have a look at the individual dotfiles. ============================================================================== FUZZY-FINDERS *toolbox-fuzzy* -The following fuzzy finders require `fzf` and `fzf.vim`. +The following fuzzy-finders require `fzf` and `fzf.vim` (for more information, see +). *:FF* *:FF!* :FF[!] {query} Opens a simple fzf-powered file browser and selector, using {query} as the initial query if provided. - Requires `ripgrep`. + Requires `ripgrep` (for more information see + ). If the current working directory is within a Git repository, the search will start from the repository @@ -58,7 +61,8 @@ The following fuzzy finders require `fzf` and `fzf.vim`. *:FG* *:FG!* :FG[!] {query} Opens a fzf-powered interactive ripgrep doohickey using {query} as the initial query if provided. - Requires `ripgrep`. + Requires `ripgrep` (for more information see + ). If the current working directory is within a Git repository, ripgrep will run from the repository root. @@ -109,15 +113,15 @@ The following fuzzy finders require `fzf` and `fzf.vim`. *:FS* :FS {query} Opens a fzf-powered snippets browser and selector, using {query} as the initial query if provided. - Requires `fuzzy-snippet` and `snippet-placeholder`. + Requires `fuzzy-snippet` from `toolbox`, and + `snippet-placeholder` (for more information, see + ). - `fuzzy-snippet` is used to get a list of available - snippets. For more information, run - fuzzy-snippets --help` in the command-line. - - `snippet-placeholder` is used to expand placeholder - content in snippets. For more information, run -` snippet-placeholder --help` in the command-line. + Snippets are passed through `snippet-placeholder` to + expand placeholder content in snippets. For more + information on available placeholder content, see + `snippet-placeholder`'s help text by running + `snippet-placeholder --help` in the command-line. When in fzf, only a single snippet can be selected. The following keyboard shortcuts are available: @@ -163,7 +167,8 @@ MISCELLANEOUS *toolbox-misc* {Visual}bd cursor (the 'iskeyword' setting is temporarily adjusted to allow all of the Base64 alphabet). In Visual mode, decodes the highlighted Base64 string. - Requires the `base64` command. + Requires the `base64` command, provided by the GNU Core + Utilities (and others). *be* *v_be* be Encodes the text under the cursor or any highlighted diff --git a/.vim/plugin/fuzzy-files.vim b/.vim/plugin/fuzzy-files.vim index 1770729..01bf89a 100644 --- a/.vim/plugin/fuzzy-files.vim +++ b/.vim/plugin/fuzzy-files.vim @@ -1,14 +1,8 @@ " A simple fzf-powered file browser and selector. " -" - By default, the search will start from the current working -" directory. If the current working directory is within a Git -" repository, the search will instead start from the repository root. -" - Ignore files (e.g. ".gitignore") in the search root directory are -" respected. -" - The bang modifier works in a similar fashion to when using it with -" the ":edit" command: it forces the editing of files even when there -" are are changes to the current buffer. -" - See the fzf prompt header for available actions. +" For more information, see "$TOOLBOX_ROOT/.vim/doc/toolbox.txt" (or +" search for "toolbox-fuzzy" using Vim's help functionality if the help +" tags file for "toolbox.txt" has been generated). " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/.vim/plugin/fuzzy-grep.vim b/.vim/plugin/fuzzy-grep.vim index 4ee4856..2ddeec2 100644 --- a/.vim/plugin/fuzzy-grep.vim +++ b/.vim/plugin/fuzzy-grep.vim @@ -1,16 +1,8 @@ " A simple fzf-powered interactive grep/ripgrep doohickey. " -" - The ":FG" command will respect ignore files (e.g. ".gitignore") in -" the search root directory, whereas ":FGA" will search every file. -" - By default, ripgrep will run from the current working directory. If -" the current working directory is within a Git repository, ripgrep -" will instead run from the repository root. -" - Changing the query will rerun ripgrep using the new query instead of -" filtering the initial input. -" - The bang modifier works in a similar fashion to when using it with -" the ":edit" command: it forces the editing of files even when there -" are are changes to the current buffer. -" - See the fzf prompt header for available actions. +" For more information, see "$TOOLBOX_ROOT/.vim/doc/toolbox.txt" (or +" search for "toolbox-fuzzy" using Vim's help functionality if the help +" tags file for "toolbox.txt" has been generated). " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/.vim/plugin/fuzzy-snippets.vim b/.vim/plugin/fuzzy-snippets.vim index e70c3c6..4d13560 100644 --- a/.vim/plugin/fuzzy-snippets.vim +++ b/.vim/plugin/fuzzy-snippets.vim @@ -1,6 +1,8 @@ " A Vim-orientated version of "$TOOLBOX_ROOT/bin/fuzzy-snippets". " -" See the fzf prompt header for available actions. +" For more information, see "$TOOLBOX_ROOT/.vim/doc/toolbox.txt" (or +" search for "toolbox-fuzzy" using Vim's help functionality if the help +" tags file for "toolbox.txt" has been generated). " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/.vim/plugin/plugins.vim b/.vim/plugin/plugins.vim index febedea..73649f9 100644 --- a/.vim/plugin/plugins.vim +++ b/.vim/plugin/plugins.vim @@ -3,7 +3,7 @@ " For more information on the standard plugins distributed with Vim, see " . " -" See also "$HOME/.vim/after/plugin/plugins.vim". +" See also "$TOOLBOX_ROOT/.vim/after/plugin/plugins.vim". " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/.vimrc b/.vimrc index fc4b54a..337b973 100644 --- a/.vimrc +++ b/.vimrc @@ -1,6 +1,6 @@ " Damien Dart's ".vimrc". " -" This file should only contain simple configuration gubbins; anything +" This file should only contain simple configuration stuff; anything " more complex should get shipped off to self-contained files in " "$TOOLBOX_ROOT/.vim/" (use "gf" to edit or view these files): " @@ -15,10 +15,13 @@ " - "$TOOLBOX_ROOT/.vim/plugin/fzf.vim" " - "$TOOLBOX_ROOT/.vim/plugin/plugins.vim" " -" Everything here and in "$HOME/.vim/" should also work in Neovim. +" (For more information about this organisation approach, please see +" .) " -" For more information about this organisation approach, please see -" . +" A cheat-sheet for some of the more frequently-used custom +" functionality is available at "$TOOLBOX_ROOT/.vim/doc/toolbox.txt" (or +" search for "toolbox" using Vim's help functionality if the help tags +" file for "toolbox.txt" has been generated). " " This file was written by Damien Dart, . This is " free and unencumbered software released into the public domain. For diff --git a/README.md b/README.md index 6bd7ad4..a55c00a 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,32 @@ toolbox ======= -My dotfiles and random scripts of varying quality. +My dotfiles and utility scripts of varying quality. They’re reasonably +well documented and organised, so spelunking is encouraged. Feel free to +use whatever you find useful here for your own use. -Once a copy of this repository has been downloaded with Git: +To get set up: -1. Ensure that any [Git submodules][], currently used to manage - third-party Vim plugins, are initialised and updated. -2. Run the `install` script in the repository root to create the - relevant symlinks in your home directory. +1. Use Git to download a copy of the *toolbox* repository, ensuring + that any [Git submodules][] (currently used to manage third-party + Vim plugins) are also initialised and updated. +2. Run the `install` script located in the repository root to create + the relevant symlinks in your home directory. +3. In Vim, run `:helptags ~/.vim/doc` to generate the help tags file + for the *toolbox* Vim cheat sheet. + +The `install` script doesn’t install third-party dependencies, as I have +[Ansible playbooks and stuff][] for that. [Git submodules]: + [Ansible playbooks and stuff]: -## See also +## Related projects -- [setup][], stuff and things that I use to provision and maintain, - among other things, my personal and work development environments. +- [nt][]: a note-taking helper application for the command line. +- [snippets][]: a bunch of reusable snippets and a little doohickey to + replace placeholder content. - [setup]: + [nt]: + [snippets]: