~chambln/dots

a5ed34c9881c2fddd8fce347529a774427a6d265 — Gregory Chamberlain 14 days ago 4fa8b05
Develop literate Kakoune config
1 files changed, 94 insertions(+), 31 deletions(-)

M pkgs/kakoune/.config/kak/init.md
M pkgs/kakoune/.config/kak/init.md => pkgs/kakoune/.config/kak/init.md +94 -31
@@ 7,18 7,29 @@ title: Kakoune configuration
# What is this?

This document is my Kakoune configuration in a [literate programming]
style. The Kakoune commands can be extracted using the following
command:

``` {.sh}
pandoc -t json init.md | jq -r '
    .blocks
  | map (select(.t == "CodeBlock" and .c[0][1][0] == "kak"))
style. The Kakoune commands can be extracted from the source markup by
first converting it to JSON format with [pandoc][](1), then piping the
result through the following jq(1) program:

``` {.jq}
.blocks
  | map(select(.t == "CodeBlock" and
               .c[0][1][0] == "kak"))
  | .[].c
  | .[1]'
```

I want a comment at the top warning any passers by that the file will be
My actual `kakrc` configuration file is very short---it simply performs
this extraction process and writes the commands to `init.kak`, which it
then sources with `source %val{config}/init.kak`. If `init.kak` is newer
than `init.md`, then the extraction stage is skipped.

**Warning:** The "newer than" test uses the `-nt` option of test(1),
which unfortunately is not specified by POSIX. However, it is present on
all major POSIX-compliant operating systems.

Because of this automatic file regeneration, it's probably a good idea
to put a comment at the top warning any passers by that the file will be
clobbered, directing them to make changes here instead.

``` {.kak}


@@ 42,30 53,19 @@ distracting, so this option makes it hidden until I hit
set-option global autocomplete prompt
```

# Normal mode mappings

``` {.kak}
map -docstring 'quit' global normal q ':i-quit<ret>'
```

# The goto menu

``` {.kak}
map global goto d '<a-semicolon>:i-delete-buffer<ret>'
map -docstring 'prev buffer' global goto p <a-semicolon>:bp<ret>
map -docstring 'next buffer' global goto n <a-semicolon>:bn<ret>
```
# Interactive commands

# The user menu
This command pipes the selection through some command, collecting the
results in a dedicated scratch buffer called `*sh*`. Any previous
results are discarded.

``` {.kak}
map -docstring 'eval sels' global user , :<space><c-r>.<ret>
map -docstring 'pipe sels' global user | :pipe<space>
map -docstring 'shell command' global user ! ':echo %sh{}<left>'
map -docstring 'edit kakrc' global user <semicolon> ':e<space>"%val{config}/init.md"<ret>'
define-command pipe -params .. -shell-completion %{
    execute-keys "y:edit -scratch *sh*<ret><esc>%%<a-d><a-p>|%arg{@}<ret>"
}
```

# Interactive commands
Undocumented:

``` {.kak}
define-command pwd %{


@@ 85,17 85,77 @@ define-command cd-here %{
        printf 'cd %s; pwd\n' "$dir"
    }
}
```

# Hooks

## Default directory

Whenever I open a file I usually want to be in its directory. This is
analogous to Emacs' buffer local `default-directory` variable.

``` {.kak}
hook global BufOpenFile .* cd-here
hook global BufNewFile  .* cd-here
```

## Markdown

Set the `formatcmd`:

``` {.kak}
define-command pipe -params .. -shell-completion %{
    execute-keys "y:edit -scratch *sh*<ret><esc>%%<a-d><a-p>|%arg{@}<ret>"
hook global WinSetOption filetype=markdown %{
    set-option window formatcmd 'pandoc -stmarkdown --reference-links --atx-headers'
}
```

# Git
# Mappings

## Normal mode

``` {.kak}
map -docstring quit global normal q :i-quit<ret>
```

## Goto menu

``` {.kak}
map -docstring 'delete buffer' global goto d <a-semicolon>:i-delete-buffer<ret>
map -docstring 'prev buffer' global goto p <a-semicolon>:bp<ret>
map -docstring 'next buffer' global goto n <a-semicolon>:bn<ret>
```

## User menu

Shortcut for jumping to this document:

``` {.kak}
map -docstring 'edit kakrc' \
    global user <semicolon> ':e "%val{config}/init.md"<ret>'
```

Very useful for working with Kakoune commands is this mapping that
evaluates the selections as though they had been written into Kakoune's
command prompt.

``` {.kak}
map -docstring 'eval sels' global user , :<space><c-r>.<ret>
```

Sometimes you want to pipe the selection through some command without
replacing it. This mapping uses the pipe command [defined earlier] to do
exactly that. The standard output can be seen in the `*sh*` scratch
buffer.

``` {.kak}
map -docstring 'pipe sels' global user | :pipe<space>
```

``` {.kak}
map -docstring 'shell command' global user ! ':echo %sh{}<left>'
```

## Git

``` {.kak}
map global user g ': git status -bs<ret>' -docstring 'git status'


@@ 121,10 181,13 @@ hook global WinSetOption filetype=git-log %{

# Plugins

## kakoune-interactively
## [kakoune-interactively]

``` {.kak}
set-option global yes_or_no_instant false
```

  [literate programming]: https://en.wikipedia.org/wiki/Literate_programming
  [pandoc]: https://pandoc.org
  [defined earlier]: #interactive-commands
  [kakoune-interactively]: https://github.com/chambln/kakoune-interactively