Literate Configuration
Problem: configuration files which specify keyboard shortcuts can be difficult to grep through. It’s not always easy to get a simple commented list of configured keyboard shortcuts.
Solution: Approach configuration documentation like literate programming: “literate configuration”.
- Markup headings with two or more # signs.
- Markup comment lines with a # prefix and at least two spaces.
Example
Take an abbreviated excerpt from the i3wm .i3/config that I cleaned up this morning.
#### i3 config file (v4)
### Notes
# # Default location: ~/.i3/config
# # List the commented command shortcuts with::
# # cat ~/.i3/config | egrep '(^(\s+)?##+ |^(\s+)?# )'
#...
## Change volume
# <XF86AudioRaiseVolume> -- volume up
bindsym XF86AudioRaiseVolume exec --no-startup-id $volume_up
# <XF86AudioLowerVolume> -- volume down
bindsym XF86AudioLowerVolume exec --no-startup-id $volume_down
## Start, stop, and reset xflux
# <alt> [ -- start xflux
bindsym $mod+bracketleft exec --no-startup-id $xflux_start
# <alt> ] -- stop xflux
bindsym $mod+bracketright exec --no-startup-id $xflux_stop
# <alt><shift> ] -- reset gamma to 1.0
bindsym $mod+Shift+bracketright exec --no-startup-id $xflux_reset
## Resize Mode
# <alt> r -- enter resize mode
bindsym $mod+r mode "resize"
mode "resize" {
## Grow and shrink windows
# These bindings trigger as soon as you enter the resize mode
# ...
# back to normal: Enter or Escape
# <enter> -- exit resize mode
bindsym Return mode "default"
# <esc> -- exit resize mode
bindsym Escape mode "default"
}
Run it through extended grep with a simple conditional regular expression:
cat ~/.i3/config | egrep '(^(\s+)?##+ |^(\s+)?# )'
Peruse the output for that one excellent keyboard shortcut
#### i3 config file (v4)
### Notes
# # Default location: ~/.i3/config
# # List the commented command shortcuts with::
# # cat ~/.i3/config | egrep '(^(\s+)?##+ |^(\s+)?# )'
## Change volume
# <XF86AudioRaiseVolume> -- volume up
# <XF86AudioLowerVolume> -- volume down
## Start, stop, and reset xflux
# <alt> [ -- start xflux
# <alt> ] -- stop xflux
# <alt><shift> ] -- reset gamma to 1.0
## Resize Mode
# <alt> r -- enter resize mode
## Grow and shrink windows
# <enter> -- exit resize mode
# <esc> -- exit resize mode
Add the -n switch to grep to display the source line numbers of the relevant configuration file documentation.
The docco homepage lists quite a few more heavyweight approaches to generating documentation from comment strings embedded in various languages (such as Markdown in a shell script).
I’ve added documentation with this pattern to my dotfiles:
- bashrc (bashrc docs)
- vimrc (vimrc docs)
- .i3/config (.i3/config docs)
- and the provis Makefile (provis Makefile docs)
This simple pattern saves time when looking up my keyboard shortcuts.
EDIT: 2014-12-16: Updated links to https://westurner.github.io/dotfiles/