From a8ab2cfec48cea3dd1fdf1013eec4a95423e92db Mon Sep 17 00:00:00 2001 From: Tom Ryder Date: Sat, 1 Jul 2017 17:12:57 +1200 Subject: Solve Pandoc issue by not building page at all --- .gitignore | 1 - ISSUES.markdown | 3 - Makefile | 9 - README.markdown | 10 +- man/man7/dotfiles.7df | 947 +++++++++++++++++++++++++++++++++++++++++++ man/man7/dotfiles.7df.header | 3 - 6 files changed, 950 insertions(+), 23 deletions(-) create mode 100644 man/man7/dotfiles.7df delete mode 100644 man/man7/dotfiles.7df.header diff --git a/.gitignore b/.gitignore index bf219412..21d294c4 100644 --- a/.gitignore +++ b/.gitignore @@ -162,5 +162,4 @@ git/gitconfig.m4 gnupg/gpg.conf gnupg/gpg.conf.m4 include/mktd.m4 -man/man7/dotfiles.7df urxvt/ext/select diff --git a/ISSUES.markdown b/ISSUES.markdown index 37803dcc..48007919 100644 --- a/ISSUES.markdown +++ b/ISSUES.markdown @@ -4,9 +4,6 @@ Known issues * man(1) completion doesn't work on OpenBSD as manpath(1) isn't a thing on that system; need to find some way of finding which manual directories should be searched at runtime, if there is one. -* pandoc(1) is awesome, but heavy as hell and requires Haskell. A more - lightweight recipe to make an acceptable man page out of the README would - be great. * The checks gscr(1df) makes to determine where it is are a bit naïve (don't work with bare repos) and could probably be improved with some appropriate git-reflog(1) calls diff --git a/Makefile b/Makefile index 2adc814b..22d5ac8e 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,6 @@ install-bin \ install-bin-man \ install-curl \ - install-dotfiles-man \ install-dunst \ install-ex \ install-finger \ @@ -303,10 +302,6 @@ gnupg/gpg.conf: gnupg/gpg.conf.m4 -D KEYSERVER=$(KEYSERVER) \ gnupg/gpg.conf.m4 > $@ -man/man7/dotfiles.7df: README.markdown man/man7/dotfiles.7df.header - cat man/man7/dotfiles.7df.header README.markdown | \ - pandoc -sS -t man -o $@ - MAILDIR = $(HOME)/Mail install: install-bin \ @@ -348,10 +343,6 @@ install-bin-man: install-curl: cp -p -- curl/curlrc $(HOME)/.curlrc -install-dotfiles-man: man/man7/dotfiles.7df - mkdir -p -- $(HOME)/.local/share/man/man7 - cp -p -- man/man7/*.7df $(HOME)/.local/share/man/man7 - install-dunst: install-x mkdir -p -- $(HOME)/.config/dunst cp -p -- dunst/dunstrc $(HOME)/.config/dunst diff --git a/README.markdown b/README.markdown index 0f134be4..30e94d10 100644 --- a/README.markdown +++ b/README.markdown @@ -565,13 +565,9 @@ Manuals ------- The `install-bin` and `install-games` targets install manuals for each script -they install. There's also an `install-dotfiles-man` target that uses -`pandoc(1)` to reformat this document as a manual page for section 7 -(`dotfiles(7df)`) if you want that. I haven't made that install by default, -because `pandoc(1)` is a bit heavy. - -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. +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. Testing ------- diff --git a/man/man7/dotfiles.7df b/man/man7/dotfiles.7df new file mode 100644 index 00000000..831af06d --- /dev/null +++ b/man/man7/dotfiles.7df @@ -0,0 +1,947 @@ +.\" Automatically generated by Pandoc 1.17.2 +.\" +.TH "DOTFILES" "7" "June 2016" "Tom Ryder's personal scripts and configuration" "" +.hy +.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. +.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. +.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 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: +.IP +.nf +\f[C] +$\ tmpdir=$(mktemp\ \-d) +$\ make\ install\ HOME="$tmpdir" +$\ env\ \-i\ HOME="$tmpdir"\ TERM="$TERM"\ "$SHELL"\ \-l +\f[] +.fi +.PP +The default \f[C]install\f[] target will install these targets and all +their dependencies. +Note that you don't actually have to have any of this except \f[C]sh\f[] +installed. +.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[] +.IP \[bu] 2 +\f[C]install\-git\f[] +.IP \[bu] 2 +\f[C]install\-gnupg\f[] +.IP \[bu] 2 +\f[C]install\-less\f[] +.IP \[bu] 2 +\f[C]install\-login\-shell\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[]. +.PP +The remaining dotfiles can be installed with the other +\f[C]install\-*\f[] targets. +Try \f[C]awk\ \-f\ bin/mftl.awk\ Makefile\f[] in the project's root +directory to see a list. +.SS Tools +.PP +Configuration is included for: +.IP \[bu] 2 +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/) (2.05a or higher) +.IP \[bu] 2 +Korn shell (http://www.kornshell.com/) (\f[C]ksh93\f[], \f[C]pdksh\f[], +\f[C]mksh\f[]) +.IP \[bu] 2 +Z shell (https://www.zsh.org/) +.RE +.IP \[bu] 2 +Abook (http://abook.sourceforge.net/) \[en] curses address book program +.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+ (https://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[] (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 +.IP \[bu] 2 +Newsbeuter (https://www.newsbeuter.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 +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 +X11 (https://www.x.org/wiki/) \[en] Windowing system with network +transparency for Unix +.PP +The configurations for shells, 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. +.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. +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. +.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 +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 indices, 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 +A terminal session with my prompt looks something like this: +.IP +.nf +\f[C] +~$\ ssh\ remote +remote:~$\ cd\ .dotfiles +remote:~/.dotfiles(master+!)$\ git\ status +\ M\ README.markdown +M\ \ bash/bashrc.d/prompt.bash +A\ \ init +remote:~/.dotfiles(master+!)$\ foobar +foobar:\ command\ not\ found +remote:~/.dotfiles(master+!)<127>$\ sleep\ 5\ & +[1]\ 28937 +remote:~/.dotfiles(master+!){1}$ +\f[] +.fi +.PP +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: +.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 +If you start up Bash, Ksh, or Zsh and it detects that it's not normally +your \f[C]$SHELL\f[], the prompt will 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 +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 +Four functions for using a \[lq]marked\[rq] directory, which I find a +more manageable concept than the \f[C]pushd\f[]/\f[C]popd\f[] directory +stack: +.RS 2 +.IP \[bu] 2 +\f[C]md()\f[] marks a given (or the current) directory. +.IP \[bu] 2 +\f[C]gd()\f[] goes to the marked directory. +.IP \[bu] 2 +\f[C]pmd()\f[] prints the marked directory. +.IP \[bu] 2 +\f[C]xd()\f[] swaps the current and marked directories. +.RE +.IP \[bu] 2 +Ten other directory management and navigation functions: +.RS 2 +.IP \[bu] 2 +\f[C]bd()\f[] changes into a named ancestor of the current directory. +.IP \[bu] 2 +\f[C]gt()\f[] changes into a directory or into a file's directory. +.IP \[bu] 2 +\f[C]lgt()\f[] runs \f[C]gt()\f[] on the first result from a +\f[C]loc(1df)\f[] search. +.IP \[bu] 2 +\f[C]mkcd()\f[] creates a directory and changes into it. +.IP \[bu] 2 +\f[C]pd()\f[] changes to the argument's parent directory. +.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]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]ud()\f[] changes into an indexed ancestor of a directory. +.IP \[bu] 2 +\f[C]vr()\f[] tries to change to the root directory of a source control +repository. +.RE +.IP \[bu] 2 +\f[C]bc()\f[] silences startup messages from GNU \f[C]bc(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, just for convenience when running it interactively. +.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 if available. +.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]ls()\f[] tries to apply color and other options good 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. +.RE +.IP \[bu] 2 +\f[C]path()\f[] manages the contents of \f[C]PATH\f[] conveniently. +.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]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]tree()\f[] colorizes GNU \f[C]tree(1)\f[] output if possible +(without having \f[C]LS_COLORS\f[] set). +.IP \[bu] 2 +\f[C]x()\f[] is a one\-key shortcut for \f[C]exec\ startx\f[]. +.PP +There are a few other little tricks defined for other shells providing +non\-POSIX features, as compatibility allows: +.IP \[bu] 2 +\f[C]keep()\f[] stores ad\-hoc shell functions and variables (Bash, Korn +Shell 93, Z shell). +.IP \[bu] 2 +\f[C]prompt()\f[] sets up my interactive prompt (Bash, Korn Shell, Z +shell). +.IP \[bu] 2 +\f[C]pushd()\f[] adds a default destination of \f[C]$HOME\f[] to the +\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). +.IP \[bu] 2 +\f[C]ver()\f[] prints the current shell's version information (Bash, +Korn Shell, Z shell). +.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 +Bash builtins: commands, help topics, shell options, variables, etc. +.IP \[bu] 2 +\f[C]find(1)\f[]'s more portable options +.IP \[bu] 2 +\f[C]ftp(1)\f[] hostnames from \f[C]~/.netrc\f[] +.IP \[bu] 2 +\f[C]git(1)\f[] subcommands, remotes, branches, tags, and addable files +.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]pass(1)\f[] entries +.IP \[bu] 2 +\f[C]ssh(1)\f[] hostnames from \f[C]~/.ssh/config\f[] +.PP +For commands that pretty much always want to operate on text, such as +text file or stream editors, I exclude special file types and extensions +I know are binary. +I don't actually read the file, so this is more of a heuristic thing, +and sometimes it will get things wrong. +.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 Korn shell +.PP +These are experimental; they are mostly used to tinker with MirBSD +\f[C]mksh\f[], AT&T \f[C]ksh93\f[], and OpenBSD \f[C]pdksh\f[]. +All shells in this family default to a yellow prompt if detected. +.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[]). +\f[C]zsh\f[] shells default to having a prompt coloured cyan. +.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]mi5(1df)\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 (https://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 and S/MIME 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 (https://dejavu-fonts.github.io/). +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 shell scripts in \f[C]bin\f[] include \f[C]tm(1df)\f[], a shortcut +to make \f[C]attach\f[] into the default command if no arguments are +given and sessions do already exist. +My \f[C]~/.inputrc\f[] file binds Alt+M to run that, and Tmux in turn +binds the same key combination to detach. +.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[]. +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]\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 +Seven 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]slow(1df)\f[] converts uppercase to lowercase. +.IP \[bu] 2 +\f[C]supp(1df)\f[] converts lowercase to uppercase. +.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 +Six simple aggregators for numbers: +.RS 2 +.IP \[bu] 2 +\f[C]max(1df)\f[] prints the maximum. +.IP \[bu] 2 +\f[C]mean(1df)\f[] prints the mean. +.IP \[bu] 2 +\f[C]med(1df)\f[] prints the median. +.IP \[bu] 2 +\f[C]min(1df)\f[] prints the minimum. +.IP \[bu] 2 +\f[C]mode(1df)\f[] prints the first encountered mode. +.IP \[bu] 2 +\f[C]tot(1df)\f[] totals the set. +.RE +.IP \[bu] 2 +Three quick\-and\-dirty HTML tools: +.RS 2 +.IP \[bu] 2 +\f[C]htenc(1df)\f[] encodes. +.IP \[bu] 2 +\f[C]htdec(1df)\f[] decodes. +.IP \[bu] 2 +\f[C]htrec(1df)\f[] wraps \f[C]a\f[] tags around URLs. +.RE +.IP \[bu] 2 +Two internet message quoting tools: +.RS 2 +.IP \[bu] 2 +\f[C]quo(1df)\f[] indents with quoting right angle\-brackets. +.IP \[bu] 2 +\f[C]wro(1df)\f[] adds a quote attribution header to its input. +.RE +.IP \[bu] 2 +Six Git\-related tools: +.RS 2 +.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]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]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. +.RE +.IP \[bu] 2 +Two time duration functions: +.RS 2 +.IP \[bu] 2 +\f[C]hms(1df)\f[] converts seconds to \f[C]hh:mm:ss\f[] or +\f[C]mm:ss\f[] timestamps. +.IP \[bu] 2 +\f[C]sec(1df)\f[] converts \f[C]hh:mm:ss\f[] or \f[C]mm:ss\f[] +timestamps to seconds. +.RE +.IP \[bu] 2 +Three pipe interaction tools: +.RS 2 +.IP \[bu] 2 +\f[C]pst(1df)\f[] runs an interactive program on data before passing it +along a pipeline. +.IP \[bu] 2 +\f[C]ped(1df)\f[] runs \f[C]pst(1df)\f[] with \f[C]$EDITOR\f[] or +\f[C]ed(1)\f[]. +.IP \[bu] 2 +\f[C]pvi(1df)\f[] runs \f[C]pvi(1df)\f[] with \f[C]$VISUAL\f[] or +\f[C]vi(1)\f[]. +.RE +.IP \[bu] 2 +\f[C]ap(1df)\f[] reads arguments for a given command from the standard +input, prompting if appropriate. +.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]bcq(1df)\f[] runs \f[C]bc(1)\f[], quieting it down if need be. +.IP \[bu] 2 +\f[C]bel(1df)\f[] prints a terminal bell character. +.IP \[bu] 2 +\f[C]bl(1df)\f[] generates a given number of blank lines. +.IP \[bu] 2 +\f[C]bp(1df)\f[] runs \f[C]br(1df)\f[] after prompting for an URL. +.IP \[bu] 2 +\f[C]br(1df)\f[] launches \f[C]$BROWSER\f[]. +.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]cfr(1df)\f[] does the same as \f[C]cf(1df)\f[], but recurses into +subdirectories as well. +.IP \[bu] 2 +\f[C]chc(1df)\f[] caches the output of a command. +.IP \[bu] 2 +\f[C]chn(1df)\f[] runs a filter over its input a given number of times. +.IP \[bu] 2 +\f[C]clog(1df)\f[] is a tiny timestamped log system. +.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]csmw(1df)\f[] prints an English list of monospace\-quoted words +read from the input. +.IP \[bu] 2 +\f[C]dam(1df)\f[] buffers all its input before emitting it as output. +.IP \[bu] 2 +\f[C]ddup(1df)\f[] removes duplicate lines from unsorted input. +.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]exm(1df)\f[] works around a screen\-clearing quirk of Vim's +\f[C]ex\f[] mode. +.IP \[bu] 2 +\f[C]finc(1df)\f[] counts the number of results returned from a set of +given \f[C]find(1)\f[] conditions. +.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]fnp(1df)\f[] prints the given files to stdout, each with a +plaintext heading with the filename in it. +.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]grec(1df)\f[] is a more logically\-named \f[C]grep\ \-c\f[]. +.IP \[bu] 2 +\f[C]gred(1df)\f[] is a more logically\-named \f[C]grep\ \-v\f[]. +.IP \[bu] 2 +\f[C]gwp(1df)\f[] searches for alphanumeric words in a similar way to +\f[C]grep(1)\f[]. +.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]ix(1df)\f[] posts its input to the ix.io pastebin. +.IP \[bu] 2 +\f[C]jfp(1df)\f[] prints its input, excluding any shebang on the first +line only. +.IP \[bu] 2 +\f[C]loc(1df)\f[] is a quick\-search wrapped around \f[C]find(1)\f[]. +.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]mex(1df)\f[] makes given filenames in \f[C]$PATH\f[] executable. +.IP \[bu] 2 +\f[C]mi5(1df)\f[] pre\-processes a crude but less painful macro +expansion file format into \f[C]m4\f[] input. +.IP \[bu] 2 +\f[C]mftl(1df)\f[] finds usable\-looking targets in Makefiles. +.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]mw(1df)\f[] prints alphabetic space\-delimited words from the input +one per line. +.IP \[bu] 2 +\f[C]oii(1df)\f[] runs a command on input only if there is any. +.IP \[bu] 2 +\f[C]onl(1df)\f[] crunches input down to one printable line. +.IP \[bu] 2 +\f[C]osc(1df)\f[] implements a \f[C]netcat(1)\f[]\-like wrapper for +\f[C]openssl(1)\f[]'s \f[C]s_client\f[] subcommand. +.IP \[bu] 2 +\f[C]p(1df)\f[] prints concatenated standard input; \f[C]cat(1)\f[] as +it should always have been. +.IP \[bu] 2 +\f[C]pa(1df)\f[] prints its arguments, one per line. +.IP \[bu] 2 +\f[C]pp(1df)\f[] prints the full path of each argument using +\f[C]$PWD\f[]. +.IP \[bu] 2 +\f[C]pph(1df)\f[] runs \f[C]pp(1df)\f[] and includes a leading +\f[C]$HOSTNAME:\f[]. +.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]pwg(1df)\f[] generates just one decent password with +\f[C]pwgen(1)\f[]. +.IP \[bu] 2 +\f[C]rep(1df)\f[] repeats a command a given number of times. +.IP \[bu] 2 +\f[C]rgl(1df)\f[] is a very crude interactive \f[C]grep(1)\f[] loop. +.IP \[bu] 2 +\f[C]shb(1df)\f[] attempts to build shebang lines for scripts from the +system paths. +.IP \[bu] 2 +\f[C]sqs(1df)\f[] chops off query strings from filenames, usually +downloads. +.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]swr(1df)\f[] allows you to run commands locally specifying remote +files in \f[C]scp(1)\f[]'s HOST:PATH format. +.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]tm(1df)\f[] runs \f[C]tmux(1)\f[] with +\f[C]attach\-session\ \-d\f[] if a session exists, and +\f[C]new\-session\f[] if it doesn't. +.IP \[bu] 2 +\f[C]trs(1df)\f[] replaces strings (not regular expression) in its +input. +.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. +.IP \[bu] 2 +\f[C]umake(1df)\f[] iterates upwards through the directory tree from +\f[C]$PWD\f[] until it finds a Makefile for which to run +\f[C]make(1)\f[] with the given arguments. +.IP \[bu] 2 +\f[C]uts(1df)\f[] gets the current UNIX timestamp in an unorthodox way +that should work on all POSIX\-compliant operating systems. +.IP \[bu] 2 +\f[C]vest(1df)\f[] runs \f[C]test(1)\f[] but fails with explicit output +via \f[C]vex(1df)\f[]. +.IP \[bu] 2 +\f[C]vex(1df)\f[] runs a command and prints \f[C]true\f[] or +\f[C]false\f[] explicitly to \f[C]stdout\f[] based on the exit value. +.IP \[bu] 2 +\f[C]xrbg(1df)\f[] applies the same randomly\-selected background to +each X screen. +.IP \[bu] 2 +\f[C]xrq(1df)\f[] gets the values of specific resources out of +\f[C]xrdb\ \-query\f[] output. +.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]aesth(6df)\f[] converts English letters to their fullwidth CJK +analogues, for ＡＥＳＴＨＥＴＩＣ　ＰＵＲＰＯＳＥＳ. +.IP \[bu] 2 +\f[C]squ(6df)\f[] makes a reduced Latin square out of each line of +input. +.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]strik(6df)\f[] outputs s̶t̶r̶i̶k̶e̶d̶ ̶o̶u̶t̶ struck out text. +.IP \[bu] 2 +\f[C]rot13(6df)\f[] rotates the Latin letters in its input. +.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(7df)\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]~/.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 +\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 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 (https://www.spi-inc.org/) +.IP \[bu] 2 +FreeBSD Foundation (https://www.freebsdfoundation.org/) +.IP \[bu] 2 +OpenBSD Foundation (http://www.openbsdfoundation.org/) +.SH AUTHORS +Tom Ryder. diff --git a/man/man7/dotfiles.7df.header b/man/man7/dotfiles.7df.header deleted file mode 100644 index cc8aef57..00000000 --- a/man/man7/dotfiles.7df.header +++ /dev/null @@ -1,3 +0,0 @@ -% DOTFILES(7) Tom Ryder's personal scripts and configuration -% Tom Ryder -% June 2016 -- cgit v1.2.3