aboutsummaryrefslogblamecommitdiff
path: root/vim/vimrc
blob: 0424fca20cd68b3b4bc1dacf142f56c1268aa588 (plain) (tree)
1
2
3
4
5
6


                                                                                                           
 
                                             
 






                                                      

                 
 




                                                            
 


                                                                          
 
                                                                 

                                             


                                                                           


                      
                                                                                 
                                                                        



































                                                                                       
 
                    



                                               
     


                                                                         
                                                                           

                                                                              
 




                                                                              
 

                                                                             
 
                                                                             
 

                                                                        


                                                                              
                              
                                              
 
                                                                              


                                                                              
 
                                                        
 
                                                                            


                                                                             

                                                                             
 

                               
     
                                          
 

                                                                          
 

                                                                                          




                                                                              

                                                                          
                                            
 











                            



                                                                              








                                                                              
 

                                                               
                                                     
                 

                                                            
             
                                     

                                                     
                         

                                                            
              
                                                
                 
     
 
                                                                              

                                                                             
                                                            
 



                                                                           
 
                                                    

                                         
       
                                        
                                       
          
     

                                                                             







                                                                             






























                                                                                  
          
                                                    

                                                   
       
                                                             
                                                                  
           
     


                                                                             


                                                                              
 
              

                                                                             





                                                                                 


                                                       
                        

                   







                                                                  





                                             
                                 
                                                      






                                                                        
     




                                                                            

                                                                      
                                                    

                                                 
       
                                                             
                                  
           
     





                                                                             


                                                                                



                                                                              
                                                                              
              

                                                 
       
                                                           
                                  
           
     
 




                                                                              
                                                                        

                                                 
       
                                                          
                                
           

     


                                                                           
                         



                                                                             
                                    
 
                            
                              




                                                                            




                                                                              
 
                         
                           




                                                                            

             
           





                                                                              
                                                
                   







                                                                          
                        
                                               

                     


                                                                           
                                  
 
                   






                                                                                     

                                                                          
 
                                                 
 










                                                                             











                                                                                

                                                                            
 
                                     

                                                           

                                                    

                                                        


                                                         










                                                                                

                                                           
                                                   
                 

                                                        
             

                                                        
     





























                                                                                 
                                             
                      
 












                                                                               
             












                                                                                
                             



                   
















                                                                                
                         

                 




                                                                            
           










                                                                                
             
 




                                                                        







                                                                                      
                                                                                     

                                                                    
                    
 
                                                                                        
                                                                            

                                                                                 

                                                         
                    














                                                                                  
                    
                      
     















                                                                                     
                








                                                                                



                                                                              






                                                                                 
                    
                      
     








                                                                                  
                     

                   

















                                                                               
          





                                                                             
            
          







                                                                              
             



                                                                             
              


























                                                                             
                             
                                       
    
                                     
     









                                                                                  
              




                                                                            
                    








                                                                             
           













                                                                                
             











                                                                                
                
 





                                                                               
                         
 






                                                                             
                            

             









                                                                                
             






                                                                               
                      













                                                                                  
                    









                                                                                

                              





                                                                              
                                                                           






                                                                             
                                                               











                                                             
                                                                                   






                                                                               






                                                                              
 













                                                                              


                                                    

                            
     





















                                                                                


                       








                                                                                


                                                                                


                                                    
                           
                                                                    




                                                                              
                                                   

                     




                                                                              
                         
                                               
                                                             
                    
     
















                                                                              
                                                                             

                                   
                                                       


















                                                                                

                    







                                                                              
                       
                              

                              
 






























                                                                                  

                             












                                                                               

                                 






                                                                                     

                                         
 



                                                                            
 

                    





                                                                                
         
               

        







                                                                                 

                             







                                                                               



                     
         



                      
               



                      
               



                      







                                                                           



                                  











                                                                                

                        




                                                                           
                         

            

           











                                                                                 

                                             
                                                                         

                                             
                                               

                                         
                                                         

                                           
                                  
                  
                                   





                                                                            
                 
                                                 

                
                                                                      
                 
                                 

                
                                       
                 
                                     

                
                                                    
                 
                                   

                
                                 
                 
                                 

                




                                                                            
                  
                                    



                                                                          
                                                                                    

                                                                           
                  
                                     
                  
                                     

















                                                                               

                                   








                                                                              

                                                 
                                                                             
                 
                                                

                






                                                                              

                         





                                                                        
                  
                                
                                  
                  
                               
                           
                  
                               




                                                                       
                  
                    
                                           
                  
                     

                                                                           
                                 

                                                          

                                    
                                                              
                  
                                  
                                                                      
                  
                                                




                                                                             

                           
                          

                       
                           

                          
                             
                  
                      
                                          
                  
                               
                                

                             
                               

                         
                                                   

                           
                                                             

                              
                               

                           

                                                                   

                                                                                  



                                                               

                         
                                

                         
                                                            
                  
                                           
                                                     
                  
                                           
                                                

                                       






                                                                              

                              












                                                                            
                 
                                    

                

                                         
                 
                                

                
                                                                
                  
                                                     
                                                                 
                  
                                                      





                                                                          
                  
                                         
                                                       
                  
                                        

                 







                                                                        

                                
                

                                  
                
                                                                               

                 
                



                                                                     



                           



                                                                       

                                                     
                                                                   

                                  











                                                                            

                        
                                         

                  
                                          

                               
                

                                                     

                                 

                 
                                                                        



                                 
                                          

                           

                

                 

                



                                                

                                                                            

                 
                                                      
                  
                               
                                                    
                  
                                        
 




                                                                              





                                                                              
                  
                             





                                                                                



                                  



                                                                            





                    



                      



                 


                                                     





                                                                            
 
" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"  Tom Ryder (tejr)’s Literate Vimrc
" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"
" Last updated: Thu, 19 Nov 2020 07:55:42 UTC
"
" │ And I was lifted up in heart, and thought
" │ Of all my late-shown prowess in the lists,
" │ How my strong lance had beaten down the knights,
" │ So many and famous names; and never yet
" │ Had heaven appeared so blue, nor earth so green,
" │ For all my blood danced in me, and I knew
" │ That I should light upon the Holy Grail.
"
"     —Tennyson
"
" │ your vimrc is better than the bible
"
"     —@polanco@mastodon.sdf.org
"     <https://mastodon.sdf.org/@polanco/104069285780040986>
"

" This file is an attempt at something like a “literate vimrc”, in the
" tradition of Donald Knuth’s “literate programming”:
" <http://www.literateprogramming.com/>
"
" The dotfiles project as part of which it is maintained is here:
" <https://sanctum.geek.nz/cgit/dotfiles.git>
"
" This is a long file, and comments abound.  Should this be bothersome, one
" could execute this command in Vim itself, to strip out comment blocks and
" blank lines:
"
"     :g/\m^$\|^\s*"/d
"
" This file should be saved as ‘vimrc’—note no leading period—in the user
" runtime directory.  On GNU/Linux, Mac OS X, and BSD, that directory is
" ‘~/.vim’.  On Windows, it’s ‘~/vimfiles’.  It requires Vim v7.0.0 or newer,
" including the +eval feature, and with the 'compatible' option turned off.
" That's to allow line continuations.  The vimrc stub at ~/.vimrc (Unix) or
" ~/_vimrc (Windows) checks that these conditions are met before loading this
" file.
"
" The Vim script linter Vint should raise no errors, warnings, or style
" problems with this file.  <https://github.com/Kuniwak/vint>
"

