Reference content goes in docstrings, explanations go in prose docs.

Also, make sure docstrings reference the prose docs, so people who stumble over
an interesting-looking command or option can find out more about it.

rc/tools/autorestore.kak

@@ -1,8 +1,18 @@
-declare-option -docstring "remove backups once they've been restored" \
+declare-option -docstring %{
+        Remove backups once they've been restored
+
+        See `:doc autorestore` for details.
+    } \
     bool autorestore_purge_restored true
 
 ## Insert the content of the backup file into the current buffer, if a suitable one is found
-define-command autorestore-restore-buffer -docstring "Restore the backup for the current file if it exists" %{
+define-command autorestore-restore-buffer \
+    -docstring %{
+        Restore the backup for the current file if it exists
+
+        See `:doc autorestore` for details.
+    } \
+%{
     evaluate-commands %sh{
         buffer_basename="${kak_buffile##*/}"
         buffer_dirname=$(dirname "${kak_buffile}")
@@ -48,7 +58,13 @@ define-command autorestore-restore-buffer -docstring "Restore the backup for the
 }
 
 ## Remove all the backups that have been created for the current buffer
-define-command autorestore-purge-backups -docstring "Remove all the backups of the current buffer" %{
+define-command autorestore-purge-backups \
+    -docstring %{
+        Remove all the backups of the current buffer
+
+        See `:doc autorestore` for details.
+    } \
+%{
     evaluate-commands %sh{
         [ ! -f "${kak_buffile}" ] && exit
 
@@ -64,7 +80,13 @@ define-command autorestore-purge-backups -docstring "Remove all the backups of t
 }
 
 ## If for some reason, backup files need to be ignored
-define-command autorestore-disable -docstring "Disable automatic backup recovering" %{
+define-command autorestore-disable \
+    -docstring %{
+        Disable automatic backup recovering
+
+        See `:doc autorestore` for details.
+    } \
+%{
     remove-hooks global autorestore
 }
 

rc/tools/doc.kak

@@ -163,6 +163,8 @@ define-command -params 1..2 \
     doc -docstring %{
         doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
         An optional keyword argument can be passed to the function, which will be automatically selected in the documentation
+
+        See `:doc doc` for details.
     } %{
     evaluate-commands %sh{
         page=$(

rc/tools/lint.asciidoc

@@ -12,9 +12,10 @@ If the 'kind' field contains 'error', the message is treated as an error,
 otherwise it is assumed to be a warning.
 
 The `:lint-buffer` and `:lint-selections` commands will run the shell command
-specified in the `lintcmd` option, collect the result in the `*lint-output*`
-buffer, and analyze it. If `toolsclient` is set, the `*lint-output*` buffer will
-be displayed in the named client.
+specified in the `lintcmd` option, passing it the path to a temporary file
+containing the text to be linted. The results are collected in the
+`*lint-output*` buffer, and analyze it. If `toolsclient` is set, the
+`*lint-output*` buffer will be displayed in the named client.
 
 Each reported error or warning causes a marker to appear in the left-hand
 margin of the buffer that was checked. When the main cursor moves onto that

rc/tools/lint.kak

@@ -2,13 +2,7 @@ declare-option \
     -docstring %{
         The shell command used by lint-buffer and lint-selections.
 
-        It will be given the path to a file containing the text to be
-        linted, and must produce output in the format:
-
-            {filename}:{line}:{column}: {kind}: {message}
-
-        If the 'kind' field contains 'error', the message is treated
-        as an error, otherwise it is assumed to be a warning.
+        See `:doc lint` for details.
     } \
     str lintcmd
 
@@ -230,6 +224,8 @@ define-command \
         Switches:
             -command <cmd>      Use the given linter.
                                 If not given, the lintcmd option is used.
+
+        See `:doc lint` for details.
     } \
     lint-selections \
 %{
@@ -275,7 +271,7 @@ define-command \
     -docstring %{
         lint-buffer: Check the current buffer with a linter.
 
-        Set the lintcmd option to control which linter is used.
+        See `:doc lint` for details.
     } \
     lint-buffer \
 %{