add and restore some docstrings

home/-shrc

@@ -5,7 +5,7 @@
 # {{{1 utilities
 
 if [ -z "$ZSH_VERSION" ]; then
-    has() { # hardcode this function from ~/sh/has for convenience
+    has() { ### @- hardcoded here for convenience.
         which "$1" >/dev/null 2>&1 && which "$1"
     }
 fi
@@ -21,7 +21,8 @@ else
     alias maybesudo="maybesudo_ " # allows aliases within the alias
 fi
 
-ADDPATH() {
+ADDPATH() { ### @ ADDPATH
+    ### append a directory to `$PATH` if it isn't already present.
     new="$(readlink -f "$1")"
     if [ ! -d "$new" ]; then
         echo -E "ADDPATH: path doesn't exist: $1" >&2
@@ -109,38 +110,38 @@ alias lr="lr -G"
 
 export LESS='-SRQ'
 alias db="dropbox_uploader"
-alias fils="du -bahd1"
+alias fils="du -bahd1" ### @- (GNU du) display human-friendly filesizes for the files in a directory.
-alias lsa="ls -A --group-directories-first"
+alias lsa="ls -A --group-directories-first" ### @- (GNU ls) list files with directories and dotfiles ordered first.
-alias perlu='perl -Mopen=locale -Mutf8'
+alias perlu='perl -Mopen=locale -Mutf8' ### @- invoke perl expecting files with UTF-8 encoding.
-alias rgn="rg --no-ignore"
+alias rgn="rg --no-ignore" ### @- invoke ripgrep without respecting `.gitignore` files.
-alias cms="cryptominisat5 --verb 0"
+alias cms="cryptominisat5 --verb 0" ### @- invoke cryptominisat5 with less noise.
-alias curls="curl -sS"
+alias curls="curl -sS" ### @- invoke curl with less noise.
 
 # git {{{2
 
-alias get="git clone --single-branch --depth 1"
+alias get="git clone --single-branch --depth 1" ### @- retrieve the most recent files from the default branch of a git repository, and not much else.
-alias gs='git status' # rip ghostscript
+alias gs='git status' ### @- invoke git's status subcommand.
-alias gd='git diff -U2'
+alias gd='git diff -U2' ### @- invoke git's diff subcommand with fewer lines of context.
-alias gds='git --no-pager diff --stat'
+alias gds='git --no-pager diff --stat' ### @- display difference stats from git.
-alias gl='git log --oneline'
+alias gl='git log --oneline' ### @- invoke git's log subcommand with a single line per commit.
-alias glo='git log --graph --decorate --pretty=oneline --abbrev-commit --all'
+alias glo='git log --graph --decorate --pretty=oneline --abbrev-commit --all' ### @- navigate git's commit tree succinctly.
-alias g1='git log --pretty=oneline --abbrev-commit --color=always | head -1'
+alias g1='git log --pretty=oneline --abbrev-commit --color=always | head -1' ### @- display the most recent git commit.
-alias gr='git remote -v'
+alias gr='git remote -v' ### @- display remote git repositories verbosely.
-alias gb='git --no-pager branch'
+alias gb='git --no-pager branch' ### @- display the current git branch.
 
 # being specific {{{2
 
 [ -e "$HOME/python3" ] && alias py="~/python3" || alias py="python3"
 alias pip="maybesudo -H pip3"
-alias revend='objcopy -I binary -O binary --reverse-bytes=4'
+alias revend='objcopy -I binary -O binary --reverse-bytes=4' ### @- reverse the 4-byte endianness of a single file. *this is an in-place operation!*
 alias aur="BUILDDIR=$HOME/src $HOME/sh/aur -jj"
-alias clone='maybesudo rsync -aHA --info=progress2 --no-i-r'
+alias clone='maybesudo rsync -aHA --info=progress2 --no-i-r' ### @- invoke rsync suitably for creating virtually indistinguishable copies of files.
-alias aligntabs="column -t -s$'\t'"
+alias aligntabs="column -t -s$'\t'" ### @- align tab-delimited fields in stdin.
-alias crawla='ssh joshua@crawl.akrasiac.org -i ~/.ssh/crawl'
+alias crawla='ssh joshua@crawl.akrasiac.org -i ~/.ssh/crawl' ### @- play Dungeon Crawl: Stone Soup through ssh on the akrasiac server.
-alias crawlz='ssh crawl@crawl.develz.org -i ~/.ssh/crawl'
+alias crawlz='ssh crawl@crawl.develz.org -i ~/.ssh/crawl' ### @- play Dungeon Crawl: Stone Soup through ssh on the develz server.
 
 alias ll="lol" # workaround for a strange issue with bash
-lol() {
+lol() { ### @ ll - list files verbosely, fancily, ordered, but not recursively.
     { lr -1lshGG -o tev -t 'name~~".*"||type==d' "$@" \
      && lr -1lshGG -o tev -t 'name!~~".*"&&type!=d' "$@" \
      || ls -lAX --group-directories-first --color=force "$@"; } | less
@@ -148,28 +149,31 @@ lol() {
 
 # providing extra functionality {{{2
 
-alias diff="git diff --color=auto --no-ext-diff --no-index --no-prefix"
+alias diff="git diff --color=auto --no-ext-diff --no-index --no-prefix" ### @- use git's diff subcommand for general diffing.
-alias gc="git column --mode=dense --padding=2"
+alias gc="git column --mode=dense --padding=2" ### @- columnize text by using git's column subcommand.
-alias counts='find . | wc -l'
+alias counts='find . | wc -l' ### @- count files in the current directory, including files found recursively.
-alias exts="find -type f | grep -o '\\.[^/.]*$' | sort | uniq -c | sort -n"
+alias exts="find -type f | grep -o '\\.[^/.]*$' | sort | uniq -c | sort -n" ### @- count and sort file extensions in the current directory, including files found recursively.
-alias nocom='grep -Ev --line-buffered --color=never "^[[:space:]]*(//|#)"'
+alias nocom='grep -Ev --line-buffered --color=never "^[[:space:]]*(//|#)"' ### @- strip single-line C-like and shell-like comments.
-alias sortip="sort -t . -k 1,1n -k 2,2n -k 3,3n -k 4,4n"
+alias sortip="sort -t . -k 1,1n -k 2,2n -k 3,3n -k 4,4n" ### @- sort numerically by IPv4 segments.
-alias jrep='grep -aPo "[\x{20}-\x{7E}\x{4E00}-\x{9FFF}\x{3040}-\x{30FF}]+"'
+alias jrep='grep -aPo "[\x{20}-\x{7E}\x{4E00}-\x{9FFF}\x{3040}-\x{30FF}]+"' ### @- extract strings comprised of basic ASCII or Japanese codepoints.
-alias bomb='uconv -f utf-8 -t utf-8 --add-signature'
+alias bomb='uconv -f utf-8 -t utf-8 --add-signature' ### @- add a Byte-Order Mark to a file.
-alias cleanse='tr -cd "\11\12\15\40-\176"'
+alias cleanse='tr -cd "\11\12\15\40-\176"' ### @- strip unprintable and non-ASCII characters.
-alias rot13='tr "A-Za-z0-9" "N-ZA-Mn-za-m5-90-4"'
+alias rot13='tr "A-Za-z0-9" "N-ZA-Mn-za-m5-90-4"' ### @- rot13 with numbers rotated as well.
-alias unwrap='awk '\''BEGIN{RS="\n\n";FS="\n"}{for(i=1;i<=NF;i++)printf "%s ",$i;print "\n"}'\'
+alias unwrap='awk '\''BEGIN{RS="\n\n";FS="\n"}{for(i=1;i<=NF;i++)printf "%s ",$i;print "\n"}'\' ### @- join paragraphs into one line each.
-alias double='awk "{print;print}"'
+alias double='awk "{print;print}"' ### @- print every line twice. <br/> print every line twice.
-alias join2='paste -d" " - -'
+alias join2='paste -d" " - -' ### @- join every other line.
-alias katagana='perlu -MUnicode::Normalize -pe'"'"'$_=NFKD($_)=~y/ァ-ヶ /ぁ-ゖ　/r'"'"
+alias katagana='perlu -MUnicode::Normalize -pe'"'"'$_=NFKD($_)=~y/ァ-ヶ /ぁ-ゖ　/r'"'" ### @- convert katakana codepoints to their equivalent hiragana.
-alias picky='{ pacman -Qgq base base-devel xorg xorg-drivers xfce4 | double; pacman -Qeq; } | sort | uniq -u'
+### useful for translating [debug text from ancient games.](https://tcrf.net/)
-alias unused='{ pacman -Qtq; pacman -Qeq | double; } | sort | uniq -u'
+alias picky='{ pacman -Qgq base base-devel xorg xorg-drivers xfce4 | double; pacman -Qeq; } | sort | uniq -u' ### @- TODO
-alias makepkgf='makepkg -Af --skipchecksums --skippgpcheck'
+alias unused='{ pacman -Qtq; pacman -Qeq | double; } | sort | uniq -u' ### @- TODO
-alias rakef='rake && gem build *.gemspec && gem install *.gem'
+alias makepkgf='makepkg -Af --skipchecksums --skippgpcheck' ### @- make the freakin' package!
+alias rakef='rake && gem build *.gemspec && gem install *.gem' ### @- make the freakin' gem!
 
-eashare() {
+eashare() { ### @- upload a file and copy its URL to the clipboard.
-    # NOTE: this only works on MSYS2 for now.
+    ###
-    # NOTE: i lied, this doesn't work anymore. idk
+    ### **NOTE:** this only works on MSYS2 for now.
+    ###
+    ### **NOTE:** i lied, this doesn't work at all.
     local dest="${1##*/}"
     eaput "$1" || return 1
     printf "%s" "$_REMOTE_DOMAIN/$_REMOTE_DIR/$dest" >> /dev/clipboard

home/bashrc

@@ -46,5 +46,4 @@ ADDPATH "$HOME/sh"
 . ~/.sh-bash
 : $((SOURCING-=1))
 
-# TODO: respect initctl like in .zshrc.
+alias reload='cd; exec bash' ### @- **TODO:** respect initctl like in `.zshrc`.
-alias reload='cd; exec bash'

home/zshrc

@@ -68,22 +68,30 @@ function {
 
 local fuzzy=`has fzy || print`
 
-dirprev() {
+dirprev() { ### @ dirprev
+    ### rotate and change to the previous directory in the directory stack
+    ### without consuming the prompt.
     pushd -q +1
     zle reset-prompt
     precmd
 }
-dirnext() {
+dirnext() { ### @ dirnext
+    ### rotate and change to the next directory in the directory stack
+    ### without consuming the prompt.
     pushd -q -0
     zle reset-prompt
     precmd
 }
-dirup() {
+dirup() { ### @ dirup
+    ### change to the parent directory of the current working directory
+    ### without consuming the prompt.
     cd ..
     zle reset-prompt
     precmd
 }
-dirview() {
+dirview() { ### @ dirview
+    ### use a fuzzy finder to select a recent directory in the directory stack
+    ### and change to it without consuming the prompt.
     print
     if [ -n "$fuzzy" ]; then
         local d="$(dirs -pl | awk '!seen[$0]++' | "$fuzzy")"
@@ -155,21 +163,26 @@ bindkey '^Xe' edit-command-line # ctrl+x -> e
 
 . ~/.-shrc
 
-alias -g OMFG="1>/dev/null"
+alias -g OMFG="1>/dev/null" ### @ OMFG - silence stdout.
-alias -g STFU="2>/dev/null"
+alias -g STFU="2>/dev/null" ### @ STFU - silence stderr.
-alias -g WHOA='${whoa[@]}'
+alias -g WHOA='${whoa[@]}' ### @ WHOA - expand to several C/C++ flags to ease development.
-alias -g WELP='${welp[@]}'
+alias -g WELP='${welp[@]}' ### @ WELP - expand to C++ flags to enable a C++-as-C facade.
 
 alias sc="~/sh/sc" # only runs in bash (for now), so be explicit with path
-alias pl="print -l" # not in -shrc because this only makes sense with zsh
+# not in -shrc because this only makes sense with zsh:
+alias pl="print -l" ### @ pl - print each argument on its own line.
 
-function tw() { # needs the "function" keyword or else zsh complains
+# needs the "function" keyword or else zsh complains:
+function tw() { ### @ tw
+    ### invoke `twitch` as a job with both stdout and stderr silenced.
     twitch "$@" OMFG STFU &
 }
 
 local host="${(L)HOST}"
 
 function {
+    # initialize prompts.
+
     local t="${TERM%%-*}"
     if [ "$t" = xterm ] || [ "$t" = screen ] || [ "$t" = tmux ]; then
         # set window title
@@ -204,7 +217,9 @@ function {
     PROMPT="%{$reset${s}%(?.${good}.${bad})${e}${s}97${e}%}%#%{$reset%} "
 }
 
-reload() {
+reload() { ### @ reload
+    ### reload zsh by wiping temp files, recompiling rc files,
+    ### and replacing the current process with a new zsh process.
     # initctl has a "reload" symlink, but i'm already too used to typing this.
     # to remedy this, when args are passed, invoke initctl instead.
     if [ $# -gt 0 ]; then
@@ -229,6 +244,7 @@ reload() {
 
 # generated by dircolors with https://github.com/isene/LS_COLORS
 function {
+    # initialize colors for ls.
     local lsc= line=
     < ~/.ls_colors | tr -d $'\r' | while read -r line; do
         lsc+="$line:"

sh/arith

@@ -6,7 +6,8 @@
 # though technically compatible with other shells,
 # extra functionality is through zsh's extended arithmetic functions.
 
-arith() {
+arith() { ### @-
+    ### perform arithmetic using the shell and display the result.
 #   <<<"$(($@))"
     printf "%s\n" "$(($@))"
 }

sh/aur

@@ -4,7 +4,10 @@
 
 # TODO: check compatibility with bash and dash.
 
-aur() {
+aur() { ### @-
+    ### download, edit, make, and install packages from the
+    ### [AUR.](https://aur.archlinux.org/)
+    ### it's a little broken.
     trap 'exit 1' SIGINT SIGTERM
 
     local bd="${BUILDDIR:-$PWD}"

sh/autosync

@@ -5,7 +5,9 @@
 
 # TODO: portable way of dodging aliases to allow other shell support?
 
-autosync() {
+autosync() { ### @-
+    ### combine `inotifywait` and `rsync`.
+    ### this is sometimes nicer than `ssh`-ing into a server and running `vim` remotely.
     target="$1"
     shift
     # as a reminder not to get the argument order mixed up:

sh/cdbusiest

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 # YES_ZSH
 
-cdbusiest() {
+cdbusiest() { ### @-
+    ### cd to the directory with the most files in it, counted recursively.
     dbusiest | read -r c d
     [ -z $c ] && return 1
     printf "%s\n" "$c $d"

sh/colors

@@ -3,7 +3,9 @@
 # YES_BASH
 # NO_DASH
 
-colors() {
+colors() { ### @-
+    ### print out all the foreground and background terminal color combinations.
+    ### excluding boilerplate, this script is a mere a 76-characters long!
     [ $# -eq 0 ] || { printf "%s\n" "$0: does not take arguments" >&2; return 1; }
     printf "\e[%dm$(printf " \e[%dm mV \e[40m" {4,10}{0..7})\e[0m\n" {3,9}{0..7}
 }

sh/compandy

@@ -2,7 +2,9 @@
 # script to make sense of compand's parameters
 # YES_ZSH
 
-compandy() {
+compandy() { ### @-
+    ### generate compand arguments for ffmpeg audio filters.
+    ### this is kinda pointless now that acompressor is wildly supported.
     if [ $# -eq 0 ]; then
         echo -E "usage: $0 {threshold} {ratio} [attack] [release] [knee] [gain] [delay]"
         return 1

sh/compile

@@ -4,7 +4,7 @@
 # NO_DASH
 
 # I'll just leave this here...
-__setup_clang_ubuntu() {
+__setup_clang_ubuntu() { ### @-
     local site="http://apt.llvm.org"
     local name="$(lsb_release -c | cut -f2)"
     local version=10 # NOTE: no longer decimal-based
@@ -26,7 +26,20 @@ deb $site/$name/ llvm-toolchain-$name-$version main\n\
     echo update-alternatives --install /usr/bin/llvm-symbolizer llvm-symbolizer /usr/bin/llvm-symbolizer-$version $priority
 }
 
-compile() {
+compile() { ### @-
+    ### compile single-file C and C++ programs, messily.
+    ###
+    ### supports gcc and clang on \*nix, and mingw64 gcc, msvc clang,
+    ### and regular msvc on Windows. tested on x86\_64 and on ARMv7 as well.
+    ### does not support MacOS, maybe someday…
+    ###
+    ### defaults to gnu11 and gnu++1z as C and C++ standards respectively.
+    ### defaults to clang, gcc, and msvc in that order.
+    ###
+    ### `compile` attempts to guess the most sane switches for any program, so that compilation may reduce to:
+    ###
+    ### **TODO:** restore examples.
+
     # FIXME: compile gcc portrend.c -lsdl
     # this causes mayhem!
 

sh/confirm

@@ -3,6 +3,17 @@
 # YES_BASH
 # NO_DASH
 
+### @ confirm
+### display a simple yes-or-no prompt and return 0-or-1 respectively.
+###
+### ```
+### $ confirm && echo yay || echo nay
+### Continue? [y/N] y
+### yay
+### $ confirm && echo yay || echo nay
+### Continue? [y/N] n
+### nay
+### ```
 if [ -n "$ZSH_VERSION" ]; then
     confirm() {
         [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }

sh/days

@@ -3,7 +3,13 @@
 # YES_BASH
 # YES_DASH
 
-days() {
+days() { ### @-
+    ### compute days since a given date.
+    ###
+    ### ```
+    ### $ days 'January 1 1970'
+    ### 18838
+    ### ```
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     echo $(( ($(date +%s) - $(date -d "$1" +%s)) / 60 / 60 / 24 ))
 }

sh/dbusiest

@@ -3,7 +3,8 @@
 # NO_BASH
 # NO_DASH
 
-dbusiest() {
+dbusiest() { ### @-
+    ### display the directory with the most files in it, counted recursively.
     [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     local c d
     for d in *(FDN); do

sh/dfu

@@ -3,7 +3,10 @@
 # YES_BASH
 # YES_DASH
 
-dfu() {
+dfu() { ### @-
+    ### pretty-print `df` in GiB.
+    ###
+    ### **TODO:** restore examples.
     [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     df -xtmpfs | awk '
     NR==1{printf"%-20s %7s %7s %7s %7s\n","Filesystem","Used","Max","Left","Misc"}

sh/disf

@@ -6,7 +6,8 @@
 
 # TODO: actually test that this works with dash.
 
-function disf() {
+function disf() { ### @-
+    ### disassemble a single function from an unstripped executable, unreliably.
     [ $# -le 2 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     local exe="${1:?first argument should be an unstripped executable}"
     local symbol="${2:?second argument should be a function name}"

sh/document

@@ -64,14 +64,16 @@ document2() {
             if [ "$n" = "$e" ]; then
                 printf '\n### [%s](%s)\n\n' "$n" "$url" >> rc/README.md~ || return 5
             else
-                printf '\n### [%s](%s)\n\n' "$n.${f#.}" "$url" >> rc/README.md~ || return 5
+                printf '\n### [%s](%s)\n\n' "$n (${f#.})" "$url" >> rc/README.md~ || return 5
                 #printf '\n### %s\n\n* defined in [%s](%s)\n\n' "$n" "$f" "$url" >> rc/README.md~ || return 5
             fi
         fi
 
         if [ "$s" != ' ' ]; then
+            if [ -z "$n" -o -n "$s" ]; then
                 printf '%s\n' "$s" >> rc/README.md~ || return 5
             fi
+        fi
     done < "$f" || return 4
 }
 

sh/e

@@ -3,7 +3,14 @@
 # NO_BASH
 # NO_DASH
 
-e() {
+e() { ### @-
+    ### wrap around `$EDITOR` to run it as root if necessary.
+    ### this still needs some work to detect root-owned directories.
+    ###
+    ### ```
+    ### $ e /etc/sudoers
+    ### [sudo] password for notwa: 
+    ### ```
     local editor=(${=EDITOR})
     local running=0
 

sh/has

@@ -3,7 +3,10 @@
 # YES_BASH
 # YES_DASH
 
-has() {
+has() { ### @-
+    ### print the result of `which` if the program is found, else simply return 1.
+    ###
+    ### `export CC="$(has clang || has clang-3.8 || has gcc)"`
     if [ -n "$ZSH_VERSION" ]; then
         whence -p "$1"
     else

sh/hex

@@ -6,7 +6,8 @@
 # though technically compatible with other shells,
 # extra functionality is through zsh's extended arithmetic functions.
 
-hex() {
+hex() { ### @-
+    ### perform arithmetic using the shell and display the result as an unsigned 32-bit integer in hexadecimal.
     printf "%08X\n" "$(($@))"
 }
 

sh/ify

@@ -3,7 +3,16 @@
 # YES_BASH
 # YES_DASH
 
-ify() {
+ify() { ### @-
+    ### pipe one command through another, so you can still pass arguments to the former.
+    ###
+    ### this is mainly useful for aliases. 99% of the time you'll use this with `less`.
+    ###
+    ### ```
+    ### $ alias ll="ify less ls -ACX --group-directories-first --color=force"
+    ### $ ll /etc
+    ### ```
+
     [ $# -ge 2 ] || { printf "%s\n" "$0: too few arguments" >&2; return 1; }
     local ex="$1"
     shift

sh/is_empty

@@ -3,7 +3,8 @@
 # YES_BASH
 # NO_DASH
 
-is_empty() {
+is_empty() { ### @-
+    ### return 0 if the directory given by argument is empty.
     while read -r f; do
         [ ! -d "$f" ] && [ -s "$f" ] && return 1
     done < <(find ${1:-.})

sh/isup

@@ -5,7 +5,8 @@
 
 # TODO: damned substrings. rewrite to be semi-portable.
 
-isup() {
+isup() { ### @-
+    ### return 0 if a given website returns a 2xx HTTP code.
     local c
     curl -sLI -w '%{http_code}' -o /dev/null "$1" | read -r c
     [ "${c:0:1}" -eq 2 ]

sh/minutemaid

@@ -1,11 +1,17 @@
 #!/usr/bin/env dash
-# crontab usage:
-#* * * * * minutemaid 9 ~/work/do_my_bidding # runs every nine minutes
 # YES_ZSH
 # YES_BASH
 # YES_DASH
 
-minutemaid() {
+minutemaid() { ### @-
+    ### return 0 if the current minute is divisible by a number.
+    ### note that a minute is relative to the seconds since the epoch, not the minute of the hour.
+    ###
+    ### ```
+    ### # crontab usage:
+    ### * * * * * minutemaid 9 ~/work/do_my_bidding # runs every nine minutes
+    ### ```
+
     local offset=0 name
     while getopts 'o:h' name; do
         case $name in

sh/monitor

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 # YES_ZSH
 
-monitor() {
+monitor() { ### @-
+    ### this is `watch` loosely reimplemented as a shell script.
     local bottom=0 strip=0 interval=2 opt=
     while getopts 'fsn:h' opt; do
         case $opt in

sh/noccom

@@ -7,7 +7,8 @@
 
 # TODO: what's the minimum version of perl required for this?
 
-noccom() {
+noccom() { ### @-
+    ### strip C-like comments; both multi-line and single-line.
     [ -s ~/opt/local/bin/noccom ] || cat > ~/opt/local/bin/noccom <<EOF
 #!/usr/bin/env perl
 

sh/now

@@ -5,7 +5,18 @@
 
 # dash compatibility is not fully tested, but it's probably okay.
 
-now() {
+now() { ### @-
+    ### print a date-time (UTC) in a sortable format.
+    ### this takes a date or file as an argument,
+    ### else it defaults to the current time.
+    ### ```
+    ### $ now
+    ### 2019-05-27_35083906
+    ### $ now ~/sh/monitor
+    ### 2017-03-14_82387259
+    ### $ now '@1234567890'
+    ### 2009-02-13_84690000
+    ### ```
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     local dt
     local fmt='+%F_%T_%N'

sh/pacbm

@@ -3,7 +3,14 @@
 # YES_BASH
 # YES_DASH
 
-pacbm() {
+pacbm() { ### @-
+    ### list installed pacman packages by their filesize, and the sum, ascending. requires `expac`.
+    ###
+    ### ```
+    ### $ pacbm | head -n -1 | tail -2
+    ###   204.78M clang
+    ###   235.44M linux-firmware
+    ### ```
     expac -s '%m %n' | awk '
     {t+=$1;printf("%8.2fM %s\n",$1/(1024*1024),$2)}
     END{printf("%8.2fM\n",t/(1024*1024))}

sh/pause

@@ -3,7 +3,14 @@
 # YES_BASH
 # NO_DASH
 
-pause() {
+pause() { ### @-
+    ### pause — the companion script of `confirm`.
+    ###
+    ### ```
+    ### $ pause
+    ### Press any key to continue
+    ### $ 
+    ### ```
     [ -n "${ZSH_VERSION:-}" ] \
       && read -sk '?Press any key to continue
 '     || read -n1 -u 1 -sp 'Press any key to continue

sh/pre

@@ -3,7 +3,10 @@
 # YES_BASH
 # YES_DASH
 
-pre() {
+pre() { ### @-
+    ### dump all the `#define`s that `$CC $CPPFLAGS $CFLAGS $LDFLAGS` would result in.
+    ###
+    ### **TODO:** restore examples.
     if [ -n "${ZSH_VERSION:-}" ]; then
         ${CC:-gcc} -dM -E - $=CPPFLAGS $=CFLAGS $=LDFLAGS < /dev/null
     else

sh/randir

@@ -3,7 +3,13 @@
 # YES_BASH
 # YES_DASH
 
-randir() {
+randir() { ### @-
+    ### display a random directory in the current working directory.
+    ###
+    ### ```
+    ### $ randir
+    ### ./sh
+    ### ```
     find -maxdepth 1 -type d \( -path '/root' -prune -o -print \) | tail -n+2 | shuf | head -n1
 }
 

sh/rs

@@ -1,8 +1,10 @@
 #!/usr/bin/env zsh
-# rs: record screen
 # YES_ZSH
 
-rs() {
+rs() { ### @-
+    ### record screen. does not record audio.
+    ### currently only works on Windows (gdigrab).
+    ### i'm sure there's something equivalent for Linux.
     set -e
 
     local o_overwrite= o_rate=30 o_duration=0

sh/sc

@@ -37,7 +37,10 @@ copy_tmp() {
     return 0
 }
 
-sc() {
+sc() { ### @-
+    ### upload given files to a webserver and return a direct link for sharing them.
+    ### you'll want to tweak this if you use it yourself.
+    ### this contains some extra logic for screenshots created by `scropt`.
     if [ -n "${ZSH_VERSION:-}" ]; then
         # syntax is too different to bother tbh
         echo "please run with bash"

sh/scramble

@@ -3,7 +3,10 @@
 # YES_BASH
 # YES_DASH
 
-scramble() {
+scramble() { ### @-
+    ### scrambles text in a predictable way using regex.
+    ###
+    ### sacbremls ttex in a pdrceailtbe way unsig reegx.
     [ $# -eq 0 ] || { printf "%s\n" "$0: does not take arguments" >&2; return 1; }
     local eggs='s/@\(\w\)\(\w\)\(\w\)/@\3\1@\2/g'
     sed \

sh/screeny

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 # YES_ZSH
 
-screeny() {
+screeny() { ### @-
+    ### i don't use this anymore~
     local user="${1:?needs arg for user name}"
     shift
     home="/home/$user"

sh/scropt

@@ -1,11 +1,14 @@
 #!/usr/bin/env bash
 # YES_ZSH
 
-: $((SOURCING+=1))
+#: $((SOURCING+=1))
 #. ~/sh/now # FIXME: don't do this?
-: $((SOURCING-=1))
+#: $((SOURCING-=1))
 
-scropt() {
+scropt() { ### @-
+    ### run `scrot` through `optipng` and save the result to `~/play/$(now).png`.
+    ###
+    ### `$ ~/sh/sc $(~/sh/scropt -s -d0.5)`
     local now=$(now)
     [ $? -eq 0 ] || return $?
     local fn="$HOME/play/$now.png"

sh/slit

@@ -3,7 +3,8 @@
 # YES_BASH
 # YES_DASH
 
-slit() {
+slit() { ### @-
+    ### view specific columns of text.
     [ $# -gt 0 ] || { printf "%s\n" "$0: too few arguments" >&2; return 1; }
     awk "{ print $(printf ',$%s' $@ | cut -b2-) }"
 

sh/slitt

@@ -1,10 +1,11 @@
 #!/usr/bin/env dash
-# this version of slit uses tabs for input/output field separators.
 # YES_ZSH
 # YES_BASH
 # YES_DASH
 
-slitt() {
+slitt() { ### @-
+    ### view specific columns of text.
+    ### this version of `slit` uses tabs for its field separators.
     [ $# -gt 0 ] || { printf "%s\n" "$0: too few arguments" >&2; return 1; }
     #echo "$@" | awk '{for(i=1;i<NF;i++)printf"$%s,",$(i);print"$"$NF}'
     local fields="$(printf ',$%s' $@ | cut -b2-)"

sh/sram

@@ -1,7 +1,8 @@
 #!/usr/bin/env zsh
 # YES_ZSH
 
-sram() {
+sram() { ### @-
+    ### convert between a couple saveram formats for N64 emulators.
     die() {
         echo -E "$@">&2
         exit 1

sh/streamcrap

@@ -54,7 +54,8 @@ fi
 
 unset _nn
 
-mpv_watch() {
+mpv_watch() { ### @-
+    ### watch something in mpv with a bunch of extra audio filtering crap.
     pushd ~/play >/dev/null
     local url="$1"; shift
     mpv \
@@ -65,7 +66,8 @@ mpv_watch() {
     popd >/dev/null
 }
 
-mpv_stream() {
+mpv_stream() { ### @-
+    ### watch a stream in mpv with a bunch of extra audio filtering crap.
     pushd ~/play >/dev/null
     local url="$1"; shift
     if [ -n "$ZSH_VERSION" ]; then
@@ -77,12 +79,18 @@ mpv_stream() {
     popd >/dev/null
 }
 
-twitch() {
+twitch() { ### @-
+    ### watch a twitch stream in mpv with a bunch of extra audio filtering crap.
     local user="$1"; shift
     mpv_stream "http://twitch.tv/$user" "$@"
 }
 
-yt() {
+yt() { ### @-
+    ### watch a youtube video in mpv with a bunch of extra audio filtering crap.
+    ### this can be given a full URL or just a video ID.
+    ### remaining arguments are passed to mpv.
+    ###
+    ### there exist several variants for more specific use cases.
     local vid="$1"; shift
     if [[ ! -e "$vid" && "$(expr substr "$vid" 1 4)" != "http" ]]; then
         vid="ytdl://$vid"
@@ -90,26 +98,31 @@ yt() {
     mpv_watch "$vid" "$@"
 }
 
-ytg() {
+ytg() { ### @-
+    ### watch a youtube video. like `yt`, but with a preference for different formats.
     local vid="$1"; shift
     yt "$vid" --ytdl-format=22/95/300/best "$@"
 }
 
-ytll() {
+ytll() { ### @-
+    ### watch a stream on youtube in mpv, etcetera etcetera.
+    ### this is the low latency version that does not support seeking.
     youtube-dl -q -f best "$1" -o - | mpv_stream - --no-ytdl
 }
 
-ytgll() {
+ytgll() { ### @-
+    ### watch a stream on youtube in mpv. like `ytll`, but with a preference for different formats.
     youtube-dl -q -f 22/95/300/best "$1" -o - | mpv_stream - --no-ytdl
 }
 
-ai() {
+ai() { # @-
-    # hai domo
+    # hai domo!
     yt "$@" --slang=en --sub-font='Tekton Pro' --sub-bold=yes \
       --sub-font-size=60 --sub-border-color='#DD6180' --sub-margin-y=52
 }
 
-asmr() {
+asmr() { # @-
+    # for your aural pleasure.
     _M_PROCESS="acompressor=threshold=0.001:ratio=1.33:attack=900:release=6000:makeup=6:knee=8:mix=0.9,alimiter" \
       yt "$@" --volume=90 --ytdl-format=251/300/best
 }

sh/sv

@@ -3,7 +3,17 @@
 # YES_BASH
 # YES_DASH
 
-sv() {
+sv() { ### @-
+    ### collect the lastmost value of every key.
+    ### the field separator can be given as its sole argument.
+    ###
+    ### ```
+    ### echo "this=that\nthem=those\nthis=cat" | sv =
+    ### this=cat
+    ### them=those
+    ### ```
+    ###
+    ### **TODO:** add multi-file grep example.
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     awk "-F${1:- }" '
     NF>1{f[$1]=substr($0,length($1)+1+length(FS))}END{for(k in f)print k FS f[k]}

sh/tpad

@@ -3,7 +3,9 @@
 # YES_BASH
 # YES_DASH
 
-tpad() {
+tpad() { ### @-
+    ### add a 1px transparent border around an image to prevent twitter from mangling it into a jpg.
+    ### sadly, this trick doesn't work anymore.
     for f; do
         gm convert -bordercolor "#000000FF" -border 1x1 "$f" "${f%.png}.tt.png"
     done

sh/trunc

@@ -3,7 +3,8 @@
 # YES_BASH
 # YES_DASH
 
-trunc() {
+trunc() { ### @-
+    ### truncate text to fit within your terminal using the unicode character `…`.
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     COLUMNS=${COLUMNS:-$(tput cols)}
     awk -vL=${1:-$COLUMNS} '{e=length>L?"…":"";print substr($0,0,L-(e?1:0)) e}'

sh/unscreen

@@ -3,7 +3,8 @@
 # NO_BASH
 # NO_DASH
 
-unscreen() {
+unscreen() { ### @-
+    ### i don't use this anymore~
     local pids="$(screen -ls | fgrep "$1" | cut -d. -f1)"
     for pid in $=pids; do
         local ppid="$(ps h --ppid "$pid" -o pid)"

sh/wipe

@@ -3,8 +3,12 @@
 # YES_BASH
 # YES_DASH
 
-wipe() {
+wipe() { ### @-
-    # TODO: rename because wipe(1) already exists.
+    ### clear the screen and its scrollback, then print a high-contrast horizontal line.
+    ### using this, you'll know with absolute certainty that you're looking at the top of your history,
+    ### and that your terminal's scrollback didn't cap out and eat text.
+    ###
+    ### **TODO:** rename because wipe(1) already exists.
     [ $# -le 0 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     clear
     clear # twice because mintty is weird