" We’ll begin by making sure that this file and Vim are speaking the same
" language.  Since it’s been the future for a few years now, this file
" indulges in characters outside the ASCII character set.  The presence of
" such characters prompts Vint to suggest declaring the file encoding with
" a :scriptencoding command:
"
" │ vim/vimrc:1:1: Use scriptencoding when multibyte char exists (see :help
" │ :scriptencoding)
"
" Furthermore, the :help for :scriptencoding specifies that :scriptencoding
" should be set *after* 'encoding'.
"
" Which encoding to use?  The answer is the UTF-8 encoding for Unicode,
" wherever possible.  On POSIX-fearing operating systems, I define the primary
" locale environment variable $LANG to ‘en_NZ.UTF-8’.  This informs Vim’s
" choice of internal character encoding.  In the absence of such a setting,
" 'encoding' defaults to ‘latin1’ (ISO-8859-1) in most circumstances.  Since
" this is almost never what I want, even if I haven't said so explicitly by
" exporting $LANG, we’ll fall back to UTF-8 instead.
"
" However, we need to test that the +multi_byte feature is available before
" doing any of this, because it was a compile-time feature that wasn't even
" enabled by default in Vim v7.0.  Its status as an optional feature wasn't
" removed until v8.1.0733.
"
" <https://github.com/vim/vim/releases/tag/v8.1.0733>
"
if has('multi_byte')
  if &encoding ==# 'latin1' && !exists('$LANG')
    set encoding=utf-8
  endif
  scriptencoding utf-8
endif

" With encoding handled, we’ll turn our attention to the value of the
" 'runtimepath' option, since any scripts loaded from the paths specified
" therein control so much of the behavior of Vim.  We build this path up as
" accurately as possible, accounting for Vim’s unusual escaping behavior for
" these list options.
"
" One of the first things we’ll need to be able to do is split the value of
" 'runtimepath' into its constituent paths.  Correctly splitting the values of
" comma-separated Vim options is surprisingly complicated.  It's not as simple
" as just splitting on commas, or even unescaped commas; a more accurate
" definition of the delimiter is:
"
" │ Any comma not preceded by a backslash, followed by any number of spaces
" │ and commas.
"
" The pattern we use for the call to split() therefore breaks down like this:
"
"   \\     ← A literal backslash
"   \@<!   ← A negative lookbehind assertion; this means that whatever
"            occurred before this pattern—in this case, a backslash—cannot
"            precede what follows, but anything that *does* precede it is
"            considered part of the datum, and not the delimiter.
"   ,      ← A literal comma
"   [, ]*  ← Any number of commas and spaces
"
" We don’t, however, have to deal with backslashes before other backslashes,
" nor before any other character.  If this seems wrong to you, I encourage you
" to read the source code for the ad-hoc tokenizer in copy_option_part() in
" src/misc2.c in Vim’s source code.
"
" Vim, I do love you, but sometimes you're really weird.
"
" We fold all that mess away into an autoloaded function option#Split(); see
" vim/autoload/option.vim.  Provided a 'runtimepath' is actually set, using
" the list returned from that function, we define an environment variable
" MYVIM—to complement MYVIMRC—for ~/.vim or ~/vimfiles, by retrieving the
" first value from the 'runtimepath'.  We'll use this later on in the file to
" comprehensively match expected paths for vimrc files.
"
if &runtimepath ==# ''
  throw 'Empty ''runtimepath'''
endif
let $MYVIM = option#Split(&runtimepath)[0]

" The next components of the runtime directory that we'll set up here will
" make use of the user’s configured XDG base directories:
"
" <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables>
"
" Note that this isn't an attempt to shoehorn all of Vim into the XDG mold;
" all of this distribution's files are still expected to be installed into
" $MYVIM, per the above.  We're just leaning on XDG’s conventions to provide
" separate locations for cache files and other configuration.
"
" We'll start by retrieving the list of valid paths for configuration from
" both the XDG_CONFIG_HOME and XDG_CONFIG_DIRS variables, or from their
" defaults, using autoloaded xdg# functions.
"
if has('unix')
  let s:xdgcachehome
        \ = xdg#CacheHome()
  let s:xdgconfigdirs
        \ = xdg#ConfigDirs()
  let s:xdgconfighome
        \ = xdg#ConfigHome()
  let s:xdgdatadirs
        \ = xdg#DataDirs()
  let s:xdgdatahome
        \ = xdg#DataHome()
endif

" We put XDG_CONFIG_HOME at the front of the 'runtimepath' list with insert(),
" provided it isn't empty, which is what the function returns when the
" configured path isn't absolute.  This is per the standard's dictum:
"
" │ All paths set in these environment variables must be absolute. If an
" │ implementation encounters a relative path in any of these variables it
" │ should consider the path invalid and ignore it.
"
"     —XDG Base Directory Specification v0.7 (24th November 2010), "Basics",
"     <https://specifications.freedesktop.org/basedir-spec/0.7/ar01s02.html>
"
" Ours not to reason why…
"
if exists('s:xdgconfighome') && s:xdgconfighome !=# ''
      \ || exists('s:xdgconfigdirs') && !empty(s:xdgconfigdirs)
  execute 'set runtimepath^='.option#Escape(join(map(
        \ extend(
          \ s:xdgconfighome !=# '' ? [s:xdgconfighome] : [],
          \ s:xdgconfigdirs
          \),
        \ 'option#item#Escape(v:val)'
        \), ','))
  execute 'set runtimepath+='.option#Escape(join(map(
        \ reverse(extend(
          \ s:xdgconfighome !=# '' ? [s:xdgconfighome] : [],
          \ s:xdgconfigdirs
          \)),
        \ 'option#item#Escape(v:val.''/after'')'
        \), ','))
endif

" Using a logical but non-default location for viminfo has the nice benefit of
" preventing command and search history from getting clobbered when something
" runs Vim without using this vimrc, because such an instance will safely
" write its own history to the default viminfo path instead.
"
" This is the portable way to specify the path to the viminfo file, as an
" addendum of the path to the 'viminfo' option with an ‘n’ prefix.  Vim
" v8.1.716 introduced a way to set this with an option named 'viminfofile',
" but I don't see a reason to use that.
"
if exists('s:xdgcachehome') && s:xdgcachehome !=# ''
  if !isdirectory(s:xdgcachehome)
    call mkdir(s:xdgcachehome, 'p', 0700)
  endif
  execute 'set viminfo+='.option#Escape(
        \ 'n'.s:xdgcachehome.'/viminfo'
        \)
endif

" Speaking of recorded data in viminfo files, the default Vim limit of a mere
" 50 entries for command and search history is pretty stingy.  The documented
" maximum value for this option is 10000.  I used that for a while, but
" eventually found that on lower-powered machines, keeping this much command
" history slowed Vim startup down a bit much for my liking, so I've scaled
" this back to a more conservative 300.  If I end up missing useful commands,
" I might try switching this on available memory instead.
"
set history=300

" We’ll now enable automatic backups of most file buffers, since that’s off by
" default.  In practice, I don’t need these backups very much, at least if I’m
" using version control sensibly, but they have still saved my bacon a few
" times.
"
" We’ll try to keep the backup files in a dedicated cache directory, to stop
" them popping up next to the file to which they correspond, and getting
" accidentally committed to version control.
"
" If Vim is new enough, we’ll add two trailing slashes to the path we’re
" inserting, which prompts Vim to incorporate the full escaped path of the
" relevant buffer in the backup filename, avoiding collisions.
"
" As a historical note, other similar directory path list options supported
" this trailing slashes hint for a long time before 'backupdir' caught up to
" them.  The 'directory' option for swap files has supported it at least as
" far back as v5.8.0 (2001), and 'undodir' appears to have supported it since
" its creation in v7.2.438.  Even though ‘:help 'backupdir'’ didn’t say so,
" people assumed it would work the same way, when in fact Vim simply ignored
" it until v8.1.0251.
"
" I don’t want to add the slashes to the option value in older versions of Vim
" where they don’t do anything, so we’ll check the version ourselves to see if
" there’s any point in including them.
"
" <https://github.com/vim/vim/releases/tag/v8.1.0251>
"
" It’s all so awkward.  Surely separate options named something like
" 'backupfullname', 'swapfilefullname' would have been clearer.
"
set backup
if exists('s:xdgcachehome') && s:xdgcachehome !=# ''
  if !isdirectory(s:xdgcachehome.'/backup')
    call mkdir(s:xdgcachehome.'/backup', 'p', 0700)
  endif
  execute 'set backupdir^='.option#Escape(option#item#Escape(
        \ s:xdgcachehome.'/backup'.(patch#('8.1.251') ? '//' : '')
        \))
endif

