Merge branch 'release/v6.21.0'v6.21.0

* release/v6.21.0:
  Update dotfiles(7) manual page
  Spelling and capitalisation fixes
  Add load guards to Vim plugins not spun out yet
  Adjust comma position in broken lines
  Overhaul local Vim spellfile word list plugin
  Refactor select_old_files.vim to allow count
  Enhance load guard or select_old_files.vim
  Add <Plug>SelectOldFiles mapping
  Add a rough normal mode map to repeat with bang
  Refactor and fix arg errors in put_date.vim plugin
  Consolidate utc.vim and put_date.vim into latter
  Document choice of format for PutDate()
  More comment corrections

10 files changed, 142 insertions, 49 deletions

diff --git a/vim/autoload/put_date.vim b/vim/autoload/put_date.vim
new file mode 100644
index 00000000..c9f52c12
--- /dev/null
+++ b/vim/autoload/put_date.vim
@@ -0,0 +1,19 @@
+let s:rfc_2822 = '%a, %d %b %Y %T %z'
+
+function! put_date#(line, utc, format) abort
+  let line = a:line
+  let utc = a:utc
+  let format = strlen(a:format)
+        \ ? substitute(a:format, '\a', '%&', 'g')
+        \ : s:rfc_2822
+  if utc
+    if exists('$TZ')
+      let tz = $TZ
+    endif
+    let $TZ = 'UTC'
+  endif
+  execute line.'put =strftime(format)'
+  if exists('tz')
+    let $TZ = tz
+  endif
+endfunction
diff --git a/vim/autoload/select_old_files.vim b/vim/autoload/select_old_files.vim
index 518b98d4..aceff110 100644
--- a/vim/autoload/select_old_files.vim
+++ b/vim/autoload/select_old_files.vim
@@ -1,7 +1,17 @@
-function! select_old_files#() abort
+function! select_old_files#(...) abort
+  if a:0
+    if a:1 =~# '^\d\+$'
+      let limit = a:1
+    else
+      echoerr 'Invalid count'
+    endif
+  elseif exists('g:select_old_files_limit')
+    let limit = g:select_old_files_limit
+  else
+    let limit = &lines - 2
+  endif
   let oldfiles = v:oldfiles
-  let limit = get(g:, 'select_old_files_limit', &lines - 1)
-  let v:oldfiles = v:oldfiles[:limit-2]
+  let v:oldfiles = v:oldfiles[:limit - 1]
   browse oldfiles
   let v:oldfiles = oldfiles
 endfunction
diff --git a/vim/autoload/spellfile_local.vim b/vim/autoload/spellfile_local.vim
index aafe64ef..081b2970 100644
--- a/vim/autoload/spellfile_local.vim
+++ b/vim/autoload/spellfile_local.vim
@@ -1,11 +1,72 @@
+function! s:SplitOption(string) abort
+  return map(
+      \ split(a:string, '\\\@<!,[, ]*')
+      \,"substitute(v:val, '\\\\,', '', 'g')"
+      \)
+endfunction
+
+function! s:JoinOption(list) abort
+  return join(map(
+        \ a:list
+        \,"substitute(v:val, '\\\\\\@<!,', '\\\\,', 'g')"
+        \), ',')
+endfunction
+
+function! s:Establish(path) abort
+  return isdirectory(a:path)
+        \ || exists('*mkdir') && mkdir(a:path, 'p', 0700)
+endfunction
+
 function! spellfile_local#() abort
