From d249084db5d90f006ac73b441c24a977bcf2e4b4 Mon Sep 17 00:00:00 2001 From: Tom Ryder Date: Tue, 11 Jun 2019 00:07:47 +1200 Subject: Lots more progress on documentating literate vimrc --- vim/vimrc | 549 +++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 350 insertions(+), 199 deletions(-) (limited to 'vim/vimrc') diff --git a/vim/vimrc b/vim/vimrc index d044ff74..013786f6 100644 --- a/vim/vimrc +++ b/vim/vimrc @@ -988,11 +988,9 @@ endtry " * Avoid shadowing any of Vim's existing functionality. If possible, extend " or supplement what Vim does, rather than replacing it. " - -" We'll start with the non-leader mappings. Ideally there shouldn't be too +" We'll start with the non-leader mappings. Ideally, there shouldn't be too " many of these. " - " I like using the space bar to scroll down a page, so I can lazily tap it to " read documents, and I find its default behaviour of moving right one " character to be useless. @@ -1101,322 +1099,475 @@ endif imap \ (DigraphSearch) -" Stack Ctrl-L to clear search highlight, make it work in insert mode too +" I end up hitting CTRL-L to clear or redraw the screen in interactive shells +" and tools like Mutt and Vim pretty often. It feels natural to me to stack +" issuing a :nohlsearch command to stop highlighting searches on top of this. +" +" This gets by far the most use in normal mode, but I'd like it to work in +" visual and insert mode, too, where it's occasionally useful, especially on +" things like mobile phone terminal emulators that can be choppy and require +" a lot of redrawing. +" +" For each of these, we end the mapping with a CTRL-L in normal mode, thereby +" extending rather than replacing Vim's normal behaviour. +" nnoremap \ :nohlsearch + +" We use :vnoremap rather than :xnoremap and thereby make the mapping apply to +" select mode as well, because CTRL-L doesn't reflect a printable character, +" and so we may as well, even though I never use select mode directly. +" vnoremap \ :nohlsearchgv + +" The insert mode mapping uses CTRL-O to issue a single normal normal-mode +" command, but twice: once to issue the :nohlsearch command, and then once to +" issue an unmapped normal-mode CTRL-L. +" inoremap \ :nohlsearch -" Remap normal/visual & and g& to preserve substitution flags +" By default, the very-useful normal mode command '&' that repeats the +" previous :substitute command doesn't preserve the flags from that +" substitution. I'd prefer it to do so, like the :&& command does, and it's +" easily remapped for both normal and visual mode, so let's just do it. +" nnoremap & \ :&& xnoremap & \ :&& -nnoremap g& - \ :%&& -" Map g: as a 'colon operator' +" I really like using the '!' command in normal mode as an operator to filter +" text through a shell command. It always bugged me a little that there +" didn't seem to be an analogue for a motion to filter text through an +" internal command like :sort, so I wrote one. +" nmap g: \ (ColonOperator) -" Cycle through argument list +" I used Tim Pope's unimpaired.vim plugin for ages, and I liked some of these +" bracket pair mappings, so I've carried a few of the simpler ones over. All +" of these can be prefixed with a count if needed, too. I use all of them +" pretty regularly, even though cycling through lists to look for something +" can be a bit wasteful. +" + +" Argument list nnoremap [a \ :previous nnoremap ]a \ :next -" Cycle through buffers +" Buffers nnoremap [b \ :bprevious nnoremap ]b \ :bnext -" Cycle through quickfix list items +" Quickfix list nnoremap [c \ :cprevious nnoremap ]c \ :cnext -" Cycle through location list items +" Location list nnoremap [l \ :lprevious nnoremap ]l \ :lnext -" Insert blank lines around current line +" Here's another mapping I particularly liked from unimpaired.vim here; insert +" blank lines from normal mode, using a custom plugin of mine called +" put_blank_lines.vim. These use operator functions so that they're +" repeatable without repeat.vim. They accept count prefixes, too. +" nmap [ \ (PutBlankLinesAbove) nmap ] \ (PutBlankLinesBelow) -" Set leader keys +" We're on to the leader maps, now. It's difficult to know what order to put +" these in; I originally had them in alphabetical order, but it seems more +" useful now to group the by the category of their function, albeit roughly. +" +" First of all, let's set the leader keys; backslash happens to be the +" default, but I like to make my choice explicit here. +" +" As of 2019, I'm still not certain that comma is the best choice for my local +" leader. I use it all the time for this purpose, and it works well, but +" I don't much like that it shadows a useful function in the fFtT;, group, and +" wonder if I would use it more if I hadn't shadowed it. +" let mapleader = '\' let maplocalleader = ',' -" Leader,a toggles 'formatoptions' 'a' flag using a plugin -nnoremap a - \ :ToggleFlagLocal formatoptions a - -" Leader,b toggles settings friendly to copying and pasting -nmap b - \ (CopyLinebreakToggle) +" Let's start with some simple ones; these ones all just toggle a boolean +" option, and print its new value. They're dirt simple to specify, and don't +" require any plugins. +" +" These are sometimes applicable in visual mode, and sometimes not. We'll +" start with the ones that only make sense as normal mode maps. Interesting, +" a visual mode mapping for 'cursorline' toggling doesn't work at all; +" 'cursorline' is always off when in any visual mode, including block mode, +" where it actually might have been really handy. -" Leader,c toggles 'cursorline'; no visual mode map as it doesn't work +"" Leader,TAB toggles automatic indentation based on the previous line +nnoremap + \ :setlocal autoindent! autoindent? +"" Leader,c toggles highlighted cursor row; doesn't work in visual mode nnoremap c \ :setlocal cursorline! cursorline? -" Leader,C toggles 'cursorcolumn'; works in visual mode +"" Leader,h toggles highlighting search results +nnoremap h + \ :set hlsearch! hlsearch? +"" Leader,i toggles showing matches as I enter my pattern +nnoremap i + \ :set incsearch! incsearch? +"" Leader,s toggles spell checking +nnoremap s + \ :setlocal spell! spell? + +" The next group of option-toggling maps are much the same as the previous +" group, except they also include analogous maps for visual mode, defined as +" recursive maps into normal mode that conclude with re-selecting the text. + +"" Leader,C toggles highlighted cursor column; works in visual mode nnoremap C \ :setlocal cursorcolumn! cursorcolumn? -xnoremap C - \ :setlocal cursorcolumn! cursorcolumn?gv +xmap C + \ Cgv +"" Leader,l toggles showing tab, end-of-line, and trailing white space +nnoremap l + \ :setlocal list! list? +xmap l + \ lgv +"" Leader,n toggles line number display +nnoremap n + \ :setlocal number! number? +xmap n + \ ngv +"" Leader,N toggles position display in bottom right +nnoremap N + \ :set ruler! ruler? +xmap N + \ Ngv +"" Leader,p toggles paste mode +nnoremap p + \ :set paste! paste? +xmap p + \ pgv +"" Leader,w toggles soft wrapping +nnoremap w + \ :setlocal wrap! wrap? +xmap w + \ wgv -" Insert an RFC2822-compliant date string into the buffer -command! -range PutDate - \ put =strftime('%a, %d %b %Y %T %z') +" This next one just shows option state of the 'formatoptions' affecting how +" text is automatically formatted; it doesn't change its value. + +"" Leader,f shows the current 'formatoptions' at a glance +nnoremap f + \ :setlocal formatoptions? + +" I often have to switch between US English and NZ English. The latter is +" almost exactly the same as UK English in most locales, although we use +" dollars rather than pounds. This is mostly so I remember things like +" excluding or including the 'u' in words like 'favourite', depending on the +" target audience. I generally use US English for international audiences. + +"" Leader,u sets US English spelling language +nnoremap u + \ :setlocal spelllang=en_us +"" Leader,z sets NZ English spelling language +nnoremap z + \ :setlocal spelllang=en_nz + +" The next mapping is another option toggler, but it's more complicated; it +" uses a simple plugin of mine called copy_linebreak.vim to manage several +" options at once, related to the 'wrap' option that soft-wraps text. +" +" It's designed for usage in terminal emulators and multiplexers to +" temporarily make the buffer text suitable for copying in such a way that the +" wrapping and any associated soft formatting won't pervert the text, +" including 'breakindent', 'linebreak', and 'showbreak' artifacts. +" +" This is really handy for quick selections of small regions of text. For +" larger blocks of text or for programatically manipulating the text as it +" leaves the buffer, it makes more sense to use :! commands. +" + +"" Leader,b toggles settings friendly to copying and pasting +nmap b + \ (CopyLinebreakToggle) + +" The above mappings show that mappings for toggling boolean options are +" simple, but there isn't a way to toggle single flags within option strings, +" so I wrote a plugin called toggle_flags.vim to provide :ToggleFlag and +" :ToggleFlagLocal commands. The first argument is the name of an option, and +" the second is the flag within it that should be toggled on or off. + +"" Leader,a toggles 'formatoptions' 'a' auto-flowing flag +nnoremap a + \ :ToggleFlagLocal formatoptions a +"" Leader,L toggles 'colorcolumn' showing the first column beyond 'textwidth' +nnoremap L + \ :ToggleFlagLocal colorcolumn +1 +xmap L + \ Lgv + +" These mappings are for managing filetypes. The first one uses the +" :FileTypeReload command that was defined much earlier in this file.for +" a vimrc reload hook. + +"" Leader,F reloads filetype plugins +nnoremap F + \ :FileTypeReload +"" Leader,t shows current filetype +nnoremap t + \ :setlocal filetype? +"" Leader,T clears filetype +nnoremap T + \ :setlocal filetype= " Set up a quick command-function pair to run a command with the UTC timezone, -" in this case, for my date-printing mappings. Is there a nicer way to do -" this? I couldn't find one. +" in this case, for my date-printing mappings. To do this, we define two new +" commands, one of which uses a script-local function. +" +" While this is a tidy way to abstract the operation for the map, I don't like +" the function implementation much at all. It works OK in stable versions of +" Vim, but changing an environment variable just long enough to affect the +" outcome of a command as a side effect seems a bit gross. +" +" Worse, the whole thing presently seems to be broken in v8.1.1487; the +" timezone first chosen seems to 'stick' permanently, and the mapping each +" produce timestamps in that zone. I haven't worked out why this happens yet. +" Using the new getenv() and setenv() functions does not seem to fix it. It +" works fine in Debian GNU/Linux's packaged v8.0.x. + +" First, of all, we define a :PutDate command that inserts a line into the buffer with +" an RFC-2822 date string, using the system strftime() implementation. This +" might be useful outside of the vimrc, too; we allow it to accept a range +" which defaults to the current line. " -" This presently seems to be broken in v8.1.1487; the timezone first chosen -" seems to 'stick' permanently. I haven't worked out why yet. Using the new -" getenv() and setenv() functions does not seem to fix it. It works fine in -" Debian GNU/Linux's packaged v8.0.x. +command! -range PutDate + \ put =strftime('%a, %d %b %Y %T %z') + +" Next, we define a :UTC command wrapper, implemented with a script-local +" function of the same name. We use expand('$TZ') to ensure we're getting the +" value of the current timezone from the environment, and cache that in +" a local variable just long enough to manipulate the environment into using +" UTC for a command, in our case, the newly-defined :PutDate command. " function! s:UTC(command) abort let tz = expand('$TZ') let $TZ = 'UTC' | execute a:command | let $TZ = tz endfunction + +" The :UTC command itself completes another command name, and accepts one +" required argument, which it passes in quoted form to the helper function. +" command! -complete=command -nargs=1 UTC \ call s:UTC() -" Leader,d inserts the local date (RFC 2822) +" And finally, we define the maps that actually use the commands. + +"" Leader,d inserts the local date (RFC 2822) nnoremap d \ :PutDate -" Leader,D inserts the UTC date (RFC 2822) +"" Leader,D inserts the UTC date (RFC 2822) nnoremap D \ :UTC PutDate -" Leader,e forces a buffer to be editable -nnoremap e - \ :setlocal modifiable noreadonly - -" Leader,f shows the current 'formatoptions' at a glance -nnoremap f - \ :setlocal formatoptions? - -" Leader,F reloads filetype plugins -nnoremap F - \ :FileTypeReload +" This group contains mappings that are to do with file and path management +" relative to the current buffer. -" Leader,g shows the current file's fully expanded path +"" Leader,g shows the current file's fully expanded path nnoremap g \ :echo expand('%:p') -" Leader,G changes directory to the current file's location +"" Leader,G changes directory to the current file's location nnoremap G \ :cd %:hpwd +"" Leader,P creates the path to the current file +nnoremap P + \ :call mkdir(expand('%:h'), 'p') -" Leader,h toggles highlighting search results -nnoremap h - \ :set hlsearch! hlsearch? +" This group contains mappings that show information about Vim's internals: +" marks, registers, variables, and the like. -" Leader,H shows command history +"" Leader,H shows command history nnoremap H \ :history : - -" Leader,i toggles showing matches as I enter my pattern -nnoremap i - \ :set incsearch! incsearch? - -" Leader,j jumps to buffers ("jetpack") -nnoremap j - \ :buffers:buffer - -" Leader,k shows my marks +"" Leader,k shows my marks nnoremap k \ :marks - -" Leader,l toggles showing tab, end-of-line, and trailing white space -nnoremap l - \ :setlocal list! list? -xnoremap l - \ :setlocal list! list?gv - -" Leader,L toggles 'colorcolumn' showing 'textwidth' -nnoremap L - \ :ToggleFlagLocal colorcolumn +1 -xnoremap L - \ :ToggleFlagLocal colorcolumn +1gv - -" Leader,m shows normal maps +"" Leader,m shows normal maps nnoremap m \ :map -" Leader,M shows buffer-local normal maps +"" Leader,M shows buffer-local normal maps nnoremap M \ :map - -" Leader,n toggles line number display -nnoremap n - \ :setlocal number! number? -xnoremap n - \ :setlocal number! number?gv -" Leader,N toggles position display in bottom right -nnoremap N - \ :set ruler! ruler? -xnoremap N - \ :set ruler! ruler?gv - -" Leader,o opens a line below in paste mode -nmap o - \ (PasteOpenBelow) -" Leader,O opens a line above in paste mode -nmap O - \ (PasteOpenAbove) - -" Leader,p toggles paste mode -nnoremap p - \ :set paste! paste? - -" Leader,P creates the path to the current file -nnoremap P - \ :call mkdir(expand('%:h'), 'p') - -" Leader,q formats the current paragraph -nnoremap q - \ gqap - -" Leader,r acts as a replacement operator -nmap r - \ (ReplaceOperator) -xmap r - \ (ReplaceOperator) - -" Leader,R reloads ~/.vimrc -nnoremap R - \ :source $MYVIMRC - -" Leader,s toggles spell checking -nnoremap s - \ :setlocal spell! spell? - -" Leader,S shows loaded scripts +"" Leader,S shows loaded scripts nnoremap S \ :scriptnames - -" Leader,t shows current filetype -nnoremap t - \ :setlocal filetype? -" Leader,T clears filetype -nnoremap T - \ :setlocal filetype= - -" Leader,u sets US English spelling (compare Leader,z) -nnoremap u - \ :setlocal spelllang=en_us - -" Leader,v shows all global variables +"" Leader,v shows all global variables nnoremap v \ :let g: v: -" Leader,V shows all local variables +"" Leader,V shows all local variables nnoremap V \ :let b: t: w: +"" Leader,y shows all registers +nnoremap y + \ :registers -" Leader,w toggles wrapping -nnoremap w - \ :setlocal wrap! wrap? -xnoremap w - \ :setlocal wrap! wrap?gv +" This group contains mappings concerned with buffer navigation and +" management. I use the "jetpack" buffer jumper one like crazy; I really like +" it. I got it from one of bairui's "Vim and Vigor" comics: +" +" + +"" Leader,DEL deletes the current buffer +nnoremap + \ :bdelete +"" Leader,INS edits a new buffer +nnoremap + \ :enew +"" Leader,e forces a buffer to be editable, even a :help one +nnoremap e + \ :setlocal modifiable noreadonly +"" Leader,E locks a buffer, reversible with e +nnoremap e + \ :setlocal nomodifiable readonly +"" Leader,j jumps to buffers ("jetpack") +nnoremap j + \ :buffers:buffer + +" Filtering and batch operations to clean up buffer text -" Leader,x strips trailing whitespace via a custom plugin +"" Leader,x strips trailing whitespace via a custom plugin nnoremap x \ :StripTrailingWhitespace xnoremap x \ :StripTrailingWhitespace - -" Leader,X squeezes repeated blank lines via a custom plugin +"" Leader,X squeezes repeated blank lines via a custom plugin nnoremap X \ :SqueezeRepeatBlanks xnoremap X \ :SqueezeRepeatBlanks - -" Leader,y shows all registers -nnoremap y - \ :registers - -" Leader,z sets NZ English spelling (compare Leader,u) -nnoremap z - \ :setlocal spelllang=en_nz - -" Leader,= runs the whole buffer through =, preserving position +"" Leader,= runs the whole buffer through =, preserving position nnoremap = \ :KeepPosition normal! 1G=G -" Leader,+ runs the whole buffer through gq, preserving position +"" Leader,+ runs the whole buffer through gq, preserving position nnoremap + \ :KeepPosition normal! 1GgqG -" Leader,. runs the configured make program into the location list -nnoremap . - \ :lmake! - -" Leader,< and Leader,> adjust indent of last edit; good for pasting -nnoremap - \ :'[,'] -nnoremap > - \ :'[,']> +" This group defines a few :onoremap commands to make my own text objects. +" I should probably make some more of these, as they've proven to be +" terrifically handy. -" Leader,_ uses last changed or yanked text as an object +"" Leader,_ uses last changed or yanked text as an object onoremap _ \ :normal! `[v`] - -" Leader,% uses entire buffer as an object +"" Leader,% uses entire buffer as an object onoremap % \ :normal! 1GVG -" Leader,{ and Leader,} move to lines with non-space chars before current column +" This group defines some useful motions. + +"" Leader,{ and Leader,} move to lines with non-space chars before current column map { \ (VerticalRegionUp) sunmap { map } \ (VerticalRegionDown) sunmap } +"" Leader,\ jumps to the last edit position mark: think "Now, where was I?" +nnoremap \ + \ `" +xnoremap \ + \ `" + +" This group does both: useful motions on defined text objects. -" Leader,/ types :vimgrep for me ready to enter a search pattern +"" Leader,< and Leader,> adjust indent of last edit; good for pasting +nnoremap + \ :'[,'] +nnoremap > + \ :'[,']> + +" This group is for directory tree or help search convenience mappings. + +"" Leader,/ types :vimgrep for me ready to enter a search pattern nnoremap / \ :vimgrep /\c/j ** -" Leader,? types :lhelpgrep for me ready to enter a search pattern +"" Leader,? types :lhelpgrep for me ready to enter a search pattern nnoremap ? \ :lhelpgrep \c -" Leader,* escapes regex metacharacters +" This group contains miscellaneous mappings for which I couldn't find any +" other place. The plugin mappings probably require their own documentation +" comment block, but my hands are getting tired from all this typing. + +"" Leader,. runs the configured make program into the location list +nnoremap . + \ :lmake! +"" Leader,o opens a line below in paste mode +nmap o + \ (PasteOpenBelow) +"" Leader,O opens a line above in paste mode +nmap O + \ (PasteOpenAbove) +"" Leader,q formats the current paragraph +nnoremap q + \ gqap +"" Leader,r acts as a replacement operator +nmap r + \ (ReplaceOperator) +xmap r + \ (ReplaceOperator) +"" Leader,* escapes regex metacharacters nmap * \ (RegexEscape) xmap * \ (RegexEscape) -" Leader,\ jumps to the last edit position mark, like g;, but works as a motion -" "Now, where was I?" (tap-tap) -nnoremap \ - \ `" -xnoremap \ - \ `" - -" Leader,DEL deletes the current buffer -nnoremap - \ :bdelete -" Leader,INS edits a new buffer -nnoremap - \ :enew +" And last, but definitely not least, I'm required by Vim fanatic law to +" include a mapping that reloads my whole configuration. Doing this triggers +" the #vimrc#SourceCmd hooks defined much earlier in the file so that +" filetypes get reloaded afterwards, so I don't need to follow R with +" a F. -" Leader,TAB toggles 'autoindent' -nnoremap - \ :setlocal autoindent! autoindent? - -" Some useful abbreviations -inoreabbrev tr@ tom@sanctum.geek.nz -inoreabbrev tr/ +"" Leader,R reloads ~/.vimrc +nnoremap R + \ :source $MYVIMRC -" THe things I almsot always type wrnog -inoreabbrev almsot almost -inoreabbrev wrnog wrong -inoreabbrev Fielding Feilding -inoreabbrev THe The -inoreabbrev THere There +" I'll close this file with a few abbreviations. Perhaps of everything in +" here, I'm least confident that these should be in here, but they've proven +" pretty useful. First, some 'deliberate' abbreviations for stuff I type +" a lot: +" +inoreabbrev tr@ + \ tom@sanctum.geek.nz +inoreabbrev tr/ + \ + +" And then, just fix some typographical and spelling errors for me +" automatically. +" +inoreabbrev almsot + \ almost +inoreabbrev wrnog + \ wrong +inoreabbrev Fielding + \ Feilding +inoreabbrev THe + \ The +inoreabbrev THere + \ There + +" Here endeth the literate vimrc. +" +" > Consequently, it is soon recognised that they write for the sake of +" > filling up the paper, and this is the case sometimes with the best +" > authors; for example, in parts of Lessing’s Dramaturgie, and even in many +" > of Jean Paul’s romances. As soon as this is perceived the book should be +" > thrown away, for time is precious. +" > -- Schopenhauer +" -- cgit v1.2.3