From eb9b7b65301e8ec9f628930a1738b0b03a6f0715 Mon Sep 17 00:00:00 2001 From: Tom Ryder Date: Sun, 3 May 2020 22:37:45 +1200 Subject: Many README.md improvements in phrasing or grammar --- README.md | 149 ++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 83 insertions(+), 66 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index dab9534e..c2b7d3f3 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,7 +75,7 @@ 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 @@ -102,8 +102,7 @@ Configuration is included for: client * [Perl::Critic](http://perlcritic.com/) -- static source code analysis engine for Perl -* [Perl::Tidy](http://perltidy.sourceforge.net/) -- Perl source code - reformatter +* [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 @@ -116,41 +115,46 @@ Configuration is included for: * [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 +174,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 +254,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 +299,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 +327,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 +340,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 +364,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 +392,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 +626,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). -- cgit v1.2.3