Merge branch 'release/v8.34.0'v8.34.0

* release/v8.34.0:
  Rewriting commentary on vimrc
  Use :keepjumps for HTML timestamp update
  Remove unneeded <silent> modifiers from maps
  Break map definitions consistently
  Break abbreviation definitions for readability

3 files changed, 160 insertions, 90 deletions

diff --git a/VERSION b/VERSION
index 7063a55e..9eb40434 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-tejr dotfiles v8.33.0
-Mon, 11 May 2020 00:46:06 +0000
+tejr dotfiles v8.34.0
+Mon, 11 May 2020 11:49:11 +0000
diff --git a/vim/autoload/html/timestamp.vim b/vim/autoload/html/timestamp.vim
index 9de19aa0..6d525afb 100644
--- a/vim/autoload/html/timestamp.vim
+++ b/vim/autoload/html/timestamp.vim
@@ -69,6 +69,6 @@ function! html#timestamp#Update() abort
   " Apply the updated timestamp
   let line = getline(lnum)
   let line = substitute(line, s:pattern, update, '')
-  call setline(lnum, line)
+  keepjumps call setline(lnum, line)
 
 endfunction
diff --git a/vim/vimrc b/vim/vimrc
index 32dbabcd..06ea0637 100644
--- a/vim/vimrc
+++ b/vim/vimrc
@@ -2,7 +2,7 @@
 "  Tom Ryder (tejr)’s Literate Vimrc
 " ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 "
-" Last updated: Sat, 09 May 2020 04:57:54 UTC
+" Last updated: Mon, 11 May 2020 09:22:45 UTC
 "
 " │ And I was lifted up in heart, and thought
 " │ Of all my late-shown prowess in the lists,
@@ -14,6 +14,7 @@
 " │
 " │     —Tennyson
 "
+
 " This file is an attempt at something like a “literate vimrc”, in the
 " tradition of Donald Knuth’s “literate programming”:
 " <http://www.literateprogramming.com/>
@@ -27,32 +28,44 @@
 "
 "     :g/\m^$\|^\s*"/d
 "
-" This file requires Vim v7.0.0 or newer—including the +eval feature—and with
-" the 'compatible' option turned off, chiefly to allow line continuations in
-" Vim script.  The vimrc stub at ~/.vimrc (Unix) or ~/_vimrc (Windows) should
-" check that these conditions are met before loading this file with ‘:runtime
-" vimrc’.  It should be saved as ‘vimrc’—note no leading period—in the user
+" 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’.
-"
-" The whole file should survive a pass of the Vim script linter Vint with no
-" errors, warnings, or style problems: <https://github.com/Kuniwak/vint>
-"
-" We’ll begin by making sure that we 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.  This prompts Vint to suggest
-" declaring the file encoding with a :scriptencoding command.  The :help for
-" :scriptencoding specifies that this should be done after 'encoding' is set,
-" so we’ll do that here first.
-"
-" On POSIX-fearing operating systems, I define the primary locale environment
-" variable $LANG, almost always specifying a multi-byte locale.  This informs
-" Vim’s choice of internal character encoding.  The default for the 'encoding'
-" option in the absence of a valid $LANG setting is ‘latin1’.  Since this is
-" almost never what I want, we’ll explicitly fall back to the UTF-8 encoding
-" for Unicode, in the absence of any other explicit specification.  We need to
-" test that the +multi_byte feature is available before doing this, however,
-" since it was a non-default compile-time option in Vim v7.0.
+" ‘~/.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')
@@ -64,53 +77,75 @@ 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, even with Vim’s unusual behavior around escaping of
-" these variables.  One of the first things we’ll need to be able to do is
-" split the value of 'runtimepath' into its constituent path parts.
+" accurately as possible, accounting for Vim’s unusual escaping behavior for
+" these list options.
 "
-" Correctly splitting the values of comma-separated Vim options is
-" surprisingly complicated.  The delimiter for such options is not simply
-" any comma; it is more accurately defined as follows:
+" 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 required for the split therefore breaks down like this:
+" 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, here a backslash, cannot precede
-"            what follows, but anything that does precede it is not removed
-"            from the data as part of the split delimiter
+"            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.  You can read the source code for the ad-hoc
-" tokenizer in copy_option_part() in src/misc2.c in Vim’s source code, and
-" test it with some values of your own, if you want to understand why.
+" 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 love you, but you are really weird sometimes.
+" Vim, I do love you, but sometimes you're really weird.
 "
