aboutsummaryrefslogtreecommitdiff
path: root/vim
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2020-05-11 20:56:35 +1200
committerTom Ryder <tom@sanctum.geek.nz>2020-05-11 21:28:15 +1200
commit44c5ff70edb8792d5986680e5df88a033fb05195 (patch)
tree7846de2825c41f28b1fc00d459d11f07949bca7e /vim
parentRemove unneeded <silent> modifiers from maps (diff)
downloaddotfiles-44c5ff70edb8792d5986680e5df88a033fb05195.tar.gz
dotfiles-44c5ff70edb8792d5986680e5df88a033fb05195.zip
Rewriting commentary on vimrc
Diffstat (limited to 'vim')
-rw-r--r--vim/vimrc133
1 files changed, 85 insertions, 48 deletions
diff --git a/vim/vimrc b/vim/vimrc
index 98c109a3..06ea0637 100644
--- a/vim/vimrc
+++ b/vim/vimrc
@@ -2,7 +2,7 @@
" Tom Ryder (tejr)’s Literate Vimrc
" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
"
-" Last updated: Mon, 11 May 2020 06:25:19 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'')'