diff options
author | Tom Ryder <tom@sanctum.geek.nz> | 2020-05-03 22:39:55 +1200 |
---|---|---|
committer | Tom Ryder <tom@sanctum.geek.nz> | 2020-05-03 22:39:55 +1200 |
commit | bac8ed9829a6a767091662fab056f460d187f246 (patch) | |
tree | 028fb5342fa8a4a8f9eb6388c927a46bf4b978ed | |
parent | Merge branch 'release/v8.26.0' (diff) | |
parent | Update dotfiles(7) manual page (diff) | |
download | dotfiles-8.27.0.tar.gz (sig) dotfiles-8.27.0.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-- | Makefile | 2 | ||||
-rw-r--r-- | README.md | 206 | ||||
-rw-r--r-- | VERSION | 4 | ||||
-rw-r--r-- | man/man7/dotfiles.7df | 216 |
4 files changed, 231 insertions, 197 deletions
@@ -350,8 +350,8 @@ install: install-bin \ install-git \ install-gnupg \ install-less \ - install-man \ install-login-shell \ + install-man \ install-readline \ install-vim @@ -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). @@ -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). |