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.  It may occasionally serve as a testbed for things that
will eventually become standalone projects.

I generally use Debian and Debian-like GNU/Linux systems (including Ubuntu),
with the [xmonad][xmonad] tiling window manager rather than a full desktop
environment like Gnome or KDE.  I usually edit text in Vim, with
[Vimwiki][vimwiki] for notes.  I maintain a blog called [p1k3][p1k3] using
[wrt][wrt].

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

status
------

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

(Then again, neither do most software projects.)

sources
-------

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

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

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][p1k3] repo and site
  - Text filters and template 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
  - `snowday`: is it a snow day for the Boulder Valley School District?
  - `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
  - `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

### fragments

The [fragments](fragments) directory is for code snippets that I write in the
course of testing some idea, checking a technique, or trying to solve a problem
posed by friends on IRC.

They're typically the kind of thing I'd throw in a random file called something
like `test.sh` and overwrite later.  It seemed useful to start collecting these
instead.

### 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
  - `.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).

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