" Files in certain directories on Unix-compatible filesystems should not be
" backed up, for security reasons.  This is particularly important if editing
" temporary files created by sudoedit(8).  We add a few path patterns to the
" default value of 'backupskip' here, in order to prevent the creation of such
" undesired backup files.
"
if has('unix')

  " Prior to v8.1.1519, Vim didn’t check patterns added to 'backupskip' for
  " uniqueness, so adding the same path repeatedly resulted in duplicate
  " strings in the value.  This was due to the absence of the P_NODUP flag for
  " the option’s definition in src/option.c in the Vim source code.  If we’re
  " using a version older than v8.1.1519, we’ll need to explicitly reset
  " 'backupskip' to its default value before adding patterns to it, so that
  " reloading this file doesn’t stack up multiple copies of any added paths.
  "
  " <https://github.com/vim/vim/releases/tag/v8.1.1519>
  "
  if !patch#('8.1.1519')
    set backupskip&
  endif

  " Typical temporary file locations
  "" RAM disk, default path for password-store’s temporary files
  set backupskip+=/dev/shm/*
  "" Hard-coded paths for sudoedit
  set backupskip+=/usr/tmp/*,/var/tmp/*

  " Per-repository temporary files for Git
  "" Commit and tag messages
  set backupskip+=*/*.git/?*_EDITMSG
  "" Edited patches
  set backupskip+=*/*.git/ADD_EDIT.patch
  "" Email messages
  set backupskip+=*/*.git/.gitsendemail.msg.*
  "" Interactive rebase manifests
  set backupskip+=*/*.git/rebase-merge/git-rebase-todo

  " systemd user manager unit files
  "" Full unit files
  set backupskip+=*/systemd/user/.#?*.?*????????????????
  "" Per-unit overrides
  set backupskip+=*/systemd/user/?*.?*.d/.#override.conf????????????????

endif

" Keep swap files for file buffers in a dedicated directory, rather than the
" default of writing them to the same directory as the buffer file.  Add two
" trailing slashes to the path to prompt Vim to use the full escaped path in
" its name, in order to avoid filename collisions, since the 'directory'
" option has supported that hint for much longer than 'backupdir' has.
"
if exists('s:xdgcachehome') && s:xdgcachehome !=# ''
  if !isdirectory(s:xdgcachehome.'/swap')
    call mkdir(s:xdgcachehome.'/swap', 'p', 0700)
  endif
  execute 'set directory^='.option#Escape(option#item#Escape(
        \ s:xdgcachehome.'/swap//'
        \))
endif

" Keep tracked undo history for files permanently, in a dedicated cache
" directory, so that the u/:undo and CTRL-R/:redo commands will work between
" Vim invocations.
"
" The 'undodir' option has the same structure as 'backupdir' and 'directory';
" if we have a user cache directory, create a subdirectory within it dedicated
" to the undo files cache.  Note also the trailing double-slash as a signal to
" Vim to use the full path of the original file in its undo file cache’s name.
"
" Support for these persistent undo file caches was not released until v7.3.0,
" so we need to check for the feature’s presence before we enable it.
"
if exists('s:xdgcachehome') && s:xdgcachehome !=# '' && has('persistent_undo')
  set undofile
  if !isdirectory(s:xdgcachehome.'/undo')
    call mkdir(s:xdgcachehome.'/undo', 'p', 0700)
  endif
  execute 'set undodir^='.option#Escape(option#item#Escape(
        \ s:xdgcachehome.'/undo//'
        \))
endif

" Set up a directory for files generated by :mkview.  To date, I think I have
" used this twice in my life, but may as well be consistent with the other
" directories of this type.  This isn't a comma-separated list like the others
" ('backupdir', 'directory', 'spell', 'undodir')
"
if exists('s:xdgcachehome') && s:xdgcachehome !=# '' && has('mksession')
  if !isdirectory(s:xdgcachehome.'/view')
    call mkdir(s:xdgcachehome.'/view', 'p', 0700)
  endif
  execute 'set viewdir='.option#Escape(option#item#Escape(
        \ s:xdgcachehome.'/view'
        \))
endif

" Now that we have a bit more confidence in our runtime environment, set up
" all of the filetype detection, plugin, and indent hooks.
"
filetype plugin indent on

" There are a couple of contexts in which it's useful to reload filetypes for
" the current buffer, quietly doing nothing if filetypes aren't enabled.
" We'll set up a user command named :ReloadFileType to do this, with
" an autoloaded function backing it.
"
command! -bar ReloadFileType
      \ call reload#FileType()

" We'll also define a :ReloadVimrc command.  This may seem like overkill, at
" first.  Surely just `:source $MYVIMRC` would be good enough?
"
" The problem is there are potential side effects to the current buffer when
" the vimrc is reloaded.  The global :set commands for some options may
" trample over different buffer-local settings that were specified by filetype
" and indent plugins.  To ensure these local values are reinstated, we'll
" define the new command wrapper around an autoloaded function that itself
" issues a :ReloadFileType command after the vimrc file is sourced.
"
command! -bar ReloadVimrc
      \ call reload#Vimrc()

" We'll now create or reset a group of automatic command hooks specific to
" matters related to reloading the vimrc itself, or maintaining and managing
" options set within it.
"
augroup vimrc
  autocmd!
augroup END

" Reload the stub vimrc, and thereby this main one, each time either of them
" is written.  This often makes errors in the file immediately apparent, and
" saves restarting Vim or running the :source command manually, which I almost
" always want to do after changing my vimrc file anyway.
"
autocmd vimrc BufWritePost $MYVIMRC,$MYVIM/vimrc
      \ ReloadVimrc

" If Vim is new enough (v7.0.187) to support the ##SourceCmd event for
" automatic command hooks, we'll also apply a hook for that event to catch
" invocations of :source of either vimrc file, and translate that into
" reloading the stub vimrc.
"
" <https://github.com/vim/vim/releases/tag/v7.0.187>
"
if exists('##SourceCmd')
  autocmd vimrc SourceCmd $MYVIMRC,$MYVIM/vimrc
        \ ReloadVimrc
endif

" For spelling, use New Zealand English by default, but later on we’ll
" configure a leader mapping to switch to United States English, since I so
" often have to write for Yankees.
"
set spelllang=en_nz

" Spell checking includes optional support for catching lower case letters at
" the start of sentences, and defines a pattern in 'spellcapcheck' for the end
" of a sentence.  The default is pretty good, but with two-spacing with
" 'cpoptions' including ‘J’ and 'formatoptions' including ‘p’ as set later in
" this file, we can be less ambiguous in this pattern.  We require two
" consecutive spaces, a newline, a carriage return, or a tab to mark the end
" of a sentence.  This means that we could make abbreviations like “i.e.
" something” without flagging “something” as a spelling error.
"
set spellcapcheck=[.?!]\\%(\ \ \\\|[\\n\\r\\t]\\)

" When spell-checking snakeCased or CamelCased words, treat every upper-case
" character in a word text object as the beginning of a new word for separate
" spell-checking.  At the time of writing, this is still a very new option
" (v8.2.0953, June 2020).
"
" <https://github.com/vim/vim/releases/tag/v8.2.0953>
"
if exists('+spelloptions')
  set spelloptions+=camel
endif

" For word completion in insert mode with CTRL-X CTRL-K, or if 'complete'
" includes the ‘k’ flag, the 'dictionary' option specifies the path to the
" system word list.  This makes the dictionary completion work consistently,
" even if 'spell' isn’t set at the time to coax it into using 'spellfile'.
"
" It’s not an error if the system directory file added first doesn’t exist;
" it’s just a common location that often yields a workable word list, and does
" so on all of my main machines.
"
" At some point, I may end up having to set this option along with 'spellfile'
" a bit more intelligently to ensure that spell checking and dictionary
" function consistently, and with reference to the same resources.  For the
" moment, I’ve just added additional entries referring to the user runtime
" directory.
"
set dictionary^=/usr/share/dict/words
if exists('s:xdgdatahome') && s:xdgdatahome !=# ''
      \ || exists('s:xdgdatadirs') && !empty(s:xdgdatadirs)
  execute 'set dictionary^='.option#Escape(join(map(
        \ extend(
          \ s:xdgdatahome !=# '' ? [s:xdgdatahome] : [],
          \ s:xdgdatadirs
          \),
        \ 'option#item#Escape(v:val.''/dictionary.txt'')'
        \), ','))
