bpb-kit/README.md

bpb-kit
=======

This repo is for dotfiles, utility scripts, and other things in my personal
setup.  Ideally, it includes most of the bits and pieces that make a personal
machine usable for me.

I mostly use Debian and Debian-like GNU/Linux systems (including Ubuntu).  I
usually edit text in Vim, and use the [xmonad][xmonad] tiling window manager.

I have a [partially-finished book about the command line][userland] which may
be relevant.

status
------

As of October 2016, most of this collection is actively maintained, although it
doesn't meet the standards of quality, consistency, or documentation you might
quite reasonably want from a real software project.

(Then again, neither do most software projects.)

sources
-------

I thief ideas and bits of configuration from the following people and projects:

  - [Alan][alan]
  - [Ben][ben]
  - [Casey][casey]
  - [Chris][chris]
  - [Christian][christian]
  - [Dave][dave]
  - [Rob][rob]
  - [Todd][todd]
  - [Tyler][tyler]
  - [Learn Vimscript the Hard Way][vimscript], Steve Losh
  - [Advanced Bash Scripting Guide][bash-guide], Mendel Cooper
  - [ArchWiki][archwiki]

contents
--------

### shell stuff

These days I use ZSH on personal systems and Bash when writing tutorials or
doing tech support.  I like to keep lots and lots of history.  I think shell
scripting is a nightmare for most real tasks, but I do it sometimes anyway.

  - [`.bashrc`](home/.bashrc)
  - [`.zshrc`](home/.zshrc) - nothing fancy
  - [`.sh_common`](home/.sh_common) - aliases and variables for both Bash and ZSH;
    no Bash compatibility guarantees here, since I mostly don't use custom
    aliases in Bash

### scripts in [home/bin/](home/bin)

Scripts here fall into a handful of categories:

  - Short wrappers for getting (or remembering) specific behavior from other
    tools
  - Screenshot and screencast tools used in my work as a writer for
    DigitalOcean and Adafruit
  - Things for working with the [p1k3](https://p1k3.com/) repo and site
  - Text filters and fragments, mostly for use with Vim aliases
  - Miscellaneous utilities

Most of these are unlikely to be portable, useful, or documented.

  - `chrome-incognito`: run Google Chrome in incognito mode
  - `cheat`: a place to hang a personal cheatsheet of sorts
  - `dmenu_unique`: run dmenu with big fonts and vertical, only showing each entry once
  - `dog`: concatenate argument strings and stdin
  - `filter-decorate`: splat some text dingbats into HTML I write sometimes
  - `filter-exec-raw`: like above, but different
  - `filter-exec`: replace text in-between markers with result of shell-script execution
  - `filter-markdownify`: convert a few things in old DigitalOcean tutorials to Markdown
  - `filter-vertical`: verticalize a string
  - `firefox-fromselection`: open a selected url in firefox
  - `fragment-bullet`: print out a "random" dingbat character
  - `get-external-ip`: print public IP address
  - `gif-sel`, `gif-sel-4`, `gif-sel-15`: take an animated gif of selected screen region
  - `git-diff-wrapper`: use vim with `git-diff-tool`
  - `git-local-to-remote-status`
  - `grab`, `grab-sel`: take a screenshot, take a screenshot of a selected region
  - `json_decode.php`: decode JSON into PHP data structures
  - `jsonprint.pl`: pretty-print JSON with Perl
  - `jump-to-window`: use `wmctrl` and `dmenu` to pick a window to jump to
  - `listusers`: print an HTML list of users
  - `notesession`: start a tmux named session for notes
  - `photocp`: copy photos from various media to a home directory location
  - `pmwhich`: find the on-filesystem location of a Perl module
  - `rightnow`: print the current time in a variety of formats
  - `saytime`: speak the time with Festival
  - `timelog`: parse a timelogging format (I use this to bill for contracting)
  - `today`: print a date
  - `todaydir`: find a p1k3 dir for the current date
  - `uni`: search unicode codepoint names (via @chneukirchen)
  - `unsorted-unique`: print all lines of input once (just an `awk` one-liner)
  - `wip`: move a p1k3 file into a work-in-progress directory
  - `words`: split input into individual words
  - `xm`: call xmodmap (dumb)
  - `xmonad.start`: personal version of xmonad startup script
  - `xtfix`: do a subtle color shift within the current xterm
  - `yank`, `unyank`: stash a file path, move it to the current directory

### tmux

I use `tmux` for terminal multiplexing (i.e., most of what GNU Screen does).
In practice, this means that I rely on it for

  - persistent shell sessions, sometimes attached to multiple machines
  - putting a bunch of shell / editor buffers inside one `ssh` or `mosh`
    session
  - capturing and scrolling back through a bunch of output

My [`.tmux.conf`](home/.tmux.conf) is brief, but does contain one useful
snippet for correcting weird Esc-key behavior in Vim.

### vim config

  - [`.vimrc`](home/.vimrc) - see file for installation details
  - uses [Vundle][vundle] to manage plugins and such
  - pulls in a ton of plugins, some more useful than others

### window management

  - `.xmodmap`
    - capslock -> ctrl
    - I run this a bunch with `bin/xm`, which is dumb
  - `.xinitrc`
    - sources `.hacksrc` if it exists
  - `.Xresources` tweaks xterm behavior and a number of fonts
    - behavior changes depending on whether `.hacksrc` is linked to
      `.hacksrc_hi_dpi`
  - XMonad config -
    - `.xmobarrc`, `.xmonad/`
    - see [`bin/xmonad.start`](bin/xmonad.start) for a drop-in replacement for
      default XMonad startup on some Debian-like systems, including Gnome/Unity
      stuff and the like. Perpetually not-quite-right.

building a debian package for dependencies
------------------------------------------

See instructions in [ns-control](ns-control).

[userland]: https://p1k3.com/userland-book/
[vundle]: https://github.com/VundleVim/Vundle.vim
[alan]: https://github.com/acg
[ben]: https://github.com/benlemasurier
[chris]: https://github.com/frencil
[christian]: http://chneukirchen.org/blog/
[dave]: https://stilldavid.com/
[casey]: https://github.com/caseydentinger/
[rob]: https://github.com/robacarp/
[todd]: https://uniontownlabs.org/
[tyler]: https://tylercipriani.com/
[xmonad]: http://xmonad.org/
[vimscript]: http://learnvimscriptthehardway.stevelosh.com/
[bash-guide]: http://www.tldp.org/LDP/abs/html/
[archwiki]: https://wiki.archlinux.org/