-" We do all this with an autoloaded function option#Split(); see
+" 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'.
+" first value from the 'runtimepath'.  We'll use this later on in the file to
+" comprehensively match expected paths for vimrc files.
 "
 if &runtimepath !=# ''
   let $MYVIM = option#Split(&runtimepath)[0]
 endif
 
-" The next components of the runtime directory that we'll set up here will be
-" the XDG base directories, for machine-local configuration and storage for
-" files outside this repository.
+" 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>
 "
-" Add all the configuration directories to 'runtimepath', including "after"
-" directories to the end of it, in reverse order, forming the desired layers
-" of configuration.
+" 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 the autoloaded xdg#() function.  We need to copy() it
+" because of Vim's implicit semantics for map() and reverse(), otherwise we'll
+" edit the values in-place.  Man, my kingdom for Perl…
+"
+" We put XDG_CONFIG_HOME at the front of the 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…
 "
 let s:xdgconfigpaths = copy(xdg#['config']['dirs'])
 if xdg#['config']['home'] !=# ''
@@ -121,6 +156,8 @@ if !empty(s:xdgconfigpaths)
         \ copy(s:xdgconfigpaths),
         \ 'option#item#Escape(v:val)'
         \), ','))
+endif
+if !empty(s:xdgconfigpaths)
   execute 'set runtimepath+='.option#Escape(join(map(
         \ reverse(copy(s:xdgconfigpaths)),
         \ 'option#item#Escape(v:val.''/after'')'
@@ -1004,7 +1041,8 @@ endif
 " 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-^>
+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
@@ -1015,8 +1053,8 @@ nnoremap <Backspace> <C-^>
 "
 nnoremap <expr> <Space>
       \ line('w$') < line('$')
-      \ ? "\<PageDown>"
-      \ : ":\<C-U>next\<CR>"
+        \ ? "\<PageDown>"
+        \ : ":\<C-U>next\<CR>"
 
 " I hate CTRL-C’s default insert mode behavior.  It ends the insert session
 " without firing the InsertLeave event for automatic command hooks.  Why would
@@ -1055,7 +1093,8 @@ nnoremap <expr> <Space>
 " uselessness.
 "
 if plugin#Ready('insert_cancel')
-  imap <C-C> <Plug>(InsertCancel)
+  imap <C-C>
+        \ <Plug>(InsertCancel)
 endif
 
 " I often can’t remember (or guess) digraph codes, and want to look up how to
@@ -1089,7 +1128,8 @@ endif
 " checking that the plugin’s available before we map to it; it’ll just quietly
 " do nothing.
 "
-imap <C-K><C-K> <Plug>(DigraphSearch)
+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
@@ -1112,14 +1152,16 @@ nnoremap <C-L>
 " 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>
+inoremap <C-L>
+      \ <C-O>:execute "normal \<C-L>"<CR>
 
 " We use :vnoremap here rather than :xnoremap and thereby make the mapping
 " apply to select mode as well, because CTRL-L doesn’t reflect a printable
 " character, and so we may as well make it work, even though I don’t actually
 " use select mode directly.
 "
-vmap <C-L> <Esc><C-L>gv
+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
@@ -1138,7 +1180,8 @@ sunmap &
 "
 " <https://sanctum.geek.nz/cgit/vim-colon-operator.git/about/>
 "
-nmap g: <Plug>(ColonOperator)
+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
@@ -1174,8 +1217,10 @@ nnoremap ]l
 "
 " <https://sanctum.geek.nz/cgit/vim-put-blank-lines.git/about/>
 "
-nmap [<Space> <Plug>(PutBlankLinesAbove)
-nmap ]<Space> <Plug>(PutBlankLinesBelow)
+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
@@ -1196,7 +1241,8 @@ let maplocalleader = ','
 " relying on mapping 'timeout'.
 "
 if maplocalleader ==# ','
-  noremap ,, ,
+  noremap ,,
+        \ ,
   sunmap ,,
 endif
 
@@ -1291,7 +1337,8 @@ nnoremap <Leader>u
 "
 
 "" Leader,b toggles settings friendly to copying and pasting