endif

" In much the same way as 'dictionary', we add an expected path to
" a thesaurus, for completion with CTRL-X CTRL-T in insert mode, or with ‘t’
" added to 'completeopt'.  The thesaurus data isn’t installed as part of the
" default ‘install-vim’ target in tejr’s dotfiles, but a decent one can be
" retrieved from my website at <https://sanctum.geek.nz/ref/thesaurus.txt>.
" I got this from the link in the :help for 'thesaurus' in v8.1.  It’s from
" WordNet and MyThes-1.  I had to remove the first two metadata lines from
" thesaurus.txt, as Vim appeared to interpret them as part of the body data.
"
if exists('s:xdgdatahome') && s:xdgdatahome !=# ''
      \ || exists('s:xdgdatadirs') && !empty(s:xdgdatadirs)
  execute 'set thesaurus^='.option#Escape(join(map(
        \ extend(
          \ s:xdgdatahome !=# '' ? [s:xdgdatahome] : [],
          \ s:xdgdatadirs
          \),
        \ 'option#item#Escape(v:val.''/thesaurus.txt'')'
        \), ','))
endif

" Next, we’ll modernize a little in adjusting some options with old
" language-specific defaults.
"
" Traditional vi was often used for development in the C programming language.
" The default values for a lot of Vim’s options still reflect this common use
" pattern.  In this case, the 'comments' and 'commentstring' options reflect
" the C syntax for comments:
"
"     /*
"      * This is an ANSI C comment.
"      */
"
" Similarly, the 'define' and 'include' options default to C preprocessor
" directives:
"
"     #define FOO "bar"
"
"     #include "baz.h"
"
" Times change, however, and I don’t get to work with C nearly as much as I’d
" like.  The defaults for these options no longer make sense, and so we blank
" them, compelling filetype plugins to set them as they need instead.
"
" The default value for the 'path' option is similar, in that it has an aged
" default; this option specifies directories in which project files and
" includes can be unearthed by navigation commands like 'gf'.  Specifically,
" its default value comprises /usr/include, which is another C default.  Let’s
" get rid of that, too.
"
set comments= commentstring= define= include=
set path-=/usr/include

" Relax traditional vi’s harsh standards over what regions of the buffer can
" be removed with backspace in insert mode.  While this admittedly allows bad
" habits to continue, since insert mode by definition is not really intended
" for deleting text, I feel the convenience outweighs that in this case.
"
set backspace+=eol     " Line breaks
set backspace+=indent  " Leading whitespace characters created by 'autoindent'
set backspace+=start   " Text before the start of the current insertion

" When soft-wrapping text with the 'wrap' option on, which is off by default,
" break the lines between words, rather than within them; it’s much easier to
" read.
"
set linebreak

" Similarly, show that the screen line is a trailing part of a wrapped line by
" prefixing it with an ellipsis.  If we have a multi-byte encoding, use
" a proper ellipsis character to save a couple of columns, but otherwise three
" periods will do just fine.
"
"     …  U+2026  HORIZONTAL ELLIPSIS
"
" Note that we test for the presence of a multi-byte encoding with a special
" feature from ‘:help feature-list’, as recommended by ‘:help encoding’.
" Checking that ‘&encoding ==# 'utf-8'’ is not quite the same thing, though
" it’s unlikely I’ll ever use a different Unicode encoding by choice.
"
if has('multi_byte_encoding')
  set showbreak=else
  set showbreak=...
endif

" The visual structure of code provided by indents breaks down if a lot of the
" lines wrap.  Ideally, most if not all lines would be kept below 80
" characters, but in cases where this isn’t possible, soft-wrapping longer
" lines when 'wrap' is on so that the indent is preserved in the following
" line mitigates this breakdown somewhat.
"
" With this 'breakindent' option set, it’s particularly important to have
" 'showbreak' set to something besides an empty string, as done above,
" otherwise without line numbers it’s hard to tell what’s a logical line and
" what’s not.
"
" The 'breakindent' option wasn’t added until v7.4.338, so we need to check it
" exists before we set it.
"
" <https://github.com/vim/vim/releases/tag/v7.4.338>
"
if exists('+breakindent')
  set breakindent
endif

" Rather than rejecting operations like :write or :saveas when 'readonly' is
" set or in other situations in which data might be lost, Vim should give me
" a prompt to allow me to confirm that I know what I’m doing.
"
set confirm

" If Vim receives an Escape key code in insert mode, it shouldn’t wait to see
" if it’s going to be followed by another key code, despite this being how the
" function keys and Meta/Alt modifier are implemented for many terminal types.
" Otherwise, if I press Escape, there’s an annoying delay before 'showmode'
" stops showing '--INSERT--'.
"
" This breaks the function keys and the Meta/Alt modifier in insert mode in
" most or maybe all of the terminals I use, but I don’t want those keys in
" insert mode, anyway.  All of this works fine in the GUI, of course.
"
set noesckeys

" Always start with 'foldlevel' set high enough to have all folds of any
" practical depth open by default.
"
set foldlevel=256

" Automatic text wrapping options using flags in the 'formatoptions' option
" begin here.  I rely on the filetype plugins to set the ‘t’ and ‘c’ flags for
" this option to configure whether text or comments should be wrapped, as
" appropriate for the document type or language, and so I don’t mess with
" either of those flags here.

" If a line is already longer than 'textwidth' would otherwise limit when
" editing of that line begins in insert mode, don’t suddenly automatically
" wrap it; I’ll break it apart myself with a command like ‘gq’.  This doesn’t
" seem to stop paragraph reformatting with ‘a’, if that’s set.
"
set formatoptions+=l

" Don’t wrap a line in such a way that a single-letter word like “I” or “a” is
" at the end of it.  Typographically, as far as I can tell, this seems to be
" a stylistic preference rather than a rule, rather like avoiding “widow” and
" “orphan” lines in typesetting.  I think it generally looks better to have
" the short word start the line, so we’ll switch it on.
"
set formatoptions+=1

" If the filetype plugins have correctly described what the comment syntax for
" the buffer’s language looks like, it makes sense to use that to figure out
" how to join lines within comments without redundant comment syntax cropping
" up.  For example, with this set, joining lines in this very comment with ‘J’
" would remove the leading ‘"’ characters.
"
" This 'formatoptions' flag wasn’t added until v7.3.541.  Because we can’t
" test for the availability of option flags directly, we resort to a version
" number check before attempting to set it.  I don’t like using :silent! to
" suppress errors for this sort of thing when I can reasonably avoid it, even
" if the tests are somewhat more verbose.
"
" <https://github.com/vim/vim/releases/tag/v7.3.541>
"
if patch#('7.3.541')
  set formatoptions+=j
endif

" A momentary digression here into the doldrums of 'cpoptions'—after staunchly
" opposing it for years, I have converted to two-spacing.  You can blame Steve
" Losh:
"
" <http://stevelosh.com/blog/2012/10/why-i-two-space/>
"
" Consequently, we specify that sentence objects for the purposes of the ‘s’
" text object, the ‘(’ and ‘)’ sentence motions, and formatting with the 'gq'
" command must be separated by *two* spaces.  One space does not suffice.
"
" My defection to the two-spacers is also the reason I now leave 'joinspaces'
" set, per its default, so that two spaces are inserted when consecutive
" sentences separated by a line break are joined onto one line by the ‘J’
" command.
"
set cpoptions+=J

" Separating sentences with two spaces has an advantage in making a clear
" distinction between two different types of periods: periods that abbreviate
" longer words, as in “Mr. Moolenaar”, and periods that terminate sentences,
" like this one.
"
" If we’re using two-period spacing for sentences, Vim can interpret the
" different spacing to distinguish between the two types, and can thereby
" avoid breaking a line just after an abbreviating period.  For example, the
" two words in “Mr. Moolenaar” should never be split apart, lest the
" abbreviation “Mr.” look too much like the end of a sentence.  This also
" preserves the semantics of that same period for subsequent reformatting; its
" single-space won’t get lost.
"
" So, getting back to our 'formatoptions' settings, that is what the ‘p’ flag
" does.  I wrote the patch that added it, after becoming envious of an
" analogous feature during an ill-fated foray into GNU Emacs usage.
"
" <https://github.com/vim/vim/releases/tag/v8.1.1523>
"
if patch#('8.1.728')
  set formatoptions+=p
