Wes Turner

@westurner

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”.

  1. Markup headings with two or more # signs.
  2. 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:

This simple pattern saves time when looking up my keyboard shortcuts.

EDIT: 2014-12-16: Updated links to https://westurner.github.io/dotfiles/