-nmap <Leader>b <Plug>(CopyLinebreakToggle)
+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
@@ -1315,7 +1362,8 @@ sunmap <Leader>L
 " kept confusing me.  I’m hoping this will be better.
 
 "" Leader,p prepares the next insert for paste mode
-nmap <Leader>p <Plug>PasteInsert
+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
@@ -1417,7 +1465,8 @@ nnoremap <Leader>j
 " <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)
+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:
@@ -1458,7 +1507,8 @@ onoremap <Leader>_
 "" Leader,% or Leader,5 uses entire buffer as an object
 onoremap <Leader>%
       \ :<C-U>execute 'normal! 1GVG'<CR>
-omap <Leader>5 <Leader>%
+omap <Leader>5
+      \ <Leader>%
 
 " This group defines some useful motions, including navigating by indent
 " block using a custom plugin:
@@ -1467,12 +1517,15 @@ omap <Leader>5 <Leader>%
 "
 
 "" Leader,{ and Leader,} move to top and bottom of indent region
-map <Leader>{ <Plug>(VerticalRegionUp)
+map <Leader>{
+      \ <Plug>(VerticalRegionUp)
 sunmap <Leader>{
-map <Leader>} <Plug>(VerticalRegionDown)
+map <Leader>}
+      \ <Plug>(VerticalRegionDown)
 sunmap <Leader>}
 "" Leader,\ jumps to the last edit position mark; think “Now, where was I?”
-noremap <Leader>\ `"
+noremap <Leader>\
+      \ `"
 sunmap <Leader>\
 
 " This group does both: useful motions on defined text objects.
@@ -1506,40 +1559,50 @@ nnoremap <Leader>?
 nnoremap <Leader>.
       \ :<C-U>lmake!<CR>
 "" Leader,q formats the current paragraph
-nnoremap <Leader>q gqap
+nnoremap <Leader>q
+      \ gqap
 "" Leader,r acts as a replacement operator
-map <Leader>r <Plug>(ReplaceOperator)
+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>!
+nmap <Leader>1
+      \ <Leader>!
 "" Leader,#/3 switches the current buffer to the next alternate filetype
-nmap <Leader># <Plug>(AlternateFileType)
-nmap <Leader>3 <Leader>#
+nmap <Leader>#
+      \ <Plug>(AlternateFileType)
+nmap <Leader>3
+      \ <Leader>#
 "" Leader,$/4 gives me my fortune
-nmap <Leader>$ <Plug>(Fortune)
-nmap <Leader>4 <Leader>$
+nmap <Leader>$
+      \ <Plug>(Fortune)
+nmap <Leader>4
+      \ <Leader>$
 "" Leader,&/7 escapes regex metacharacters
-map <Leader>& <Plug>(RegexEscape)
+map <Leader>&
+      \ <Plug>(RegexEscape)
 ounmap <Leader>&
 sunmap <Leader>&
-map <Leader>7 <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 <silent> <Leader>*
-      \ :<C-U>let @/ = expand('<cword>')<CR>:let &hlsearch = &hlsearch<CR>
-nmap <Leader>8 <Leader>*
+nnoremap <Leader>*
+      \ :<C-U>let @/ = expand('<cword>') <Bar> let &hlsearch = &hlsearch<CR>
+nmap <Leader>8
+      \ <Leader>*
 "" Leader,` opens a scratch buffer, horizontally split
-nnoremap <silent> <Leader>`
+nnoremap <Leader>`
       \ :<C-U>ScratchBuffer<CR>
 "" Leader,~ opens a scratch buffer, vertically split
-nnoremap <silent> <Leader>~
+nnoremap <Leader>~
       \ :<C-U>vertical ScratchBuffer<CR>
 
 " And last, but definitely not least, I’m required by Vim fanatic law to
@@ -1556,17 +1619,24 @@ nnoremap <Leader>R
 " pretty useful.  First, some 'deliberate' abbreviations for stuff I type
 " a lot:
 "
-inoreabbrev tr@ tom@sanctum.geek.nz
-inoreabbrev tr/ <https://sanctum.geek.nz/>
+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 THe The
-inoreabbrev THere There
+inoreabbrev almsot
+      \ almost
+inoreabbrev wrnog
+      \ wrong
+inoreabbrev Fielding
+      \ Feilding
+inoreabbrev THe
+      \ The
+inoreabbrev THere
+      \ There
 
 " Here endeth the literate vimrc.  Let us praise God.
 "