aboutsummaryrefslogtreecommitdiff
path: root/man/man7/dotfiles.7df
diff options
context:
space:
mode:
authorTom Ryder <tom@sanctum.geek.nz>2016-08-26 12:13:03 +1200
committerTom Ryder <tom@sanctum.geek.nz>2016-08-26 12:50:25 +1200
commitcde1926a3c65830bceed5e8e76cd94e81b19386c (patch)
tree5abe782d2c9567f3d7c3affa8fc077fb3d5d5e5c /man/man7/dotfiles.7df
parentAdd notifications to dmp(1) (diff)
downloaddotfiles-cde1926a3c65830bceed5e8e76cd94e81b19386c.tar.gz
dotfiles-cde1926a3c65830bceed5e8e76cd94e81b19386c.zip
Put dotfiles manuals into their own section
This probably contains a few mistakes
Diffstat (limited to 'man/man7/dotfiles.7df')
-rw-r--r--man/man7/dotfiles.7df730
1 files changed, 730 insertions, 0 deletions
diff --git a/man/man7/dotfiles.7df b/man/man7/dotfiles.7df
new file mode 100644
index 00000000..cf8e9389
--- /dev/null
+++ b/man/man7/dotfiles.7df
@@ -0,0 +1,730 @@
+.TH "DOTFILES(7df)" "" "June 2016" "" ""
+.SH Dotfiles (Tom Ryder)
+.PP
+This is my personal repository of configuration files and scripts for
+\f[C]$HOME\f[], including most of the settings that migrate well between
+machines.
+.SS Installation
+.IP
+.nf
+\f[C]
+$\ git\ clone\ https://sanctum.geek.nz/code/dotfiles.git\ ~/.dotfiles
+$\ cd\ ~/.dotfiles
+$\ git\ submodule\ init
+$\ git\ submodule\ update
+$\ make
+$\ make\ \-n\ install
+$\ make\ install
+\f[]
+.fi
+.PP
+For the default \f[C]all\f[] target, you'll need \f[C]bash(1)\f[],
+\f[C]git(1)\f[], \f[C]install(1)\f[], \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:
+.IP
+.nf
+\f[C]
+$\ tmpdir=$(mktemp\ \-d)
+$\ make\ install\ HOME="$tmpdir"
+$\ env\ \-i\ HOME="$tmpdir"\ TERM="$TERM"\ bash\ \-l
+\f[]
+.fi
+.PP
+The default target will install the core terminal\-only files: cURL,
+Git, GnuPG, Vim, shell scripts and functions, and shell and terminal
+setup files.
+The remaining dotfiles can be installed with the other targets.
+Take a look at the \f[C]Makefile\f[] to see what's available.
+.SS Tools
+.PP
+Configuration is included for:
+.IP \[bu] 2
+Abook (http://abook.sourceforge.net/) \[en] curses address book program
+.IP \[bu] 2
+Bash (https://www.gnu.org/software/bash/) \[en] GNU Bourne\-Again Shell,
+including a \f[C]~/.profile\f[] configured to work with most
+Bourne\-compatible shells
+.IP \[bu] 2
+cURL (https://curl.haxx.se/) \[en] Command\-line tool for transferring
+data with URL syntax
+.IP \[bu] 2
+Dunst (http://knopwob.org/dunst/) \[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
+.IP \[bu] 2
+Git (https://git-scm.com/) \[en] Distributed version control system
+.IP \[bu] 2
+GnuPG (https://www.gnupg.org/) \[en] GNU Privacy Guard, for private
+communication and file encryption
+.IP \[bu] 2
+GTK+ (http://www.gtk.org/) \[en] GIMP Toolkit, for graphical user
+interface elements
+.IP \[bu] 2
+i3 (https://i3wm.org/) \[en] Tiling window manager
+.IP \[bu] 2
+less (https://www.gnu.org/software/less/) \[en] Terminal pager
+.IP \[bu] 2
+Mutt (http://www.mutt.org/) \[en] Terminal mail user agent
+.IP \[bu] 2
+\f[C]mysql(1)\f[] (http://linux.die.net/man/1/mysql) \[en] Command\-line
+MySQL client
+.IP \[bu] 2
+Ncmpcpp (https://rybczak.net/ncmpcpp/) \[en] ncurses music player client
+.IP \[bu] 2
+Newsbeuter (https://www.newsbeuter.org/) \[en] Terminal RSS/Atom feed
+reader
+.IP \[bu] 2
+\f[C]pdksh(1)\f[] (http://www.cs.mun.ca/~michael/pdksh/) \[en] public
+domain fork of the Korn shell
+.IP \[bu] 2
+\f[C]psql(1)\f[] (http://linux.die.net/man/1/psql) \[en] Command\-line
+PostgreSQL client
+.IP \[bu] 2
+Perl::Critic (http://perlcritic.com/) \[en] static source code analysis
+engine for Perl
+.IP \[bu] 2
+Perl::Tidy (http://perltidy.sourceforge.net/) \[en] Perl indenter and
+reformatter
+.IP \[bu] 2
+Readline (https://cnswww.cns.cwru.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
+.IP \[bu] 2
+Subversion (https://subversion.apache.org/) \[en] Apache Subversion, a
+version control system
+.IP \[bu] 2
+tmux (https://tmux.github.io/) \[en] Terminal multiplexer similar to GNU
+Screen
+.IP \[bu] 2
+Vim (http://www.vim.org/) \[en] Vi IMproved, a text editor
+.IP \[bu] 2
+Wyrd (https://packages.debian.org/sid/wyrd) \[en] a \f[C]curses\f[]
+calendar frontend for
+Remind (https://www.roaringpenguin.com/products/remind)
+.IP \[bu] 2
+X11 (https://www.x.org/wiki/) \[en] Windowing system with network
+transparency for Unix
+.IP \[bu] 2
+Zsh (https://www.zsh.org/) \[en] Bourne\-style shell designed for
+interactive use
+.PP
+The configurations for Bash, GnuPG, 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.
+Otherwise, the rest of the configuration isn't too distant from the
+defaults.
+.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.
+All of these boil down to exporting variables appropriate to the system
+and the software it has available.
+.PP
+I make an effort to target POSIX for my functions and scripts where I
+can, but Bash is my interactive shell of choice.
+.PP
+My \f[C]\&.bash_profile\f[] calls \f[C]\&.profile\f[], and then
+\f[C]\&.bashrc\f[], which only applies for interactive shells.
+Subscripts for \f[C]\&.bashrc\f[] are loaded from \f[C]\&.bashrc.d\f[].
+The contents of the \f[C]*.d\f[] directories changes depending on the
+host, so only specific scripts in it are versioned.
+.PP
+As I occasionally have work on very old internal systems, my Bash is
+written to work with any version 2.05a or
+newer (http://wiki.bash-hackers.org/scripting/bashchanges).
+This is why I use older syntax for certain things such as appending
+items to arrays:
+.IP
+.nf
+\f[C]
+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 indexes, unlike the above syntax:
+.IP
+.nf
+\f[C]
+array+=("$item")
+\f[]
+.fi
+.PP
+Where I do use features that are only available in versions of Bash
+newer than 2.05a, 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.
+.SS Prompt
+.PP
+When I use any other Bourne\-compatible shell, I'm generally happy to
+accept its defaults for interactive behavior.
+.PP
+A terminal session with my prompt looks something like this:
+.IP
+.nf
+\f[C]
+~$\ ssh\ remote
+tom\@remote:~$\ cd\ .dotfiles
+tom\@remote:~/.dotfiles(master+!)$\ git\ status
+\ M\ README.markdown
+M\ \ bash/bashrc.d/prompt.bash
+A\ \ init
+tom\@remote:~/.dotfiles(master+!)$\ foobar
+foobar:\ command\ not\ found
+tom\@remote:~/.dotfiles(master+!)<127>$\ sleep\ 5\ &
+[1]\ 28937
+tom\@remote:~/.dotfiles(master+!){1}$
+\f[]
+.fi
+.PP
+The username and hostname are skipped if not connected via SSH.
+The right side of the prompt expands based on context to include these
+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
+.IP \[bu] 2
+The number of running background jobs, if non\-zero
+.IP \[bu] 2
+The exit status of the last command, if non\-zero
+.PP
+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
+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
+that it should work correctly for most common terminals using both
+\f[C]termcap(5)\f[] and \f[C]terminfo(5)\f[], including *BSD systems.
+It's also designed to degrade gracefully for eight\-color and no\-color
+terminals.
+.SS Functions
+.PP
+If a function can be written in POSIX \f[C]sh\f[] without too much
+hackery, I put it in \f[C]sh/shrc.d\f[] to be loaded by any POSIX
+interactive shell.
+Those include:
+.IP \[bu] 2
+\f[C]bc()\f[] silences startup messages from GNU \f[C]bc(1)\f[].
+.IP \[bu] 2
+\f[C]bd()\f[] changes into a named ancestor of the current directory.
+.IP \[bu] 2
+\f[C]diff()\f[] forces the unified format for \f[C]diff(1)\f[].
+.IP \[bu] 2
+\f[C]ed()\f[] tries to get verbose error messages, a prompt, and a
+Readline environment for \f[C]ed(1)\f[].
+.IP \[bu] 2
+\f[C]env()\f[] sorts the output of \f[C]env(1)\f[] if it was invoked
+with no arguments, because the various shells have different ways of
+listing exported variables.
+.IP \[bu] 2
+\f[C]gdb()\f[] silences startup messages from \f[C]gdb(1)\f[].
+.IP \[bu] 2
+\f[C]gpg()\f[] quietens \f[C]gpg(1)\f[] down for most commands.
+.IP \[bu] 2
+\f[C]grep()\f[] tries to apply color and other options good for
+interactive use, depending on the capabilities of the system
+\f[C]grep(1)\f[].
+.IP \[bu] 2
+\f[C]hgrep()\f[] allows searching \f[C]$HISTFILE\f[].
+.IP \[bu] 2
+\f[C]keychain()\f[] keeps \f[C]$GPG_TTY\f[] up to date if a GnuPG agent
+is available.
+.IP \[bu] 2
+\f[C]lhn()\f[] gets the history number of the last command, if the POSIX
+\f[C]fc\f[] builtin is available.
+.IP \[bu] 2
+\f[C]ls()\f[] tries to apply color to \f[C]ls(1)\f[] for interactive use
+if available.
+.RS 2
+.IP \[bu] 2
+\f[C]la()\f[] runs \f[C]ls\ \-A\f[] if it can, or \f[C]ls\ \-a\f[]
+otherwise.
+.IP \[bu] 2
+\f[C]ll()\f[] runs \f[C]ls\ \-Al\f[] if it can, or \f[C]ls\ \-al\f[]
+otherwise.
+through your pager, using color if it can.
+.RE
+.IP \[bu] 2
+\f[C]mkcd()\f[] creates a directory and changes into it.
+.IP \[bu] 2
+\f[C]mysql()\f[] allows shortcuts to MySQL configuration files stored in
+\f[C]~/.mysql\f[].
+.IP \[bu] 2
+\f[C]path()\f[] manages the contents of \f[C]PATH\f[] conveniently.
+.IP \[bu] 2
+\f[C]pd()\f[] changes to the argument's parent directory.
+.IP \[bu] 2
+\f[C]pwgen()\f[] generates just one decent password with
+\f[C]pwgen(1)\f[].
+.IP \[bu] 2
+\f[C]rcsdiff()\f[] forces a unified format for \f[C]rcsdiff(1)\f[].
+.IP \[bu] 2
+\f[C]rd()\f[] replaces the first instance of its first argument with its
+second argument in \f[C]$PWD\f[], emulating a feature of the Zsh
+\f[C]cd\f[] builtin that I like.
+.IP \[bu] 2
+\f[C]scp()\f[] tries to detect forgotten hostnames in \f[C]scp(1)\f[]
+command calls.
+.IP \[bu] 2
+\f[C]scr()\f[] creates a temporary directory and changes into it.
+.IP \[bu] 2
+\f[C]sd()\f[] changes into a sibling of the current directory.
+.IP \[bu] 2
+\f[C]sudo()\f[] forces \f[C]\-H\f[] for \f[C]sudo(8)\f[] calls so that
+\f[C]$HOME\f[] is never preserved; I hate having \f[C]root\f[]\-owned
+files in my home directory.
+.IP \[bu] 2
+\f[C]tmux()\f[] changes the default command for \f[C]tmux(1)\f[] to
+\f[C]attach\-session\ \-d\f[] if a session exists, or creates a new
+session if one doesn't.
+.IP \[bu] 2
+\f[C]ud()\f[] changes into an indexed ancestor of a directory.
+.IP \[bu] 2
+\f[C]vim()\f[] defines three functions to always use \f[C]vim(1)\f[] as
+my \f[C]ex(1)\f[], \f[C]vi(1)\f[] and \f[C]view(1)\f[] implementation if
+it's available.
+.IP \[bu] 2
+\f[C]vr()\f[] tries to change to the root directory of a source control
+repository.
+.PP
+There are a few other little tricks defined for other shells, mostly in
+\f[C]bash/bashrc.d\f[]:
+.IP \[bu] 2
+\f[C]keep()\f[] stores ad\-hoc shell functions and variables.
+.IP \[bu] 2
+\f[C]prompt()\f[] sets up my interactive prompt.
+.IP \[bu] 2
+\f[C]pushd()\f[] adds a default destination of \f[C]$HOME\f[] to the
+\f[C]pushd\f[] builtin.
+.IP \[bu] 2
+\f[C]vared()\f[] allows interactively editing a variable with Readline,
+emulating a Zsh function I like by the same name.
+.SS Completion
+.PP
+I find the \f[C]bash\-completion\f[] package a bit too heavy for my
+tastes, and turn it off using a stub file installed in
+\f[C]\&.config/bash_completion\f[].
+The majority of the time I just want to complete paths anyway, and this
+makes for a quicker startup without a lot of junk functions in my Bash
+namespace.
+.PP
+I do make some exceptions with completions defined in
+\f[C]\&.bash_completion.d\f[] files for things I really do get tired of
+typing repeatedly:
+.IP \[bu] 2
+Builtins, commands, help topics, shell options, and variables
+.IP \[bu] 2
+\f[C]ftp(1)\f[] hostnames from \f[C]~/.netrc\f[]
+.IP \[bu] 2
+\f[C]git(1)\f[] branch names
+.IP \[bu] 2
+\f[C]gpg(1)\f[] long options
+.IP \[bu] 2
+\f[C]make(1)\f[] targets read from a \f[C]Makefile\f[]
+.IP \[bu] 2
+\f[C]man(1)\f[] page titles
+.IP \[bu] 2
+\f[C]mysql(1)\f[] databases from \f[C]~/.mysql/*.cnf\f[]
+.IP \[bu] 2
+\f[C]pass(1)\f[] entries
+.IP \[bu] 2
+\f[C]ssh(1)\f[] hostnames from \f[C]~/.ssh/config\f[]
+.PP
+I also add completions for my own scripts and functions where useful.
+The completions are dynamically loaded if Bash is version 4.0 or
+greater.
+Otherwise, they're all loaded on startup.
+.SS pdksh
+.PP
+The pdksh configuration files and functions are not nearly as featureful
+as the Bash ones.
+They're tested on OpenBSD and FreeBSD pdksh implementations, but the
+former is the primary system for which I'm maintaining them, and there
+are some feature differences.
+.SS Zsh
+.PP
+These are experimental; I do not like Zsh much at the moment.
+The files started as a joke (\f[C]exec\ bash\f[]).
+.SS GnuPG
+.PP
+The configuration for GnuPG is intended to follow RiseUp's OpenPGP best
+practices (https://riseup.net/en/security/message-security/openpgp/best-practices).
+The configuration file is rebuilt using \f[C]m4(1)\f[] and
+\f[C]make(1)\f[] because it requires hard\-coding a path to the SKS
+keyserver certificate authority, and neither tilde nor \f[C]$HOME\f[]
+expansion works for this.
+.SS Mutt
+.PP
+My mail is kept in individual Maildirs under \f[C]~/Mail\f[], with
+\f[C]inbox\f[] being where most unfiltered mail is sent.
+I use Getmail (http://pyropus.ca/software/getmail/),
+maildrop (http://www.courier-mta.org/maildrop/), and
+MSMTP (http://msmtp.sourceforge.net/); the configurations for these are
+not included here.
+I sign whenever I have some indication that the recipient might be using
+a PGP implementation, and I encrypt whenever I have a public key
+available for them.
+The GnuPG interfacing is done with
+GPGme (https://www.gnupg.org/related_software/gpgme/), rather than
+defining commands for each crypto operation.
+I wrote an article about this
+setup (https://sanctum.geek.nz/arabesque/linux-crypto-email/) if it
+sounds appealing.
+.PP
+You'll need Abook (http://abook.sourceforge.net/) installed if you want
+to use the \f[C]query_command\f[] I have defined, and
+msmtp (http://msmtp.sourceforge.net/) for the \f[C]sendmail\f[] command.
+.SS rxvt\-unicode
+.PP
+I've butchered the URxvt Perl extensions
+\f[C]selection\-to\-clipboard\f[] and \f[C]selection\f[] into a single
+\f[C]select\f[] extension in \f[C]~/.urxvt/ext\f[], which is the only
+extension I define in \f[C]~/.Xresources\f[].
+.PP
+The included \f[C]\&.Xresources\f[] file assumes that \f[C]urxvt\f[] can
+use 256 colors and Perl extensions.
+If you're missing functionality, try changing \f[C]perl\-ext\-common\f[]
+to \f[C]default\f[].
+.PP
+My choice of font is Ubuntu Mono (http://font.ubuntu.com/), but the file
+should allow falling back to the more common Deja Vu Sans
+Mono (http://dejavu-fonts.org/wiki/Main_Page).
+I've found Terminus (http://terminus-font.sourceforge.net/) works well
+too, but bitmap fonts are not really my cup of tea.
+The Lohit Kannada font bit is purely to make ಠ_ಠ work correctly.
+( ͡° ͜ʖ ͡°) seems to work out of the box.
+.SS tmux
+.PP
+These are just generally vi\-friendly settings, not much out of the
+ordinary.
+Note that the configuration presently uses a hard\-coded 256\-color
+colorscheme, and uses non\-login shells, with an attempt to control the
+environment to stop shells thinking they have access to an X display.
+.PP
+The configuration file is created with \f[C]m4(1)\f[] to allow
+specifying a color theme.
+This is just because I use a different color for my work session.
+The default is a dark grey.
+.PP
+The configuration for Bash includes a \f[C]tmux\f[] function designed to
+make \f[C]attach\f[] into the default command if no arguments are given
+and sessions do already exist.
+The default command is normally \f[C]new\-session\f[].
+.SS Vim
+.PP
+The majority of the \f[C]\&.vimrc\f[] file is just setting options, with
+a few mappings.
+I try not to deviate too much from the Vim defaults behaviour in terms
+of interactive behavior and keybindings.
+.PP
+The configuration is extensively commented, mostly because I was reading
+through it one day and realised I'd forgotten what half of it did.
+Plugins are loaded using \@tpope's
+pathogen.vim (https://github.com/tpope/vim-pathogen).
+.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[].
+A few of them still have Bashisms for various reasons.
+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.
+.PP
+Installed by the \f[C]install\-bin\f[] target:
+.IP \[bu] 2
+Three SSH\-related scripts:
+.RS 2
+.IP \[bu] 2
+\f[C]sls(1df)\f[] prints hostnames read from a \f[C]ssh_config(5)\f[]
+file.
+It uses \f[C]slsf(1df)\f[] to read each one.
+.IP \[bu] 2
+\f[C]sra(1df)\f[] runs a command on multiple hosts read from
+\f[C]sls(1df)\f[] and prints output.
+.IP \[bu] 2
+\f[C]sta(1df)\f[] runs a command on multiple hosts read from
+\f[C]sls(1df)\f[] and prints the hostname if the command returns zero.
+.RE
+.IP \[bu] 2
+Five URL\-related shortcut scripts:
+.RS 2
+.IP \[bu] 2
+\f[C]hurl(1df)\f[] extracts values of \f[C]href\f[] attributes of
+\f[C]<a>\f[] tags, sorts them uniquely, and writes them to
+\f[C]stdout\f[]; it requires pup (https://github.com/ericchiang/pup).
+.IP \[bu] 2
+\f[C]murl(1df)\f[] converts Markdown documents to HTML with
+\f[C]pandoc(1)\f[] and runs the output through \f[C]hurl(1df)\f[].
+.IP \[bu] 2
+\f[C]urlc(1df)\f[] accepts a list of URLs on \f[C]stdin\f[] and writes
+error messages to \f[C]stderr\f[] if any of the URLs are broken,
+redirecting, or are insecure and have working secure versions; requires
+\f[C]curl(1)\f[].
+.IP \[bu] 2
+\f[C]urlh(1df)\f[] prints the values for a given HTTP header from a HEAD
+response.
+.IP \[bu] 2
+\f[C]urlmt(1df)\f[] prints the MIME type from the \f[C]Content\-Type\f[]
+header as retrieved by \f[C]urlh(1df)\f[].
+.RE
+.IP \[bu] 2
+Three RFC\-related shortcut scripts:
+.RS 2
+.IP \[bu] 2
+\f[C]rfcf(1df)\f[] fetches ASCII RFCs from the IETF website.
+.IP \[bu] 2
+\f[C]rfct(1df)\f[] formats ASCII RFCs.
+.IP \[bu] 2
+\f[C]rfcr(1df)\f[] does both, displaying in a pager if appropriate, like
+a \f[C]man(1)\f[] reader for RFCs.
+.RE
+.IP \[bu] 2
+Five toy random\-number scripts (not for sensitive/dead\-serious use):
+.RS 2
+.IP \[bu] 2
+\f[C]rndi(1df)\f[] gets a random integer within two bounds.
+.IP \[bu] 2
+\f[C]rnds(1df)\f[] attempts to get an optional random seed for
+\f[C]rndi(1df)\f[].
+.IP \[bu] 2
+\f[C]rnda(1df)\f[] uses \f[C]rndi(1df)\f[] to choose a random argument.
+.IP \[bu] 2
+\f[C]rndf(1df)\f[] uses \f[C]rnda(1df)\f[] to choose a random file from
+a directory.
+.IP \[bu] 2
+\f[C]rndl(1df)\f[] uses \f[C]rndi(1df)\f[] to choose a random line from
+files.
+.RE
+.IP \[bu] 2
+Four file formatting scripts:
+.RS 2
+.IP \[bu] 2
+\f[C]d2u(1df)\f[] converts DOS line endings in files to UNIX ones.
+.IP \[bu] 2
+\f[C]u2d(1df)\f[] converts UNIX line endings in files to DOS ones.
+.IP \[bu] 2
+\f[C]stbl(1df)\f[] strips a trailing blank line from the files in its
+arguments.
+.IP \[bu] 2
+\f[C]stws(1df)\f[] strips trailing spaces from the ends of lines of the
+files in its arguments.
+.RE
+.IP \[bu] 2
+Five stream formatting scripts:
+.RS 2
+.IP \[bu] 2
+\f[C]sd2u(1df)\f[] converts DOS line endings in streams to UNIX ones.
+.IP \[bu] 2
+\f[C]su2d(1df)\f[] converts UNIX line endings in streams to DOS ones.
+.IP \[bu] 2
+\f[C]tl(1df)\f[] tags input lines with a prefix or suffix, basically a
+\f[C]sed(1)\f[] shortcut.
+.IP \[bu] 2
+\f[C]tlcs(1df)\f[] executes a command and uses \f[C]tl(1df)\f[] to tag
+stdout and stderr lines, and color them if you want.
+.IP \[bu] 2
+\f[C]unf(1df)\f[] joins lines with leading spaces to the previous line.
+Intended for unfolding HTTP headers, but it should work for most RFC 822
+formats.
+.RE
+.IP \[bu] 2
+\f[C]apf(1df)\f[] prepends arguments to a command with ones read from a
+file, intended as a framework for shell wrappers or functions.
+.IP \[bu] 2
+\f[C]ax(1df)\f[] evaluates an awk expression given on the command line;
+this is intended as a quick way to test how Awk would interpret a given
+expression.
+.IP \[bu] 2
+\f[C]bel(1df)\f[] prints a terminal bell character.
+.IP \[bu] 2
+\f[C]br(1df)\f[] launches \f[C]$BROWSER\f[], or a more suitable
+application for an URL if it knows of one.
+.IP \[bu] 2
+\f[C]ca(1df)\f[] prints a count of its given arguments.
+.IP \[bu] 2
+\f[C]cf(1df)\f[] prints a count of entries in a given directory.
+.IP \[bu] 2
+\f[C]clrd(1df)\f[] sets up a per\-line file read, clearing the screen
+first.
+.IP \[bu] 2
+\f[C]clwr(1df)\f[] sets up a per\-line file write, clearing the screen
+before each line
+.IP \[bu] 2
+\f[C]dmp(1df)\f[] copies a pass(1) entry selected by \f[C]dmenu(1)\f[]
+to the X CLIPBOARD.
+.IP \[bu] 2
+\f[C]dub(1df)\f[] lists the biggest entries in a directory.
+.IP \[bu] 2
+\f[C]edda(1df)\f[] provides a means to run \f[C]ed(1)\f[] over a set of
+files preserving any options, mostly useful for scripts.
+.IP \[bu] 2
+\f[C]eds(1df)\f[] edits executable script files in \f[C]EDSPATH\f[],
+defaulting to \f[C]~/.local/bin\f[], for personal scripting snippets.
+.IP \[bu] 2
+\f[C]fgscr(1df)\f[] finds Git repositories in a directory root and
+scrubs them with \f[C]gscr(1df)\f[].
+.IP \[bu] 2
+\f[C]fnl(1df)\f[] runs a command and saves its output and error into
+temporary files, printing their paths and line counts
+.IP \[bu] 2
+\f[C]gms(1df)\f[] runs a set of \f[C]getmailrc\f[] files; does much the
+same thing as the script \f[C]getmails\f[] in the \f[C]getmail\f[]
+suite, but runs the requests in parallel and does up to three silent
+retries using \f[C]try(1df)\f[].
+.IP \[bu] 2
+\f[C]grc(1df)\f[] quietly tests whether the given directory appears to
+be a Git repository with pending changes.
+.IP \[bu] 2
+\f[C]gscr(1df)\f[] scrubs Git repositories.
+.IP \[bu] 2
+\f[C]han(1df)\f[] provides a \f[C]keywordprg\f[] for Vim's Bash script
+filetype that will look for \f[C]help\f[] topics.
+You could use it from the shell too.
+.IP \[bu] 2
+\f[C]igex(1df)\f[] wraps around a command to allow you to ignore error
+conditions that don't actually worry you, exiting with 0 anyway.
+.IP \[bu] 2
+\f[C]isgr(1df)\f[] quietly tests whether the given directory appears to
+be a Git repository.
+.IP \[bu] 2
+\f[C]jfc(1df)\f[] adds and commits lazily to a Git repository.
+.IP \[bu] 2
+\f[C]jfcd(1df)\f[] watches a directory for changes and runs
+\f[C]jfc(1df)\f[] if it sees any.
+.IP \[bu] 2
+\f[C]maybe(1df)\f[] is like \f[C]true(1)\f[] or \f[C]false(1)\f[]; given
+a probability of success, it exits with success or failure.
+Good for quick tests.
+.IP \[bu] 2
+\f[C]mkcp(1df)\f[] creates a directory and copies preceding arguments
+into it.
+.IP \[bu] 2
+\f[C]mkmv(1df)\f[] creates a directory and moves preceding arguments
+into it.
+.IP \[bu] 2
+\f[C]motd(1df)\f[] shows the system MOTD.
+.IP \[bu] 2
+\f[C]pa(1df)\f[] prints its arguments, one per line.
+.IP \[bu] 2
+\f[C]paz(1df)\f[] print its arguments terminated by NULL chars.
+.IP \[bu] 2
+\f[C]pit(1df)\f[] runs its input through a pager if its standard output
+looks like a terminal.
+.IP \[bu] 2
+\f[C]plmu(1df)\f[] retrieves a list of installed modules from
+\f[C]plenv\f[] (https://github.com/tokuhirom/plenv), filters out any
+modules in \f[C]~/.plenv/non\-cpan\-modules\f[], and updates them all.
+.IP \[bu] 2
+\f[C]rmrej(1df)\f[] deletes rejected hunks from a failed
+\f[C]patch(1)\f[] run.
+.IP \[bu] 2
+\f[C]shb(1df)\f[] attempts to build shebang lines for scripts from
+\f[C]$PATH\f[].
+.IP \[bu] 2
+\f[C]spr(1df)\f[] posts its input to the sprunge.us pastebin.
+.IP \[bu] 2
+\f[C]sshi(1df)\f[] prints human\-readable SSH connection details.
+.IP \[bu] 2
+\f[C]stex(1df)\f[] strips extensions from filenames.
+.IP \[bu] 2
+\f[C]sue(8df)\f[] execs \f[C]sudoedit(8)\f[] as the owner of all the
+file arguments given, perhaps in cases where you may not necessarily
+have \f[C]root\f[] \f[C]sudo(8)\f[] privileges.
+.IP \[bu] 2
+\f[C]td(1df)\f[] manages a to\-do file for you with \f[C]$EDITOR\f[] and
+\f[C]git(1)\f[]; I used to use Taskwarrior, but found it too complex and
+buggy.
+.IP \[bu] 2
+\f[C]try(1df)\f[] repeats a command up to a given number of times until
+it succeeds, only printing error output if all three attempts failed.
+Good for tolerating blips or temporary failures in \f[C]cron(8)\f[]
+scripts.
+.PP
+There's some silly stuff in \f[C]install\-games\f[]:
+.IP \[bu] 2
+\f[C]aaf(6df)\f[] gets a random ASCII Art
+Farts (http://www.asciiartfarts.com/) comic.
+.IP \[bu] 2
+\f[C]acq(6df)\f[] allows you to interrogate AC, the interplanetary
+computer.
+.IP \[bu] 2
+\f[C]kvlt(6df)\f[] translates input to emulate a style of typing unique
+to black metal communities on the internet.
+.IP \[bu] 2
+\f[C]rndn(6df)\f[] implements an esoteric random number generation
+algorithm.
+.IP \[bu] 2
+\f[C]xyzzy(6df)\f[] teleports to a marked location on the filesystem.
+.IP \[bu] 2
+\f[C]zs(6df)\f[] prepends \[lq]z\[rq] case\-appropriately to every
+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.
+There's also an \f[C]install\-dotfiles\-man\f[] target that uses
+\f[C]pandoc(1)\f[] to reformat this document as a manual page for
+section 7 (\f[C]dotfiles(7)\f[]) if you want that.
+I haven't made that install by default, because \f[C]pandoc(1)\f[] is a
+bit heavy.
+.PP
+If you want to use the manuals, you may need to add
+\f[C]~/.local/share/man\f[] to your \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
+\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).
+.PP
+If you have ShellCheck (https://www.shellcheck.net/) and/or
+Perl::Critic (http://perlcritic.com/), there's a \f[C]lint\f[] target
+for the shell script files and Perl files respectively.
+The files don't need to pass that check to be installed.
+.SS Known issues
+.PP
+See ISSUES.markdown.
+.SS Note for previous visitors
+.PP
+Most of this repository's five\-year history was rewritten shortly after
+I moved it from GitHub to cgit, taking advantage of the upheaval to
+reduce its size and remove useless binary blobs and third\-party stuff
+that I never should have versioned anyway.
+If you've checked this out before, you'll probably need to do it again,
+and per\-commit links are likely to be broken.
+Sorry about that.
+.SS License
+.PP
+Public domain; see the included \f[C]UNLICENSE\f[] file.
+It's just configuration and simple scripts, so do whatever you like with
+it if any of it's useful to you.
+If you're feeling generous, please join and/or donate to a free software
+advocacy group, and let me know you did it because of this project:
+.IP \[bu] 2
+Free Software Foundation (https://www.fsf.org/)
+.IP \[bu] 2
+Software in the Public Interest (http://www.spi-inc.org/)
+.IP \[bu] 2
+OpenBSD Foundation (http://www.openbsdfoundation.org/)
+.SH AUTHORS
+Tom Ryder.