aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2020-05-03 22:39:55 +1200
committerTom Ryder <tom@sanctum.geek.nz>2020-05-03 22:39:55 +1200
commitbac8ed9829a6a767091662fab056f460d187f246 (patch)
tree028fb5342fa8a4a8f9eb6388c927a46bf4b978ed
parentMerge branch 'release/v8.26.0' (diff)
parentUpdate dotfiles(7) manual page (diff)
downloaddotfiles-bac8ed9829a6a767091662fab056f460d187f246.tar.gz
dotfiles-bac8ed9829a6a767091662fab056f460d187f246.zip
Merge branch 'release/v8.27.0'v8.27.0
* release/v8.27.0: Update dotfiles(7) manual page Reflow features list Remove spaces around em-dashes Many README.md improvements in phrasing or grammar Order sub-targets of `install` correctly
-rw-r--r--Makefile2
-rw-r--r--README.md206
-rw-r--r--VERSION4
-rw-r--r--man/man7/dotfiles.7df216
4 files changed, 231 insertions, 197 deletions
diff --git a/Makefile b/Makefile
index 8e537c84..098907c8 100644
--- a/Makefile
+++ b/Makefile
@@ -350,8 +350,8 @@ install: install-bin \
install-git \
install-gnupg \
install-less \
- install-man \
install-login-shell \
+ install-man \
install-readline \
install-vim
diff --git a/README.md b/README.md
index dab9534e..b75c368f 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ This is my personal repository of configuration files and scripts for `$HOME`,
including most of the settings that migrate well between machines.
This repository began as a simple way to share Vim and tmux configuration, but
-over time a lot of scripts and shell configuration have been added, making it
+a lot of scripts and shell configuration have been added over time, making it
into a personal suite of custom Unix tools.
Installation
@@ -23,11 +23,11 @@ Installation
For the default `all` target, you'll need a POSIX-fearing userland, including
`make(1)` and `m4(1)`.
-The installation `Makefile` will overwrite things standing in the way of its
+The installation `Makefile` overwrites things standing in the way of its
installed files without backing them up, so read the output of `make -n
-install` before running `make install` to make sure you aren't going to lose
+install` before running `make install` carefully, to make sure you aren't going to lose
anything unexpected. If you're still not sure, install it in a temporary
-directory so you can explore:
+directory first, so you can explore:
$ tmpdir=$(mktemp -d)
$ make install HOME="$tmpdir"
@@ -37,17 +37,17 @@ The default `install` target will install these targets and all their
dependencies:
* `install-bin`
-* `install-bin-man`
* `install-curl`
* `install-ex`
* `install-git`
* `install-gnupg`
* `install-less`
* `install-login-shell`
+* `install-man`
* `install-readline`
* `install-vim`
-The `install-login-shell` looks at your `SHELL` environment variable and tries
+The `install-login-shell` target looks at your `SHELL` environment variable, and tries
to figure out which shell's configuration files to install, falling back on
`install-sh`.
@@ -56,8 +56,8 @@ The remaining files can be installed with the other `install-*` targets. Try
### Configuration
-To save a set of `make` targets useful for a specific user or host, you can
-save them in a newline-separated file `~/.local/share/dotfiles.conf`, and
+To keep a set of `make` targets useful for a specific user or host, you can
+list them in a newline-separated file `~/.local/share/dotfiles.conf`, and
install using that with the special `install-conf` target. This can include
variable settings, too:
@@ -75,82 +75,85 @@ Configuration is included for:
* Bourne-style POSIX shells, sharing a `.profile`, an `ENV` file, and some
helper functions:
- * [GNU Bash](https://www.gnu.org/software/bash/) (3.0 or higher)
+ * [GNU Bash](https://www.gnu.org/software/bash/) (v3.0 or newer)
* [Korn shell](http://www.kornshell.com/) (`ksh93`, `pdksh`, `mksh`)
* [Z shell](https://www.zsh.org/)
-* [Abook](http://abook.sourceforge.net/) -- curses address book program
-* [cURL](https://curl.haxx.se/) -- Command-line tool for transferring data with
+* [Abook](http://abook.sourceforge.net/)--curses address book program
+* [cURL](https://curl.haxx.se/)--Command-line tool for transferring data with
URL syntax
-* [Dillo](https://www.dillo.org/) -- A lightweight web browser
-* [Dunst](https://dunst-project.org/) -- A lightweight X11 notification daemon
+* [Dillo](https://www.dillo.org/)--A lightweight web browser
+* [Dunst](https://dunst-project.org/)--A lightweight X11 notification daemon
that works with `libnotify`
-* `finger(1)` -- User information lookup program
-* [Git](https://git-scm.com/) -- Distributed version control system
-* [GNU Emacs](https://www.gnu.org/software/emacs/) -- Extensible text editor
-* [GnuPG](https://www.gnupg.org/) -- GNU Privacy Guard, for private
- communication and file encryption
-* [GTK+](https://www.gtk.org/) -- GIMP Toolkit, for graphical user interface
+* `finger(1)`--User information lookup program
+* [Git](https://git-scm.com/)--Distributed version control system
+* [GNU Emacs](https://www.gnu.org/software/emacs/)--Extensible text editor
+* [GnuPG](https://www.gnupg.org/)--GNU Privacy Guard, for private communication
+ and file encryption
+* [GTK+](https://www.gtk.org/)--GIMP Toolkit, for graphical user interface
elements
-* [i3](https://i3wm.org/) -- Tiling window manager
-* [less](https://www.gnu.org/software/less/) -- Terminal pager
-* [mpv](https://mpv.io/) -- Media player
-* [Mutt](http://www.mutt.org/) -- Terminal mail user agent
-* [`mysql(1)`](https://linux.die.net/man/1/mysql) -- Command-line MySQL client
-* [Ncmpcpp](https://rybczak.net/ncmpcpp/) -- ncurses music player client
-* [Newsboat](https://newsboat.org/) -- Terminal RSS/Atom feed reader
-* [`psql(1)`](https://linux.die.net/man/1/psql) -- Command-line PostgreSQL
- client
-* [Perl::Critic](http://perlcritic.com/) -- static source code analysis engine
+* [i3](https://i3wm.org/)--Tiling window manager
+* [less](https://www.gnu.org/software/less/)--Terminal pager
+* [mpv](https://mpv.io/)--Media player
+* [Mutt](http://www.mutt.org/)--Terminal mail user agent
+* [`mysql(1)`](https://linux.die.net/man/1/mysql)--Command-line MySQL client
+* [Ncmpcpp](https://rybczak.net/ncmpcpp/)--ncurses music player client
+* [Newsboat](https://newsboat.org/)--Terminal RSS/Atom feed reader
+* [`psql(1)`](https://linux.die.net/man/1/psql)--Command-line PostgreSQL client
+* [Perl::Critic](http://perlcritic.com/)--static source code analysis engine
for Perl
-* [Perl::Tidy](http://perltidy.sourceforge.net/) -- Perl source code
- reformatter
-* [Readline](https://tiswww.case.edu/php/chet/readline/rltop.html) -- GNU
- library for user input used by Bash, MySQL, and others
-* [rxvt-unicode](http://software.schmorp.de/pkg/rxvt-unicode.html) -- Fork of
- the rxvt terminal emulator with Unicode support
-* [Subversion](https://subversion.apache.org/) -- Apache Subversion, a version
+* [Perl::Tidy](http://perltidy.sourceforge.net/)--reformats Perl source code
+* [Readline](https://tiswww.case.edu/php/chet/readline/rltop.html)--GNU library
+ for user input used by Bash, MySQL, and others
+* [rxvt-unicode](http://software.schmorp.de/pkg/rxvt-unicode.html)--Fork of the
+ rxvt terminal emulator with Unicode support
+* [Subversion](https://subversion.apache.org/)--Apache Subversion, a version
control system
-* [tidy](http://www.html-tidy.org/) -- HTML/XHTML linter and tidier
-* [tmux](https://tmux.github.io/) -- Terminal multiplexer similar to GNU Screen
-* [Vim](https://www.vim.org/) -- Vi IMproved, a text editor
-* [X11](https://www.x.org/wiki/) -- Windowing system with network transparency
+* [tidy](http://www.html-tidy.org/)--HTML/XHTML linter and tidier
+* [tmux](https://tmux.github.io/)--Terminal multiplexer similar to GNU Screen
+* [Vim](https://www.vim.org/)--Vi IMproved, a text editor
+* [X11](https://www.x.org/wiki/)--Windowing system with network transparency
for Unix
-The configurations for shells, Mutt, tmux, and Vim are the most
-expansive, and most likely to be of interest. The i3 configuration is mostly
-changed to make window switching behave like Vim windows and tmux panes do, and
-there's a fair few resources defined for rxvt-unicode.
+The configurations for shells, Mutt, tmux, and Vim are the most likely to be of
+interest. The i3 configuration is limited mainly to changing window switching
+key bindings to match Vim's. There are a fair few resources defined for
+rxvt-unicode.
### Shell
-My `.profile` and other files in `sh` are written in POSIX shell script, so
-they should work in most `sh(1)` implementations. Individual scripts called by
-`.profile` are saved in `.profile.d` and iterated on login for ease of
-management. Most of these boil down to exporting variables appropriate to the
-system and the software it has available.
+On GNU/Linux, I use Bash; on \*BSD, I use some variant of Korn Shell,
+preferably `ksh93` if it's available.
-Configuration that should be sourced for all POSIX-fearing interactive shells
-is kept in `~/.shrc`, with subscripts read from `~/.shrc.d`. There's a shim in
-`~/.shinit` to act as `ENV`. I make an effort to target POSIX for my functions
-and scripts where I can so that the same files can be loaded for all shells.
+#### POSIX core
-On GNU/Linux I use Bash, on BSD I use some variant of Korn Shell, preferably
-`ksh93` if it's available.
+My `~/.profile` and other files in `sh` are written in POSIX shell script, so
+they *should* work in most POSIX-conforming `sh(1)` implementations. Please
+email me if you find a case where they don't!
-My Bash is written to work with [any version 3.0 or
+Further shell snippets to run on login are sourced from `~/.profile.d` by
+`~/.profile`. Most of these boil down to exporting variables appropriate to
+the system and the software it has available.
+
+Configuration that should be sourced for all conforming *interactive* shells is
+kept in `~/.shrc`, with subscripts read from `~/.shrc.d`. There's
+a `~/.shinit` shim to act as `ENV`.
+
+#### GNU Bash
+
+My Bash scripts are written to work with GNU Bash [v3.0 or
newer](https://wiki.bash-hackers.org/scripting/bashchanges). This is why I use
older syntax for certain things such as appending items to arrays:
array[${#array[@]}]=$item
-Compare this to the much nicer syntax available since 3.1-alpha1, which
-actually works for arrays with sparse indices, unlike the above syntax:
+This doesn't work for arrays with sparse indices; compare this to the much
+nicer syntax available since 3.1-alpha1, which does:
array+=("$item")
-Where I do use features that are only available in versions of Bash newer than
-3.0, such as newer `shopt` options or `PROMPT_DIRTRIM`, they are only run after
-testing `BASH_VERSINFO` appropriately.
+I do use some features that are only available in versions after v3.0, such as
+newer `shopt` options like `dirspell`, or variables like `PROMPT_DIRTRIM`.
+These are set only after testing `BASH_VERSINFO` appropriately.
#### Prompt
@@ -170,20 +173,22 @@ A terminal session with my prompt looks something like this:
The hostname is elided if not connected via SSH. The working directory with
tilde abbreviation for `$HOME` is always shown. The rest of the prompt expands
-based on context to include these elements in this order:
+based on context to include these elements, in this order:
-* Whether in a Git repository if applicable, and punctuation to show repository
- status including reference to upstreams at a glance. Subversion support can
- also be enabled (I need it at work), in which case a `git:` or `svn:` prefix
- is added appropriately.
+* Whether in a Git repository if applicable,
+
+* The current version control branch, tag, or commit/revision if applicable,
+ and punctuation to show repository status including reference to upstreams at
+ a glance. Subversion support can also be enabled, in which case a `git:` or
+ `svn:` prefix is added appropriately for disambiguation.
* The number of running background jobs, if non-zero.
* The exit status of the last command, if non-zero.
You can set `PROMPT_COLOR`, `PROMPT_PREFIX`, and `PROMPT_SUFFIX` too, which all
do about what you'd expect.
-If you start up Bash, Korn shell, or Z shell, and it detects that it's not your
-login shell, the prompt will display an appropriate prefix.
+If you start up GNU Bash, Korn shell, or Z shell, and that doesn't match your
+login shell, the prompt should display an appropriate prefix.
This is all managed within the `prompt` function. There's some mildly hacky
logic on `tput` codes included such that it should work correctly for most
@@ -248,7 +253,7 @@ non-POSIX features, as compatibility allows:
* `pushd()` adds a default destination of `$HOME` to the `pushd` builtin
(Bash).
* `vared()` allows interactively editing a variable with Readline, emulating a
- Zsh function I like by the same name (Bash).
+ Z shell function I like by the same name (Bash).
* `ver()` prints the current shell's version information (Bash, Korn Shell, Z
shell).
@@ -293,9 +298,9 @@ colored cyan.
### Mutt
-My mail is kept in individual Maildirs under `~/mail`, with the system mail
-spool in e.g. `/var/mail/tejr` being where most unfiltered mail is sent. I use
-[Getmail](http://pyropus.ca/software/getmail/),
+My mail is kept in individual Maildir-format directories under `~/mail`, with
+the system mail spool in e.g. `/var/mail/tejr` being where most unfiltered mail
+is sent. I use [Getmail](http://pyropus.ca/software/getmail/),
[maildrop](https://www.courier-mta.org/maildrop/), and
[msmtp](https://marlam.de/msmtp/); the configurations for these are not
included here. I sign whenever I have some indication that the recipient might
@@ -321,10 +326,10 @@ Perl extensions. If you're missing functionality, try changing
### tmux
-These are just generally vi-friendly settings, not much out of the ordinary.
-Note that the configuration presently uses a hard-coded 256-color color scheme,
-and uses non-login shells, with an attempt to control the environment to stop
-shells thinking they have access to an X display.
+These are just generally vi-friendly settings, and there isn't much out of the
+ordinary. Note that the configuration presently uses a hard-coded 256-color
+color scheme, and uses non-login shells, with an attempt to control the
+environment to stop shells thinking they have access to an X display.
The shell scripts in `bin` include `tm(1df)`, a shortcut to make `attach` into
the default command if no arguments are given and sessions do already exist.
@@ -334,9 +339,19 @@ key combination to detach.
### Vim
The majority of the Vim configuration is just setting options, with a fair few
-mappings and remappings, both global and buffer-local. I try not to deviate
-too much from the Vim defaults behavior in terms of interactive behavior and
-keybindings. It's extensively commented.
+mappings and remappings, both global and buffer-local. It's extensively
+commented.
+
+#### XDG Basedirs
+
+The [XDG Base Directory
+Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)'s
+environment variables are checked on startup, and appropriate directories are
+added to the start and end of `'runtimepath'`. I use these separate
+directories for machine-local configuration, usually in `~/.config/vim`, while
+all the files that this suite installs land in `~/.vim`. Backups, swap files,
+persistent undo data, saved views, and the `viminfo` file all live under
+`XDG_CACHE_HOME`, normally `~/.cache/vim`.
#### Filetypes
@@ -348,21 +363,21 @@ filetypes in custom `ftdetect` rules.
#### Plugins
If the logic for doing something involves more than a few lines or any
-structures like functions, I like to implement it as a plugin in
-`~/.vim/plugin` and/or `~/.vim/autoload`, with documentation for each in
-`~/.vim/doc`.
+structures like functions that can be decoupled from `$MYVIMRC`, I like to
+implement it as a plugin in `~/.vim/plugin` and/or `~/.vim/autoload`, with
+documentation for each in `~/.vim/doc`.
They eventually get either discarded if I stop using them, or spun off into
-their own repositories if I don't, and added to this repository as submodules
-under `vim/bundle` instead. Some of them I upload to
+their own repositories and added to this repository as submodules under
+`vim/bundle` if I don't. Some of them I upload to
[vim.org](https://www.vim.org/account/profile.php?user_id=73687).
#### Filetype plugins
I apply some replacement or supplementary configuration specific to file types
I often edit in `~/.vim` and `~/.vim/after`, in the `ftplugin`, `indent`, and
-`syntax` subdirectories. Some of these filetype plugins or extensions will
-also eventually be removed to be separately distributed, and installed via
+`syntax` subdirectories. Some of these filetype plugins or extensions may also
+eventually be removed to be separately distributed, and installed via
submodules instead.
#### Compilers
@@ -376,17 +391,19 @@ it good?"--with separate local leader maps; for example, for `perl` filetypes,
#### No Neovim support
The configuration doesn't explicitly support Neovim, although most of it will
-probably work.
+probably work; you would probably just comment out the settings for a few of
+the removed options.
Scripts
-------
Where practical, I make short scripts into POSIX (but not Bourne) `sh(1)`,
`awk(1)`, or `sed(1)` scripts in `~/.local/bin`. I try to use shell functions
-only when I actually need to, which tends to be when I need to tinker with the
-namespace of the user's current shell.
+only when I actually need to, which tends to be when I need to change the state
+of the user's current shell, or to limit a change in behavior only to
+interactive shells.
-Installed by the `install-bin` target:
+These scripts are installed by the `install-bin` target:
* Three SSH-related scripts:
* `sls(1df)` prints hostnames read from a `ssh_config(5)` file. It uses
@@ -608,16 +625,15 @@ There's some silly stuff in `install-games`:
Manuals
-------
-The `install-bin` and `install-games` targets install manuals for each script
-they install. If you want to use the manuals, you may need to add
-`~/.local/share/man` to your `~/.manpath` or `/etc/manpath` configuration,
-depending on your system.
+The `install-bin` and `install-games` targets install manuals for each script.
+If you want to read the manuals, you may need to add `~/.local/share/man` to
+your `~/.manpath` or `/etc/manpath` configuration, depending on your system.
Testing
-------
You can check that both sets of shell scripts are syntactically correct with
-`make check-bash`, `make check-sh`, or `make check` for everything including
+`make check-bash` or `make check-sh`, or `make check` for everything including
the scripts in `bin` and `games`. There's no proper test suite for the actual
functionality (yet).
diff --git a/VERSION b/VERSION
index fa9a8612..31dbc5f6 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-tejr dotfiles v8.26.0
-Sun, 03 May 2020 09:59:43 +0000
+tejr dotfiles v8.27.0
+Sun, 03 May 2020 10:39:52 +0000
diff --git a/man/man7/dotfiles.7df b/man/man7/dotfiles.7df
index dd4c2286..9f76496d 100644
--- a/man/man7/dotfiles.7df
+++ b/man/man7/dotfiles.7df
@@ -9,8 +9,8 @@ This is my personal repository of configuration files and scripts for
machines.
.PP
This repository began as a simple way to share Vim and tmux
-configuration, but over time a lot of scripts and shell configuration
-have been added, making it into a personal suite of custom Unix tools.
+configuration, but a lot of scripts and shell configuration have been
+added over time, making it into a personal suite of custom Unix tools.
.SS Installation
.IP
.nf
@@ -29,12 +29,12 @@ $\ make\ install
For the default \f[C]all\f[] target, you'll need a POSIX\-fearing
userland, including \f[C]make(1)\f[] and \f[C]m4(1)\f[].
.PP
-The installation \f[C]Makefile\f[] will overwrite things standing in the
-way of its installed files without backing them up, so read the output
-of \f[C]make\ \-n\ install\f[] before running \f[C]make\ install\f[] to
-make sure you aren't going to lose anything unexpected.
-If you're still not sure, install it in a temporary directory so you can
-explore:
+The installation \f[C]Makefile\f[] overwrites things standing in the way
+of its installed files without backing them up, so read the output of
+\f[C]make\ \-n\ install\f[] before running \f[C]make\ install\f[]
+carefully, to make sure you aren't going to lose anything unexpected.
+If you're still not sure, install it in a temporary directory first, so
+you can explore:
.IP
.nf
\f[C]
@@ -49,8 +49,6 @@ their dependencies:
.IP \[bu] 2
\f[C]install\-bin\f[]
.IP \[bu] 2
-\f[C]install\-bin\-man\f[]
-.IP \[bu] 2
\f[C]install\-curl\f[]
.IP \[bu] 2
\f[C]install\-ex\f[]
@@ -63,13 +61,15 @@ their dependencies:
.IP \[bu] 2
\f[C]install\-login\-shell\f[]
.IP \[bu] 2
+\f[C]install\-man\f[]
+.IP \[bu] 2
\f[C]install\-readline\f[]
.IP \[bu] 2
\f[C]install\-vim\f[]
.PP
-The \f[C]install\-login\-shell\f[] looks at your \f[C]SHELL\f[]
-environment variable and tries to figure out which shell's configuration
-files to install, falling back on \f[C]install\-sh\f[].
+The \f[C]install\-login\-shell\f[] target looks at your \f[C]SHELL\f[]
+environment variable, and tries to figure out which shell's
+configuration files to install, falling back on \f[C]install\-sh\f[].
.PP
The remaining files can be installed with the other \f[C]install\-*\f[]
targets.
@@ -77,8 +77,8 @@ Try \f[C]awk\ \-f\ bin/mftl.awk\ Makefile\f[] in the project's root
directory to see a list.
.SS Configuration
.PP
-To save a set of \f[C]make\f[] targets useful for a specific user or
-host, you can save them in a newline\-separated file
+To keep a set of \f[C]make\f[] targets useful for a specific user or
+host, you can list them in a newline\-separated file
\f[C]~/.local/share/dotfiles.conf\f[], and install using that with the
special \f[C]install\-conf\f[] target.
This can include variable settings, too:
@@ -101,7 +101,7 @@ Bourne\-style POSIX shells, sharing a \f[C]\&.profile\f[], an
\f[C]ENV\f[] file, and some helper functions:
.RS 2
.IP \[bu] 2
-GNU Bash (https://www.gnu.org/software/bash/) (3.0 or higher)
+GNU Bash (https://www.gnu.org/software/bash/) (v3.0 or newer)
.IP \[bu] 2
Korn shell (http://www.kornshell.com/) (\f[C]ksh93\f[], \f[C]pdksh\f[],
\f[C]mksh\f[])
@@ -109,98 +109,100 @@ Korn shell (http://www.kornshell.com/) (\f[C]ksh93\f[], \f[C]pdksh\f[],
Z shell (https://www.zsh.org/)
.RE
.IP \[bu] 2
-Abook (http://abook.sourceforge.net/) \[en] curses address book program
+Abook (http://abook.sourceforge.net/)\[en]curses address book program
.IP \[bu] 2
-cURL (https://curl.haxx.se/) \[en] Command\-line tool for transferring
+cURL (https://curl.haxx.se/)\[en]Command\-line tool for transferring
data with URL syntax
.IP \[bu] 2
-Dillo (https://www.dillo.org/) \[en] A lightweight web browser
+Dillo (https://www.dillo.org/)\[en]A lightweight web browser
.IP \[bu] 2
-Dunst (https://dunst-project.org/) \[en] A lightweight X11 notification
+Dunst (https://dunst-project.org/)\[en]A lightweight X11 notification
daemon that works with \f[C]libnotify\f[]
.IP \[bu] 2
-\f[C]finger(1)\f[] \[en] User information lookup program
+\f[C]finger(1)\f[]\[en]User information lookup program
.IP \[bu] 2
-Git (https://git-scm.com/) \[en] Distributed version control system
+Git (https://git-scm.com/)\[en]Distributed version control system
.IP \[bu] 2
-GNU Emacs (https://www.gnu.org/software/emacs/) \[en] Extensible text
+GNU Emacs (https://www.gnu.org/software/emacs/)\[en]Extensible text
editor
.IP \[bu] 2
-GnuPG (https://www.gnupg.org/) \[en] GNU Privacy Guard, for private
+GnuPG (https://www.gnupg.org/)\[en]GNU Privacy Guard, for private
communication and file encryption
.IP \[bu] 2
-GTK+ (https://www.gtk.org/) \[en] GIMP Toolkit, for graphical user
+GTK+ (https://www.gtk.org/)\[en]GIMP Toolkit, for graphical user
interface elements
.IP \[bu] 2
-i3 (https://i3wm.org/) \[en] Tiling window manager
+i3 (https://i3wm.org/)\[en]Tiling window manager
.IP \[bu] 2
-less (https://www.gnu.org/software/less/) \[en] Terminal pager
+less (https://www.gnu.org/software/less/)\[en]Terminal pager
.IP \[bu] 2
-mpv (https://mpv.io/) \[en] Media player
+mpv (https://mpv.io/)\[en]Media player
.IP \[bu] 2
-Mutt (http://www.mutt.org/) \[en] Terminal mail user agent
+Mutt (http://www.mutt.org/)\[en]Terminal mail user agent
.IP \[bu] 2
-\f[C]mysql(1)\f[] (https://linux.die.net/man/1/mysql) \[en]
-Command\-line MySQL client
+\f[C]mysql(1)\f[] (https://linux.die.net/man/1/mysql)\[en]Command\-line
+MySQL client
.IP \[bu] 2
-Ncmpcpp (https://rybczak.net/ncmpcpp/) \[en] ncurses music player client
+Ncmpcpp (https://rybczak.net/ncmpcpp/)\[en]ncurses music player client
.IP \[bu] 2
-Newsboat (https://newsboat.org/) \[en] Terminal RSS/Atom feed reader
+Newsboat (https://newsboat.org/)\[en]Terminal RSS/Atom feed reader
.IP \[bu] 2
-\f[C]psql(1)\f[] (https://linux.die.net/man/1/psql) \[en] Command\-line
+\f[C]psql(1)\f[] (https://linux.die.net/man/1/psql)\[en]Command\-line
PostgreSQL client
.IP \[bu] 2
-Perl::Critic (http://perlcritic.com/) \[en] static source code analysis
+Perl::Critic (http://perlcritic.com/)\[en]static source code analysis
engine for Perl
.IP \[bu] 2
-Perl::Tidy (http://perltidy.sourceforge.net/) \[en] Perl source code
-reformatter
+Perl::Tidy (http://perltidy.sourceforge.net/)\[en]reformats Perl source
+code
.IP \[bu] 2
-Readline (https://tiswww.case.edu/php/chet/readline/rltop.html) \[en]
-GNU library for user input used by Bash, MySQL, and others
+Readline (https://tiswww.case.edu/php/chet/readline/rltop.html)\[en]GNU
+library for user input used by Bash, MySQL, and others
.IP \[bu] 2
-rxvt\-unicode (http://software.schmorp.de/pkg/rxvt-unicode.html) \[en]
-Fork of the rxvt terminal emulator with Unicode support
+rxvt\-unicode (http://software.schmorp.de/pkg/rxvt-unicode.html)\[en]Fork
+of the rxvt terminal emulator with Unicode support
.IP \[bu] 2
-Subversion (https://subversion.apache.org/) \[en] Apache Subversion, a
+Subversion (https://subversion.apache.org/)\[en]Apache Subversion, a
version control system
.IP \[bu] 2
-tidy (http://www.html-tidy.org/) \[en] HTML/XHTML linter and tidier
+tidy (http://www.html-tidy.org/)\[en]HTML/XHTML linter and tidier
.IP \[bu] 2
-tmux (https://tmux.github.io/) \[en] Terminal multiplexer similar to GNU
+tmux (https://tmux.github.io/)\[en]Terminal multiplexer similar to GNU
Screen
.IP \[bu] 2
-Vim (https://www.vim.org/) \[en] Vi IMproved, a text editor
+Vim (https://www.vim.org/)\[en]Vi IMproved, a text editor
.IP \[bu] 2
-X11 (https://www.x.org/wiki/) \[en] Windowing system with network
+X11 (https://www.x.org/wiki/)\[en]Windowing system with network
transparency for Unix
.PP
-The configurations for shells, Mutt, tmux, and Vim are the most
-expansive, and most likely to be of interest.
-The i3 configuration is mostly changed to make window switching behave
-like Vim windows and tmux panes do, and there's a fair few resources
-defined for rxvt\-unicode.
+The configurations for shells, Mutt, tmux, and Vim are the most likely
+to be of interest.
+The i3 configuration is limited mainly to changing window switching key
+bindings to match Vim's.
+There are a fair few resources defined for rxvt\-unicode.
.SS Shell
.PP
-My \f[C]\&.profile\f[] and other files in \f[C]sh\f[] are written in
-POSIX shell script, so they should work in most \f[C]sh(1)\f[]
-implementations.
-Individual scripts called by \f[C]\&.profile\f[] are saved in
-\f[C]\&.profile.d\f[] and iterated on login for ease of management.
+On GNU/Linux, I use Bash; on *BSD, I use some variant of Korn Shell,
+preferably \f[C]ksh93\f[] if it's available.
+.SS POSIX core
+.PP
+My \f[C]~/.profile\f[] and other files in \f[C]sh\f[] are written in
+POSIX shell script, so they \f[I]should\f[] work in most
+POSIX\-conforming \f[C]sh(1)\f[] implementations.
+Please email me if you find a case where they don't!
+.PP
+Further shell snippets to run on login are sourced from
+\f[C]~/.profile.d\f[] by \f[C]~/.profile\f[].
Most of these boil down to exporting variables appropriate to the system
and the software it has available.
.PP
-Configuration that should be sourced for all POSIX\-fearing interactive
-shells is kept in \f[C]~/.shrc\f[], with subscripts read from
-\f[C]~/.shrc.d\f[].
-There's a shim in \f[C]~/.shinit\f[] to act as \f[C]ENV\f[].
-I make an effort to target POSIX for my functions and scripts where I
-can so that the same files can be loaded for all shells.
+Configuration that should be sourced for all conforming
+\f[I]interactive\f[] shells is kept in \f[C]~/.shrc\f[], with subscripts
+read from \f[C]~/.shrc.d\f[].
+There's a \f[C]~/.shinit\f[] shim to act as \f[C]ENV\f[].
+.SS GNU Bash
.PP
-On GNU/Linux I use Bash, on BSD I use some variant of Korn Shell,
-preferably \f[C]ksh93\f[] if it's available.
-.PP
-My Bash is written to work with any version 3.0 or
+My Bash scripts are written to work with GNU Bash v3.0 or
newer (https://wiki.bash-hackers.org/scripting/bashchanges).
This is why I use older syntax for certain things such as appending
items to arrays:
@@ -211,8 +213,8 @@ array[${#array[\@]}]=$item
\f[]
.fi
.PP
-Compare this to the much nicer syntax available since 3.1\-alpha1, which
-actually works for arrays with sparse indices, unlike the above syntax:
+This doesn't work for arrays with sparse indices; compare this to the
+much nicer syntax available since 3.1\-alpha1, which does:
.IP
.nf
\f[C]
@@ -220,10 +222,10 @@ array+=("$item")
\f[]
.fi
.PP
-Where I do use features that are only available in versions of Bash
-newer than 3.0, such as newer \f[C]shopt\f[] options or
-\f[C]PROMPT_DIRTRIM\f[], they are only run after testing
-\f[C]BASH_VERSINFO\f[] appropriately.
+I do use some features that are only available in versions after v3.0,
+such as newer \f[C]shopt\f[] options like \f[C]dirspell\f[], or
+variables like \f[C]PROMPT_DIRTRIM\f[].
+These are set only after testing \f[C]BASH_VERSINFO\f[] appropriately.
.SS Prompt
.PP
A terminal session with my prompt looks something like this:
@@ -248,12 +250,15 @@ The hostname is elided if not connected via SSH.
The working directory with tilde abbreviation for \f[C]$HOME\f[] is
always shown.
The rest of the prompt expands based on context to include these
-elements in this order:
+elements, in this order:
.IP \[bu] 2
-Whether in a Git repository if applicable, and punctuation to show
-repository status including reference to upstreams at a glance.
-Subversion support can also be enabled (I need it at work), in which
-case a \f[C]git:\f[] or \f[C]svn:\f[] prefix is added appropriately.
+Whether in a Git repository if applicable,
+.IP \[bu] 2
+The current version control branch, tag, or commit/revision if
+applicable, and punctuation to show repository status including
+reference to upstreams at a glance.
+Subversion support can also be enabled, in which case a \f[C]git:\f[] or
+\f[C]svn:\f[] prefix is added appropriately for disambiguation.
.IP \[bu] 2
The number of running background jobs, if non\-zero.
.IP \[bu] 2
@@ -262,8 +267,8 @@ The exit status of the last command, if non\-zero.
You can set \f[C]PROMPT_COLOR\f[], \f[C]PROMPT_PREFIX\f[], and
\f[C]PROMPT_SUFFIX\f[] too, which all do about what you'd expect.
.PP
-If you start up Bash, Korn shell, or Z shell, and it detects that it's
-not your login shell, the prompt will display an appropriate prefix.
+If you start up GNU Bash, Korn shell, or Z shell, and that doesn't match
+your login shell, the prompt should display an appropriate prefix.
.PP
This is all managed within the \f[C]prompt\f[] function.
There's some mildly hacky logic on \f[C]tput\f[] codes included such
@@ -381,7 +386,7 @@ shell).
\f[C]pushd\f[] builtin (Bash).
.IP \[bu] 2
\f[C]vared()\f[] allows interactively editing a variable with Readline,
-emulating a Zsh function I like by the same name (Bash).
+emulating a Z shell function I like by the same name (Bash).
.IP \[bu] 2
\f[C]ver()\f[] prints the current shell's version information (Bash,
Korn Shell, Z shell).
@@ -434,8 +439,8 @@ The files started as a joke (\f[C]exec\ bash\f[]).
\f[C]zsh\f[] shells default to having a prompt colored cyan.
.SS Mutt
.PP
-My mail is kept in individual Maildirs under \f[C]~/mail\f[], with the
-system mail spool in e.g.
+My mail is kept in individual Maildir\-format directories under
+\f[C]~/mail\f[], with the system mail spool in e.g.
\f[C]/var/mail/tejr\f[] being where most unfiltered mail is sent.
I use Getmail (http://pyropus.ca/software/getmail/),
maildrop (https://www.courier-mta.org/maildrop/), and
@@ -467,8 +472,8 @@ If you're missing functionality, try changing \f[C]perl\-ext\-common\f[]
to \f[C]default\f[].
.SS tmux
.PP
-These are just generally vi\-friendly settings, not much out of the
-ordinary.
+These are just generally vi\-friendly settings, and there isn't much out
+of the ordinary.
Note that the configuration presently uses a hard\-coded 256\-color
color scheme, and uses non\-login shells, with an attempt to control the
environment to stop shells thinking they have access to an X display.
@@ -482,9 +487,20 @@ binds the same key combination to detach.
.PP
The majority of the Vim configuration is just setting options, with a
fair few mappings and remappings, both global and buffer\-local.
-I try not to deviate too much from the Vim defaults behavior in terms of
-interactive behavior and keybindings.
It's extensively commented.
+.SS XDG Basedirs
+.PP
+The XDG Base Directory
+Specification (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)'s
+environment variables are checked on startup, and appropriate
+directories are added to the start and end of
+\f[C]\[aq]runtimepath\[aq]\f[].
+I use these separate directories for machine\-local configuration,
+usually in \f[C]~/.config/vim\f[], while all the files that this suite
+installs land in \f[C]~/.vim\f[].
+Backups, swap files, persistent undo data, saved views, and the
+\f[C]viminfo\f[] file all live under \f[C]XDG_CACHE_HOME\f[], normally
+\f[C]~/.cache/vim\f[].
.SS Filetypes
.PP
I define my own \f[C]filetype.vim\f[] and \f[C]scripts.vim\f[], so that
@@ -495,13 +511,14 @@ you can extend them with your favorite filetypes in custom
.SS Plugins
.PP
If the logic for doing something involves more than a few lines or any
-structures like functions, I like to implement it as a plugin in
-\f[C]~/.vim/plugin\f[] and/or \f[C]~/.vim/autoload\f[], with
-documentation for each in \f[C]~/.vim/doc\f[].
+structures like functions that can be decoupled from \f[C]$MYVIMRC\f[],
+I like to implement it as a plugin in \f[C]~/.vim/plugin\f[] and/or
+\f[C]~/.vim/autoload\f[], with documentation for each in
+\f[C]~/.vim/doc\f[].
.PP
They eventually get either discarded if I stop using them, or spun off
-into their own repositories if I don't, and added to this repository as
-submodules under \f[C]vim/bundle\f[] instead.
+into their own repositories and added to this repository as submodules
+under \f[C]vim/bundle\f[] if I don't.
Some of them I upload to
vim.org (https://www.vim.org/account/profile.php?user_id=73687).
.SS Filetype plugins
@@ -509,7 +526,7 @@ vim.org (https://www.vim.org/account/profile.php?user_id=73687).
I apply some replacement or supplementary configuration specific to file
types I often edit in \f[C]~/.vim\f[] and \f[C]~/.vim/after\f[], in the
\f[C]ftplugin\f[], \f[C]indent\f[], and \f[C]syntax\f[] subdirectories.
-Some of these filetype plugins or extensions will also eventually be
+Some of these filetype plugins or extensions may also eventually be
removed to be separately distributed, and installed via submodules
instead.
.SS Compilers
@@ -524,17 +541,18 @@ it good?\[rq]\[en]with separate local leader maps; for example, for
.SS No Neovim support
.PP
The configuration doesn't explicitly support Neovim, although most of it
-will probably work.
+will probably work; you would probably just comment out the settings for
+a few of the removed options.
.SS Scripts
.PP
Where practical, I make short scripts into POSIX (but not Bourne)
\f[C]sh(1)\f[], \f[C]awk(1)\f[], or \f[C]sed(1)\f[] scripts in
\f[C]~/.local/bin\f[].
I try to use shell functions only when I actually need to, which tends
-to be when I need to tinker with the namespace of the user's current
-shell.
+to be when I need to change the state of the user's current shell, or to
+limit a change in behavior only to interactive shells.
.PP
-Installed by the \f[C]install\-bin\f[] target:
+These scripts are installed by the \f[C]install\-bin\f[] target:
.IP \[bu] 2
Three SSH\-related scripts:
.RS 2
@@ -974,14 +992,14 @@ occurrence of \[lq]s\[rq] in the text on its standard input.
.SS Manuals
.PP
The \f[C]install\-bin\f[] and \f[C]install\-games\f[] targets install
-manuals for each script they install.
-If you want to use the manuals, you may need to add
+manuals for each script.
+If you want to read the manuals, you may need to add
\f[C]~/.local/share/man\f[] to your \f[C]~/.manpath\f[] or
\f[C]/etc/manpath\f[] configuration, depending on your system.
.SS Testing
.PP
You can check that both sets of shell scripts are syntactically correct
-with \f[C]make\ check\-bash\f[], \f[C]make\ check\-sh\f[], or
+with \f[C]make\ check\-bash\f[] or \f[C]make\ check\-sh\f[], or
\f[C]make\ check\f[] for everything including the scripts in
\f[C]bin\f[] and \f[C]games\f[].
There's no proper test suite for the actual functionality (yet).