-  let spellfile = join([
-        \ substitute(expand('%:p'), '[^0-9A-Za-z_.-]', '%', 'g'),
-        \ substitute(v:lang, '_.*', '', ''),
-        \ &encoding
-        \ ], '.') . '.add'
-  Establish $MYVIM/cache/spell/local
-  execute 'setlocal spellfile+=$MYVIM/cache/spell/local/'.spellfile
-  nnoremap <buffer> zG 2zg
-  xnoremap <buffer> zG 2zg
+
+  set spellfile<
+
+  let spelllangs = s:SplitOption(&spelllang)
+  if !len(spelllangs) || &spelllang[0] ==# ''
+    echoerr 'Blank ''spelllang'''
+  endif
+  let spelllang = substitute(spelllangs[0], '_.*', '', '')
+
+  if !len(&encoding)
+    echoerr 'Blank ''encoding'''
+  endif
+
+  let spellfiles = s:SplitOption(&spellfile)
+  if len(spellfiles) != 1 || spellfiles[0] ==# ''
+    return
+  endif
+
+  let spelldir = fnamemodify(spellfiles[0], ':h')
+  if spelldir ==# ''
+    echoerr 'Blank directory'
+  endif
+
+  try
+    let path = substitute(expand('%:p'), '/', '%', 'g')
+    if path ==# ''
+      echoerr 'Blank path'
+    endif
+    call s:Establish(spelldir.'/path')
+    call add(spellfiles, spelldir.'/path/'.join([
+          \ path
+          \,spelllang
+          \,&encoding
+          \,'add'
+          \], '.'))
+
+    if &filetype ==# ''
+      echoerr 'Blank filetype'
+    endif
+    call s:Establish(spelldir.'/filetype')
+    call add(spellfiles, spelldir.'/filetype/'.join([
+          \ &filetype
+          \,spelllang
+          \,&encoding
+          \,'add'
+          \], '.'))
+  catch
+  endtry
+
+  let &l:spellfile = s:JoinOption(spellfiles)
+
 endfunction
diff --git a/vim/autoload/utc.vim b/vim/autoload/utc.vim
deleted file mode 100644
index 1a464342..00000000
--- a/vim/autoload/utc.vim
+++ /dev/null
@@ -1,4 +0,0 @@
-function! utc#(command) abort
-  let tz = expand('$TZ')
-  let $TZ = 'UTC' | execute a:command | let $TZ = tz
-endfunction
diff --git a/vim/plugin/paste_insert.vim b/vim/plugin/paste_insert.vim
index 9cd5415e..2c17f802 100644
--- a/vim/plugin/paste_insert.vim
+++ b/vim/plugin/paste_insert.vim
@@ -1,4 +1,4 @@
-if exists('loaded_paste_insert')
+if exists('loaded_paste_insert') || &compatible
   finish
 endif
 let loaded_paste_insert = 1
diff --git a/vim/plugin/put_date.vim b/vim/plugin/put_date.vim
index d911486e..e78f5fcd 100644
--- a/vim/plugin/put_date.vim
+++ b/vim/plugin/put_date.vim
@@ -1,6 +1,6 @@
-if exists('loaded_put_date')
+if exists('loaded_put_date') || &compatible || !has('*strftime')
   finish
 endif
 let loaded_put_date = 1
-command! -bar -range PutDate
-      \ <line1>put =strftime('%a, %d %b %Y %T %z')
+command! -bang -bar -nargs=* -range PutDate
+      \ call put_date#(<q-line1>, <q-bang> ==# '!', <q-args>)
diff --git a/vim/plugin/select_old_files.vim b/vim/plugin/select_old_files.vim
index dbfbd64c..77c7746e 100644
--- a/vim/plugin/select_old_files.vim
+++ b/vim/plugin/select_old_files.vim
@@ -1,6 +1,8 @@
-if exists('loaded_select_old_files')
+if exists('loaded_select_old_files') || &compatible || !exists(':oldfiles')
   finish
 endif
 let loaded_select_old_files = 1
-command! -bar SelectOldFiles
-      \ call select_old_files#()
+command! -bar -nargs=? SelectOldFiles
+      \ call select_old_files#(<f-args>)
+nnoremap <Plug>SelectOldFiles
+      \ :<C-U>SelectOldFiles<CR>
diff --git a/vim/plugin/spellfile_local.vim b/vim/plugin/spellfile_local.vim
index c026d626..f6918bfb 100644
--- a/vim/plugin/spellfile_local.vim
+++ b/vim/plugin/spellfile_local.vim
@@ -1,19 +1,12 @@
-if exists('loaded_spellfile_local')
+if exists('loaded_spellfile_local') || &compatible
   finish
 endif
 let loaded_spellfile_local = 1
 