endif

" In an effort to avoid loading unnecessary files, we add a flag to the
" 'guioptions' option to prevent the menu.vim runtime file from being loaded.
" It doesn’t do any harm, but I never use it, and it’s easy to turn it off.
"
" The documentation for this flag in ‘:help 'go-M'’ includes a note saying the
" flag should be set here, rather that in the GUI-specific gvimrc file, as one
" might otherwise think.
"
if has('gui_running')
  set guioptions+=M
endif

" By default, Vim doesn’t allow a file buffer to have unwritten changes if
" it’s not displayed in a window.  Setting this option removes that
" restriction so that buffers can remain in a modified state while not
" actually displayed anywhere.
"
" This option is set in almost every vimrc I read; it’s so pervasive that
" I sometimes see comments expressing astonishment or annoyance that it isn’t
" set by default.  However, I didn’t actually need this option for several
" years of Vim usage, because I instinctively close windows onto buffers only
" after the buffers within them have been written anyway.
"
" However, the option really is required for batch operations performed with
" commands like :argdo or :bufdo, because Vim won’t otherwise tolerate
" unwritten changes to a litany of buffers that are not displayed in any
" window.  After I started using such command maps a bit more often,
" I realized I finally had a reason to turn this on permanently.
"
set hidden

" Highlight matches for completed searches in the buffer text, but clear that
" highlighting away when this vimrc file is reloaded.  Later on in this file,
" CTRL-L in normal mode is remapped to issue :nohlsearch in addition to its
" usual screen refresh function.
"
set hlsearch
nohlsearch

" Highlight search matches in my text while I’m still typing my pattern,
" including scrolling the screen to show the first such match if necessary.
" This can be somewhat jarring, particularly when the cursor ends up scrolling
" a long way from home in a large file, but I think the benefits of being able
" to see instances of what I’m trying to match as I type the pattern do
" outweigh that discomfort.
"
set incsearch

" Don’t waste cycles and bandwidth redrawing the screen during execution of
" macro recordings and scripts.
"
set lazyredraw

" Define meta-characters to show in place of characters that are otherwise
" invisible, or line wrapping attributes when the 'list' option is enabled.
"
" These 'list' characters all correspond to invisible or indistinguishable
" characters.  We leave the default eol:$ in place to show newlines, and add
" a few more.
"
set listchars+=tab:>-   " Tab characters, preserve width with hyphens
set listchars+=trail:-  " Trailing spaces
set listchars+=nbsp:+   " Non-breaking spaces

" The next pair of 'list' characters are arguably somewhat misplaced, in that
" they don’t really represent invisible characters in the same way as the
" others, but are hints for the presence of other characters on unwrapped
" lines that are wider than the screen.  They’re very useful, though.
"
" If the current encoding supports it, use these non-ASCII characters for the
" markers, as they’re visually distinctive:
"
" extends: Signals presence of unwrapped text to screen right
"     »  U+00BB  RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
" precedes: Signals presence of unwrapped text to screen left
"     «  U+00BB  LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
"
" Failing that, ‘<’ and ‘>’ will do the trick.
"
if has('multi_byte_encoding')
  set listchars+=extends:»,precedes:«
else
  set listchars+=extends:>,precedes:<
endif

" Don’t let your editor’s options be configured by content in arbitrary files!
" Down with modelines!  Purge them from your files!  Écrasez l’infâme!
"
" I think that modelines are Vim’s worst misfeature, and that 'nomodeline'
" should be the default.  It’s enabled pretty bad security vulnerabilities
" over the years, and it’s a lot more effective to use filetype detection,
" other automatic command hooks, or methods like .editorconfig to set
" variables specifically for a buffer or project.
"
set nomodeline

" The only octal numbers I can think of that I ever even encounter are Unix
" permissions masks, and I’d never use CTRL-A or CTRL-X to increment them.
" Numbers with leading zeroes are far more likely to be decimals.
"
set nrformats-=octal

" I like to leave the last line of the screen blank unless something is
" actually happening in the editor for it to report, so I have grown to like
" the Vim default of 'noruler'.  CTRL-G shows me everything I need to know,
" and is near-instinctive now.
"
" Rude system vimrc files tend to switch this back on, though, so we force it
" off here.
"
set noruler

" Sessions preserve window, tab, and buffer layout, and are thereby great for
" more complex and longer-term projects like books, but they don’t play
" together well with plugins and filetype plugins.  Restoring the same
" settings from both reloaded plugins and from the session causes screeds of
" errors.  Adjusting session behavior to stop it trying to restore the sorts
" of settings that plugins manage makes them usable again.
"
set sessionoptions-=localoptions  " No buffer options or mappings
set sessionoptions-=options       " No global options or mappings

" Turn 'showcmd' off if a system vimrc has been rude enough to set it; I don’t
" like how it can interfere with the display of longer lines.
"
set noshowcmd

" The ‘I’ flag for the 'shortmess' option prevents the display of the Vim
" startup screen with version information, :help hints, and donation
" suggestion.  After I registered Vim and donated to Uganda per the screen’s
" plea, I didn’t feel bad about turning this off anymore.  Even with this
" setting in place, I wouldn’t normally see it too often anyway, as I seldom
" start Vim with no file arguments.
"
" I haven’t felt the need to mess with the other flags in this option.
" I don’t have any problems with spurious Enter prompts, which seems to be the
" main reason people pile it full of letters.
"
set shortmess+=I

" I find the defaults of new windows opening above or to the left of the
" previous window too jarring, because I’m used to both the i3 window manager
" and the tmux terminal multiplexer doing it the other way around, in reading
" order.  I prefer the visual effect of the previous text staying where it is,
" and the new window occupying previously blank space.
"
set splitbelow splitright

" Vim has an internal list of terminal types that support using smoother
" terminal redrawing, and for which 'ttyfast' is normally set, described in
" ‘:help 'ttyfast'’.  That list includes most of the terminals I use, but
" there are a couple more for which the 'ttyfast' option should apply: the
" windows terminal emulator PuTTY, and the terminal multiplexer tmux, both of
" which I use heavily.
"
if &term =~# '^putty\|^tmux'
  set ttyfast
endif

" We really don’t want a mouse; while I use it a lot for cut and paste in X,
" it just gets in the way if the tool running in the terminal tries to use it
" too.  Mouse events should be exclusively handled by the terminal emulator
" application, so Vim shouldn’t try to give me terminal mouse support, even if
" it would work.
"
" The manual suggests that disabling this should be done by clearing 't_RV',
" but that didn’t actually seem to work when I tried it.
"
set ttymouse=

" While using virtual block mode, allow me to navigate to any column of the
" buffer window; don’t confine the boundaries of the block to the coordinates
" of characters that actually exist in the buffer text.  While working with
" formatted columnar data with this off is generally OK, it’s a hassle for
" more subtle applications of visual block mode.
"
set virtualedit+=block

" I can’t recall a time that Vim’s error beeping or flashing was actually
" useful to me, and so we turn it off in the manner that the manual instructs
" in ‘:help 'visualbell'’.  This enables visual rather than audio error bells,
" but in the same breath, blanks the terminal attribute that would be used to
" trigger such screen blinking, indirectly disabling the bell altogether.
"
" I thought at first that the newer 'belloff' and/or 'errorbells' options
" would be a more intuitive way to keep Vim quiet, but the last time I checked
" that, neither appeared to work as comprehensively as this older method does.
"
" Interestingly, the :help says that this setting has to be repeated in the
" gvimrc file for GUI Vim.
"
set visualbell t_vb=

" When Ex command line completion is started with Tab, list valid completions
" and complete the command line to the longest common substring, just as Bash
" does, with just the one key press.
"
" The default value of 'full' for the 'wildmode' option puts the full
" completion onto the line immediately, which I tolerate for insert mode
" completion but don’t really like on the Ex command line.  Instead, I arrange
" for that to happen only with a second key press.
"
set wildmenu
set wildmode=list:longest,full

