From 44c5ff70edb8792d5986680e5df88a033fb05195 Mon Sep 17 00:00:00 2001 From: Tom Ryder Date: Mon, 11 May 2020 20:56:35 +1200 Subject: Rewriting commentary on vimrc --- vim/vimrc | 133 +++++++++++++++++++++++++++++++++++++++----------------------- 1 file 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”: " @@ -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: -" -" 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. +" + +" 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. +" +" " 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 " \@ " -" 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", +" +" +" 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'')' -- cgit v1.2.3