-let s:spellfile = join([
-      \ substitute(v:lang, '_.*', '', ''),
-      \ &encoding
-      \ ], '.') . '.add'
-Establish $MYVIM/cache/spell
-execute 'set spellfile=$MYVIM/cache/spell/'.s:spellfile
-
-command! -bar AddLocalSpellFile
+command! -bar SetLocalSpellFiles
       \ call spellfile_local#()
 
 augroup spellfile_local
   autocmd BufNew,BufRead *
-        \ AddLocalSpellFile
+        \ SetLocalSpellFiles
 augroup END
diff --git a/vim/plugin/utc.vim b/vim/plugin/utc.vim
deleted file mode 100644
index 9b8b647a..00000000
--- a/vim/plugin/utc.vim
+++ /dev/null
@@ -1,6 +0,0 @@
-if exists('loaded_utc')
-  finish
-endif
-let loaded_utc = 1
-command! -bar -complete=command -nargs=1 UTC
-      \ call utc#(<q-args>)
diff --git a/vim/vimrc b/vim/vimrc
index 5d12b321..9cc74c3b 100644
--- a/vim/vimrc
+++ b/vim/vimrc
@@ -103,9 +103,9 @@ scriptencoding utf-8
 " Vim, I love you, but you are really weird.
 "
 let s:runtimepath = map(
-      \ split(&runtimepath, '\\\@<!,[, ]*'),
-      \ "substitute(v:val, '\\\\,', '', 'g')"
-      \ )
+      \ split(&runtimepath, '\\\@<!,[, ]*')
+      \,"substitute(v:val, '\\\\,', '', 'g')"
+      \)
 if !exists('$MYVIM')
   let $MYVIM = s:runtimepath[0]
 endif
@@ -398,6 +398,22 @@ if has('persistent_undo')
   set undodir^=$MYVIM/cache/undo//
 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.  We'll set the 'spellfile' option too, to
+" place it in the cache directory into which we've been putting everything.
+" We'll follow Vim's standard naming convention for the file itself, though.
+" If available, my plugin spellfile_local.vim will extend this later to add
+" more spelling word lists per filetype and per file.
+"
+set spelllang=en_nz
+Establish $MYVIM/cache/spell
+let &spellfile = $MYVIM.'/cache/spell/'.join([
+      \ substitute(&spelllang, '_.*', '', '')
+      \,&encoding
+      \,'add'
+      \], '.')
+
 " 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,
@@ -991,7 +1007,7 @@ autocmd vimrc ColorScheme sahara
 
 " We'll have Vim try to use my 'sahara' fork of the 'desert256' color scheme.
 " If we fail to load the color scheme, for whatever reason, suppress the
-" error, and default to a dark background (if not already) for the the default
+" error, and default to a dark background (if not already) for the default
 " color scheme in the absence of guidance otherwise from a COLORFGBG
 " environment variable or a t_RB terminal response.  Vim otherwise defaults to
 " 'light', which is less likely in my case.
@@ -1384,15 +1400,15 @@ nnoremap <Leader>t
 nnoremap <Leader>T
       \ :<C-U>setlocal filetype=<CR>
 
-" These mappings use my put_date.vim and utc.vim plugins for date insertion
-" into the buffer.
+" 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
-      \ :<Home>UTC<End> PutDate<CR>
+      \ :PutDate!<CR>
 
 " This group contains mappings that are to do with file and path management
 " relative to the current buffer.  The Leader,P mapping that creates
@@ -1466,12 +1482,11 @@ nnoremap <Leader>j
 
 " 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'
-" keypress before entering the number.  This one is handy followed by
+" 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.
 "
-nnoremap <Leader>o
-      \ :<C-U>SelectOldFiles<CR>
+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:
@@ -1555,6 +1570,9 @@ nnoremap <Leader>?
 "" Leader,. runs the configured make program into the location list
 nnoremap <Leader>.
       \ :<C-U>lmake!<CR>
+"" Leader,! repeats the last command, adding a bang
+nnoremap <Leader>!
+      \ :<Up><Home><S-Right>!<CR>
 "" Leader,q formats the current paragraph
 nnoremap <Leader>q gqap
 "" Leader,r acts as a replacement operator