1 files changed, 94 insertions(+), 31 deletions(-)

M pkgs/kakoune/.config/kak/init.md

@@ 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