" Define a list of patterns to ignore for file and directory command line
" completion.  Files and directories with names matching any of these patterns
" won’t be presented as candidates for tab completion on the command line.
"
" To make this list, I went right through my home directory with
" a `find`-toothed comb; counted the occurrences of every extension, forced
" down to lowercase; and then manually selected the ones that I was confident
" would seldom contain plain text.
"
" The following incantation does the trick with POSIX-compatible shell tools,
" giving patterns for the top 100 alphanumeric extensions for files from the
" running user’s home directory:
"
"     $ (LC_ALL=C ; find "$HOME" ! -type d -name '*.?*' -exec \
"           sh -c 'for fn ; do
"              ext=${fn##*.}
"              case $ext in
"                  (*[![:alnum:]]*) continue ;;
"                  (?*) printf "%s\n" "$ext" ;;
"              esac
"           done' _ {} + |
"           tr '[[:upper:]]' '[[:lower:]]' | sort | uniq -c |
"           sort -k1,1nr | awk 'NR <= 100 {print "*." $2}')
"
" I turned out to have rather a lot of .html and .vim files.
"
" If you’re scoffing at that and thinking “I could write a much simpler one,”
" please do so, and send it to me at <tom@sanctum.geek.nz> to have yours put
" in here instead, with appropriate credit.  Don’t forget to handle more than
" ARG_MAX files, include filenames with newlines, and that the -z or -0 null
" separator extensions are not standardized in POSIX.
"
" <https://mywiki.wooledge.org/UsingFind#Complex_actions>
"
set wildignore=*~,#*#,*.7z,.DS_Store,.git,.hg,.svn,*.a,*.adf,*.asc,*.au,*.aup
      \,*.avi,*.bin,*.bmp,*.bz2,*.class,*.db,*.dbm,*.djvu,*.docx,*.exe
      \,*.filepart,*.flac,*.gd2,*.gif,*.gifv,*.gmo,*.gpg,*.gz,*.hdf,*.ico
      \,*.iso,*.jar,*.jpeg,*.jpg,*.m4a,*.mid,*.mp3,*.mp4,*.o,*.odp,*.ods,*.odt
      \,*.ogg,*.ogv,*.opus,*.pbm,*.pdf,*.png,*.ppt,*.psd,*.pyc,*.rar,*.rm
      \,*.s3m,*.sdbm,*.sqlite,*.swf,*.swp,*.tar,*.tga,*.ttf,*.wav,*.webm,*.xbm
      \,*.xcf,*.xls,*.xlsx,*.xpm,*.xz,*.zip

" Allow me to type a path to complete on the Ex command line in all-lowercase,
" and transform the consequent completion to match the appropriate case, like
" the Readline setting ‘completion-ignore-case’ can be used for GNU Bash.
"
" When completing filenames on the command line, choose completions without
" regard to case, allowing me the ease of typing a partial path in
" all-lowercase.  This is very similar to the Readline setting
" ‘completion-ignore-case’ used for Bash.
"
" The 'wildignorecase' option is not related to the similarly-named
" 'wildignore' option, nor to the +wildmenu feature.
"
" We need to check that the 'wildignorecase' option exists before we set it,
" because it wasn't added to Vim until v7.3.72:
"
" <https://github.com/vim/vim/releases/tag/v7.3.072>
"
if exists('+wildignorecase')
  set wildignorecase
endif

" Enable syntax highlighting, but only if it’s not already on, to save
" reloading the syntax files unnecessarily.
"
" <https://sanctum.geek.nz/blinkenlights/syntax-on.jpg>
"
" For several months in 2018, as an experiment, I tried using terminals with
" no color at all, imitating a phenomenally productive BSD purist co-worker
" who abhorred color in any form on his terminals.  He only drank black
" coffee, too.  If you’re reading this: Hello, bdh!
"
" That experiment was instructive and interesting, and I found I had been
" leaning on color information in some surprising ways.  However, some months
" later, I found I still missed my colors, and so I went back to my
" Kodachrome roots, and didn’t pine at all for that monochrome world.
"
" The thing I most like about syntax highlighting is detecting runaway
" strings, which generally works in even the most threadbare language syntax
" highlighting definitions.  I kept missing such errors when I didn’t have the
" colors.  I don’t have high standards for it otherwise, except maybe for
" shell script.
"
if !exists('syntax_on')
  syntax enable
endif

" Before we attempt to pick a syntax highlighting color scheme, we’ll set up
" a couple of hooks for color scheme loading.  In this case, we turn
" 'cursorline' on if my 'sahara' color scheme is loaded, since I’ve configured
" it to be a very dark gray that doesn’t stand out too much against a black
" background.  For any other color scheme, turn the option off, because it
" almost always stands out too much for my liking.
"
" You’d think the pattern here could be used to match the color scheme name,
" and it can be—after patch v7.4.108, when Christian Brabandt fixed it.  Until
" that version, it matched against the current buffer name, so we’re forced to
" have an explicit test in the command instead.
"
" <https://github.com/vim/vim/releases/tag/v7.4.108>
"
autocmd vimrc ColorScheme *
      \ call colorscheme#UpdateCursorline(g:colors_name, ['sahara'])

" Use 'dark' as my default value for 'background', in the absence of an
" environment variable COLORFGBG or a response in v:termrbgresp that would set
" it specifically.
"
if !exists('$COLORFGBG') && !get(v:, 'termrbgresp')
  set background=dark
endif

" If the background seems to be dark, and I have either the GUI or a 256 color
" terminal, and my custom sahara.vim color scheme looks to be available, load
" it.
"
if &background ==# 'dark'
      \ && (has('gui_running') || &t_Co >= 256)
      \ && globpath(&runtimepath, 'colors/sahara.vim') !=# ''
  colorscheme sahara
endif

" My mapping definitions begin here.  I have some general personal rules for
" approaches to mappings:
"
" * Use the configured Leader key as a prefix for mappings as much as
"   possible.
"
" * Use only the configured LocalLeader key as a prefix for mappings that are
"   defined as local to a buffer, which for me are almost always based on
"   &filetype and set up by ftplugin files.
"
" * If a normal mode map would make sense in visual mode, take the time to
"   configure that too.  Use :xmap and its analogues rather than :vmap to
"   avoid defining unusable select-mode mappings, even though I never actually
"   use selection mode directly.
"
" * Avoid mapping in insert mode; let characters be literal to the greatest
"   extent possible, and avoid “doing more” in insert mode besides merely
"   inserting text as it’s typed.
"
" * Avoid key chords with CTRL in favor of leader keys.
"
" * Never use Alt/Meta key chords; the terminal support for them is just too
"   confusing and flaky.
"
" * Don’t suppress display of mapped commands for no reason; it’s OK to show
"   the user the command that’s being run under the hood.  Do avoid HIT-ENTER
"   prompts, though.
"
" * 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
" many of these.
"

" Use backspace as an even quicker way to switch to the current buffer’s
" alternate buffer.  User nickspoons of #vim was incredulous that I had never
" used CTRL-^ and indeed did not know about it.  I have since repented.
"
nnoremap <Backspace>
      \ <C-^>

" I find the space bar’s default behavior in normal mode of moving right one
" character to be useless.  Instead, I remap it to be a lazy way of paging
" through the argument list buffers, scrolling a page until the last line of
" the buffer is visible, and then moving to the :next buffer.
"
" I always wanted you to go into space, man.
"
nnoremap <expr> <Space>
      \ line('w$') < line('$')
        \ ? "\<PageDown>"
        \ : ":\<C-U>next\<CR>"

" I often can’t remember (or guess) digraph codes, and want to look up how to
" compose a specific character that I can name, at least in part.  The table
" in ‘:help digraph-table’ is what to use for that situation, and it solves
" the problem, but I didn’t like the overhead of repeated lookups therein.
"
" Steve Losh has a solution I liked where a double-tap of CTRL-K in insert
" mode brought up the applicable :help window:
"
" <https://bitbucket.org/sjl/dotfiles/src/2559256/vim/vimrc#lines-309:310>
"
" I took that one step further with a custom plugin named digraph_search.vim.
" It parses the digraph table from :help and runs a simple text search of its
" names using a string provided by the user.  For example, searching for ACUTE
" yields:
"
" > Digraphs matching ACUTE:
" > ´  ''  ACUTE ACCENT
" > Á  A'  LATIN CAPITAL LETTER A WITH ACUTE
" > É  E'  LATIN CAPITAL LETTER E WITH ACUTE
" > Í  I'  LATIN CAPITAL LETTER I WITH ACUTE
" > ...etc...
"
" <https://sanctum.geek.nz/cgit/vim-digraph-search.git/about/>
"
" This leaves you in insert mode, ready to hit CTRL-K one more time and then
" type the digraph that you’ve hopefully found.
"
" Since a double-tap of CTRL-K does nothing in default Vim, we don’t bother
" checking that the plugin’s available before we map to it; it’ll just quietly
" do nothing.
"
imap <C-K><C-K>
      \ <Plug>(DigraphSearch)

" 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
" insert and visual modes, 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 behavior.
"
nnoremap <C-L>
      \ :<C-U>nohlsearch<CR><C-L>

" The insert mode wrapper for normal CTRL-L uses i_CTRL-O to issue a single
" normal mode command.  We intentionally use ‘:normal’ rather than ‘:normal!’
" so that the mapping works recursively.  I tried using <C-O><C-L> with :imap
" for this, but it didn’t work.  Maybe i_CTRL-O doesn’t respect mappings.
" I couldn’t find any documentation about it.
"
inoremap <C-L>
      \ <C-O>:execute "normal \<C-L>"<CR>

" We use :vmap here rather than :xmap to have the mapping applied for select
" mode as well as visual mode.  This is because CTRL-L doesn’t reflect
" a printable character, and so we don't shadow anything by making it work,
" even though I don’t actually use select mode directly very much.
"
vmap <C-L>
      \ <Esc><C-L>gv

" 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.
"
noremap &
      \ :&&<CR>
ounmap &
sunmap &

" 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.
"
" <https://sanctum.geek.nz/cgit/vim-colon-operator.git/about/>
"
nmap g:
      \ <Plug>(ColonOperator)

" 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<CR>
nnoremap ]a
      \ :next<CR>
" Buffers
nnoremap [b
      \ :bprevious<CR>
nnoremap ]b
      \ :bnext<CR>
" Quickfix list
nnoremap [c
      \ :cprevious<CR>
nnoremap ]c
      \ :cnext<CR>
" Location list
nnoremap [l
      \ :lprevious<CR>
nnoremap ]l
      \ :lnext<CR>

" Here’s another mapping I particularly liked from unimpaired.vim; 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.
"
" <https://sanctum.geek.nz/cgit/vim-put-blank-lines.git/about/>
"
nmap [<Space>
      \ <Plug>(PutBlankLinesAbove)
nmap ]<Space>
      \ <Plug>(PutBlankLinesBelow)

" We’re on to the leader maps, now.  It’s difficult to know in what order to
" describe and specify these.  I used to have them in alphabetical order, but
" it seems much more useful to group them by the type of action they take.
"
" 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 I sometimes wonder if
" I would use the key for its original function more, had I not shadowed it.
"
let mapleader = '\'
let maplocalleader = ','

" If the local leader is a comma, map double-tap comma to its original
" function in the relevant modes so that I can still use it quickly without
" relying on mapping 'timeout'.
"
if maplocalleader ==# ','
  noremap ,,
        \ ,
  sunmap ,,
endif

" 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.  Annoyingly,
" 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,TAB toggles automatic indentation based on the previous line
nnoremap <Leader><Tab>
      \ :<C-U>set autoindent! autoindent?<CR>
"" Leader,c toggles highlighted cursor row; doesn’t work in visual mode
nnoremap <Leader>c
      \ :<C-U>set cursorline! cursorline?<CR>
"" Leader,h toggles highlighting search results
nnoremap <Leader>h
      \ :<C-U>set hlsearch! hlsearch?<CR>
"" Leader,i toggles showing matches as I enter my pattern
nnoremap <Leader>i
      \ :<C-U>set incsearch! incsearch?<CR>
"" Leader,s toggles spell checking
nnoremap <Leader>s
      \ :<C-U>set spell! spell?<CR>

" 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
noremap <Leader>C
      \ :<C-U>set cursorcolumn! cursorcolumn?<CR>
ounmap <Leader>C
sunmap <Leader>C
"" Leader,l toggles showing tab, end-of-line, and trailing white space
noremap <Leader>l
      \ :<C-U>set list! list?<CR>
ounmap <Leader>l
sunmap <Leader>l
"" Leader,n toggles line number display
noremap <Leader>n
      \ :<C-U>set number! number?<CR>
ounmap <Leader>n
sunmap <Leader>n
"" Leader,N toggles position display in bottom right
noremap <Leader>N
      \ :<C-U>set ruler! ruler?<CR>
ounmap <Leader>N
sunmap <Leader>N
"" Leader,w toggles soft wrapping
noremap <Leader>w
      \ :<C-U>set wrap! wrap?<CR>
ounmap <Leader>w
sunmap <Leader>w

" 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 <Leader>f
      \ :<C-U>set formatoptions?<CR>

" 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.
"
nnoremap <Leader>z
      \ :<C-U>set spelllang=en_nz<CR>
nnoremap <Leader>u
      \ :<C-U>set spelllang=en_us<CR>

" The next mapping is also for toggling an option, 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 manipulating the text as it leaves the buffer,
" it makes more sense to use :! commands.
"
" <https://sanctum.geek.nz/cgit/vim-copy-linebreak.git/about/>
"

"" Leader,b toggles settings friendly to copying and pasting
nmap <Leader>b
      \ <Plug>(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
" with just the :set command, 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 <Leader>a
      \ :<C-U>ToggleFlagLocal formatoptions a<CR>
"" Leader,L toggles 'colorcolumn' showing the first column beyond 'textwidth'
noremap <Leader>L
      \ :<C-U>ToggleFlagLocal colorcolumn +1<CR>
ounmap <Leader>L
sunmap <Leader>L

" This mapping uses my paste_insert.vim plugin to queue up automatic commands
" for the next insert operation.  It’s still pretty new.  It replaces my old
" paste_open.vim plugin which did this only for opening new lines, and which
" kept confusing me.  I’m hoping this will be better.

"" Leader,p prepares the next insert for paste mode
nmap <Leader>p
      \ <Plug>PasteInsert

" These mappings are for managing filetypes.  The first one uses the
" :ReloadFileType command that was defined much earlier in this file for
" application in the vimrc reload command.

"" Leader,F reloads filetype settings
nnoremap <Leader>F
      \ :<C-U>ReloadFileType<CR>
"" Leader,t shows current filetype
nnoremap <Leader>t
      \ :<C-U>set filetype?<CR>
"" Leader,T clears filetype
nnoremap <Leader>T
      \ :<C-U>set filetype=<CR>

" These mappings use my put_date.vim plugin for date insertion into the
" buffer.

"" Leader,d inserts the local date (RFC 2822)
nnoremap <Leader>d
      \ :PutDate<CR>
"" Leader,D inserts the UTC date (RFC 2822)
nnoremap <Leader>D
      \ :PutDate!<CR>

" 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
nnoremap <Leader>g
      \ :<C-U>echo expand('%:p')<CR>
"" Leader,G changes directory to the current file’s location
nnoremap <Leader>G
      \ :<C-U>cd %:h <Bar> pwd<CR>
"" Leader,P creates the path to the current file if it doesn’t exist
nnoremap <Leader>P
      \ :<C-U>call mkdir(expand('%:h'), 'p')<CR>

" This group contains mappings that show information about Vim’s internals:
" marks, registers, variables, and the like.

"" Leader,H shows command history
nnoremap <Leader>H
      \ :<C-U>history :<CR>
"" Leader,k shows my marks
nnoremap <Leader>k
      \ :<C-U>marks<CR>
"" Leader,K shows functions
nnoremap <Leader>K
      \ :<C-U>function<CR>
"" Leader,m shows normal maps
nnoremap <Leader>m
      \ :<C-U>nmap<CR>
"" Leader,M shows buffer-local normal maps
nnoremap <Leader>M
      \ :<C-U>nmap <buffer><CR>
"" Leader,S shows loaded scripts
nnoremap <Leader>S
      \ :<C-U>scriptnames<CR>
"" Leader,U shows user commands
nnoremap <Leader>U
      \ :<C-U>command<CR>
"" Leader,v shows all global and internal variables
nnoremap <Leader>v
      \ :<C-U>let g: v:<CR>
"" Leader,V shows all buffer, tab, and window local variables
nnoremap <Leader>V
      \ :<C-U>let b: t: w:<CR>
"" Leader,y shows all registers
nnoremap <Leader>y
      \ :<C-U>registers<CR>

" This group contains mappings concerned with buffer navigation and
" management.  I use the “jetpack” buffer jumper one a lot.  I got it from one
" of bairui’s “Vim and Vigor” comics:
"
" <http://of-vim-and-vigor.blogspot.com/p/vim-vigor-comic.html>

"" Leader,DEL deletes the current buffer
nnoremap <Leader><Delete>
      \ :bdelete<CR>
"" Leader,INS edits a new buffer
nnoremap <Leader><Insert>
      \ :<C-U>enew<CR>
"" Leader,e forces a buffer to be editable, even a :help one
nnoremap <Leader>e
      \ :<C-U>set modifiable noreadonly<CR>
"" Leader,E locks a buffer, reversible with <Leader>e
nnoremap <Leader>E
      \ :<C-U>set nomodifiable readonly<CR>
"" Leader,j jumps to buffers—the “jetpack”
nnoremap <Leader>j
      \ :<C-U>buffers<CR>:buffer<Space>

" Leader,o hacks up the list of old files from viminfo just long enough to
" ensure that :browse :oldfiles fits in a screen, avoiding an Enter or ‘q’
" keystroke before entering the number.  This one is handy followed by
" <Leader>,\ to jump back to the last remembered position in that file, since
" by definition viminfo remembers that mark, too.
"
nmap <Leader>o
      \ <Plug>(SelectOldFiles)

" This group defines mappings for filtering and batch operations to clean up
" buffer text.  All of these mappings use commands from my custom plugins:
"
" :KeepPosition
"   <https://sanctum.geek.nz/cgit/vim-keep-position.git/about/>
" :SqueezeRepeatBlanks
"   <https://sanctum.geek.nz/cgit/vim-squeeze-repeat-blanks.git/about/>
" :StripTrailingWhitespace
"   <https://sanctum.geek.nz/cgit/vim-strip-trailing-whitespace.git/about/>
"

"" Leader,x strips trailing whitespace
noremap <Leader>x
      \ :StripTrailingWhitespace<CR>
ounmap <Leader>x
sunmap <Leader>x

"" Leader,X squeezes repeated blank lines
noremap <Leader>X
      \ :SqueezeRepeatBlanks<CR>
ounmap <Leader>X
sunmap <Leader>X
"" Leader,= runs the whole buffer through =, preserving position
nnoremap <Leader>=
      \ :<C-U>KeepPosition execute 'normal! 1G=G'<CR>
"" Leader,+ runs the whole buffer through gq, preserving position
nnoremap <Leader>+
      \ :<C-U>KeepPosition execute 'normal! 1GgqG'<CR>

" 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
onoremap <Leader>_
      \ :<C-U>execute 'normal! `[v`]'<CR>
"" Leader,% or Leader,5 uses entire buffer as an object
onoremap <Leader>%
      \ :<C-U>execute 'normal! 1GVG'<CR>
omap <Leader>5
      \ <Leader>%

" This group defines some useful motions, including navigating by indent
" block using a custom plugin:
"
" <https://sanctum.geek.nz/cgit/vim-vertical-region.git/about/>
"

"" Leader,{ and Leader,} move to top and bottom of indent region
map <Leader>{
      \ <Plug>(VerticalRegionUp)
sunmap <Leader>{
map <Leader>}
      \ <Plug>(VerticalRegionDown)
sunmap <Leader>}
"" Leader,\ jumps to the last edit position mark; think “Now, where was I?”
noremap <Leader>\
      \ `"
sunmap <Leader>\

" This group does both: useful motions on defined text objects.

"" Leader,< and Leader,> adjust indent of last edit; good for pasting
nnoremap <Leader><lt>
      \ :<C-U>'[,']<lt><CR>
nnoremap <Leader>>
      \ :<C-U>'[,']><CR>

" This group is for directory tree or help search convenience mappings.

"" Leader,/ types :vimgrep for me ready to enter a search pattern
nnoremap <Leader>/
      \ :<C-U>vimgrep /\c/j **<S-Left><S-Left><Right>
"" Leader,? types :lhelpgrep for me ready to enter a search pattern
nnoremap <Leader>?
      \ :<C-U>lhelpgrep \c<S-Left>

" 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.
"
" * <https://sanctum.geek.nz/cgit/vim-alternate-filetype.git/about/>
" * <https://sanctum.geek.nz/cgit/vim-regex-escape.git/about/>
" * <https://sanctum.geek.nz/cgit/vim-replace-operator.git/about/>
" * <https://sanctum.geek.nz/cgit/vim-scratch-buffer.git/about/>
"

"" Leader,. runs the configured make program into the location list
nnoremap <Leader>.
      \ :<C-U>lmake!<CR>
"" Leader,q formats the current paragraph
nnoremap <Leader>q
      \ gqap
"" Leader,r acts as a replacement operator
map <Leader>r
      \ <Plug>(ReplaceOperator)
ounmap <Leader>r
sunmap <Leader>r
"" Leader,!/1 repeats the last command, adding a bang
nnoremap <Leader>!
      \ :<Up><Home><S-Right>!<CR>
nmap <Leader>1
      \ <Leader>!
"" Leader,#/3 switches the current buffer to the next alternate filetype
nmap <Leader>#
      \ <Plug>(AlternateFileType)
nmap <Leader>3
      \ <Leader>#
"" Leader,&/7 escapes regex metacharacters
map <Leader>&
      \ <Plug>(RegexEscape)
ounmap <Leader>&
sunmap <Leader>&
map <Leader>7
      \ <Leader>&
ounmap <Leader>7
sunmap <Leader>7
"" Leader,*/8 is "sticky star":
""    - Set search string to word under cursor
""    - Show search highlighting if it's enabled
""    - Don't move the cursor
nnoremap <Leader>*
      \ :<C-U>let @/ = expand('<cword>') <Bar> let &hlsearch = &hlsearch<CR>
nmap <Leader>8
      \ <Leader>*
"" Leader,` opens a scratch buffer, horizontally split
nnoremap <Leader>`
      \ :<C-U>ScratchBuffer<CR>
"" Leader,~ opens a scratch buffer, vertically split
nnoremap <Leader>~
      \ :<C-U>vertical ScratchBuffer<CR>

" There's no digraph for ZERO WIDTH SPACE (U+200B), which I often need to work
" around word boundary problems in tagging people on the Fediverse.
"
digraphs zs 8203

" And last, but definitely not least, I’m required by Vim fanatic law to
" include a mapping that reloads my whole configuration.  This uses the
" command wrapper defined much earlier in the file, so that filetypes also get
" reloaded afterwards, meaning I don’t need to follow <Leader>R with
" a <Leader>F to fix up broken global settings.
"
nnoremap <Leader>R
      \ :<C-U>ReloadVimrc<CR>

" 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/
      \ <https://sanctum.geek.nz/>

" And then, just automatically fix some things I almsot always spell or type
" wrnog.
"
inoreabbrev almsot
      \ almost
inoreabbrev wrnog
      \ wrong
inoreabbrev Fielding
      \ Feilding
inoreabbrev Newsbeuter
      \ Newsboat
inoreabbrev newsbeuter
      \ newsboat
inoreabbrev THe
      \ The
inoreabbrev THere
      \ There

" Here endeth the literate vimrc.  Let us praise God.
"
" │ Consequently, it is soon recognized that they write for the sake of
" │ filling up the paper, and this is the case sometimes with the best
" │ authors…as soon as this is perceived the book should be thrown away,
" │ for time is precious.
" │
" │     —Schopenhauer
"