From 42963051710cb8230256d8ca46b84295a93dd6c0 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 3 Sep 2020 01:19:20 +1000
Subject: [PATCH 1/6] doc.kak: Also search through plugins (stdlib and
 per-user) for docs.

This makes the somewhat-dubious assumption that every plugin will have uniquely-
named documentation files, instead of automatically putting every plugin's docs
into a namespace. However, plugins already have to deal with flat namespaces for
commands, options, filetypes, etc. so one more shouldn't hurt.

Fixes #2466.
---
 rc/tools/doc.kak | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak
index 6e0cf74e..b68f9363 100644
--- a/rc/tools/doc.kak
+++ b/rc/tools/doc.kak
@@ -137,9 +137,19 @@ define-command -params 1 -hidden doc-render %{
 define-command -params 1..2 \
     -shell-script-candidates %{
         if [ "$kak_token_to_complete" -eq 0 ]; then
-            find "${kak_runtime}/doc/" -type f -name "*.asciidoc" | sed 's,.*/,,; s/\.[^/]*$//'
+            (
+                find "${kak_runtime}/doc/" -type f -name "*.asciidoc"
+                find "${kak_runtime}/rc/" -type f -name "*.asciidoc"
+                find "${kak_config}/autoload/" -type f -name "*.asciidoc"
+            ) | sed 's,.*/,,; s/\.[^/]*$//'
         elif [ "$kak_token_to_complete" -eq 1 ]; then
-            readonly page="${kak_runtime}/doc/${1}.asciidoc"
+            page=$(
+                (
+                    find "${kak_runtime}/doc/" -type f -name "$1.asciidoc"
+                    find "${kak_runtime}/rc/" -type f -name "$1.asciidoc"
+                    find "${kak_config}/autoload/" -type f -name "$1.asciidoc"
+                ) | head -1
+            )
             if [ -f "${page}" ]; then
                 awk '
                     /^==+ +/ { sub(/^==+ +/, ""); print }
@@ -153,7 +163,13 @@ define-command -params 1..2 \
         An optional keyword argument can be passed to the function, which will be automatically selected in the documentation
     } %{
     evaluate-commands %sh{
-        readonly page="${kak_runtime}/doc/${1}.asciidoc"
+        page=$(
+            (
+                find "${kak_runtime}/doc/" -type f -name "$1.asciidoc"
+                find "${kak_runtime}/rc/" -type f -name "$1.asciidoc"
+                find "${kak_config}/autoload/" -type f -name "$1.asciidoc"
+            ) | head -1
+        )
         if [ -f "${page}" ]; then
             jump_cmd=""
             if [ $# -eq 2 ]; then

From d628cb50cf4752b83b3a1594e9fb54be26854951 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 3 Sep 2020 01:55:36 +1000
Subject: [PATCH 2/6] rc: Add some documentation for existing plugins..

---
 rc/tools/autorestore.asciidoc | 23 ++++++++++++++
 rc/tools/doc.asciidoc         | 15 +++++++++
 rc/tools/lint.asciidoc        | 57 +++++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+)
 create mode 100644 rc/tools/autorestore.asciidoc
 create mode 100644 rc/tools/doc.asciidoc
 create mode 100644 rc/tools/lint.asciidoc

diff --git a/rc/tools/autorestore.asciidoc b/rc/tools/autorestore.asciidoc
new file mode 100644
index 00000000..7112ae3b
--- /dev/null
+++ b/rc/tools/autorestore.asciidoc
@@ -0,0 +1,23 @@
+= Automatically restore unsaved work after a crash.
+
+When Kakoune crashes, it automatically writes out unsaved changes to backup
+files with predictable names. When you edit a file, if such a backup file
+exists, this plugin will automatically load the content of the backup file
+instead.
+
+== Commands
+
+*autorestore-restore-buffer*::
+    Restore the backup for the current file if it exists.
+
+*autorestore-purge-backups*::
+    Remove all the backups of the current buffer.
+
+*autorestore-disable*::
+    Disable automatic backup recovering for this session.
+
+== Options
+
+*autorestore_purge_restored* (bool)::
+    *default* true +
+    If true, remove backups once they've been restored
diff --git a/rc/tools/doc.asciidoc b/rc/tools/doc.asciidoc
new file mode 100644
index 00000000..ff1fbae9
--- /dev/null
+++ b/rc/tools/doc.asciidoc
@@ -0,0 +1,15 @@
+= Kakoune's online documentation
+
+== Commands
+
+*doc* <topic>::
+    *alias* help +
+    display documentation about a topic. The completion list displays the
+    available topics
+
+== Options
+
+*docsclient* (str)::
+    If set, the `:doc` command (and other commands that display documentation)
+    will try to display documentation in the Kakoune client with this name.
+    See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc
new file mode 100644
index 00000000..3590eb7e
--- /dev/null
+++ b/rc/tools/lint.asciidoc
@@ -0,0 +1,57 @@
+= Integrate with tools that check files for problems.
+
+Many file-formats have "lint" tools that check for common problems and point out
+where they occur. Most of these tools produce output in the the traditional
+message 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.
+
+This plugin can run such tools and collect the resulting messages. The complete
+output is collected in the `*lint-output*` buffer, and any lines in the current
+file with messages will have a marker displayed next to them in the left margin.
+When the cursor moves onto a line with the problem, the associated messages will
+be displayed in a tool tip..
+
+== Commands
+
+*lint-buffer*::
+    *alias* lint +
+    Pass the entire buffer through the program named in `lintcmd`. The buffer
+    may contain unsaved changes.
+
+*lint-selections* [-command <cmd>]::
+    Pass each of the selections through `<cmd>` or, if the `-command` switch is
+    not provided, through the program named in `lintcmd`. The buffer may contain
+    unsaved changes.
+
+*lint-hide-diagnostics*::
+    Hide line markers and disable the automatic display of messages, if any.
+
+*lint-next-message*::
+    Jump to the next message generated by the last `lint-buffer` or
+    `lint-selections` command.
+
+*lint-previous-message*::
+    Jump to the previous message generated by the last `lint-buffer` or
+    `lint-selections` command.
+
+== Options
+
+*lintcmd* (str)::
+    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:
+
+
+*toolsclient* (str)::
+    If set, the `:lint` command (and other commands that point out files and
+    line-numbers) will try to display its results in the Kakoune client with
+    this name.
+    See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
+

From e3298c63208ff86cfc7f9d3441f120d2edcc4e56 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 3 Sep 2020 15:06:24 +1000
Subject: [PATCH 3/6] Address code-review comments

- some wording changes in included documentation
- find supports multiple starting paths, we don't need to launch it 3 times
- Change the regex that trims the file extension to only trim the last extension

Some additional things I noticed:

- find should use -L to see through symlinks like the autoload processing does.
- find should check the user's autoload directory first, so users can override
  Kakoune's built-in documentation.
---
 rc/tools/doc.asciidoc  |  4 ++--
 rc/tools/doc.kak       | 33 ++++++++++++++++++---------------
 rc/tools/lint.asciidoc | 13 ++++++-------
 3 files changed, 26 insertions(+), 24 deletions(-)

diff --git a/rc/tools/doc.asciidoc b/rc/tools/doc.asciidoc
index ff1fbae9..14ea2920 100644
--- a/rc/tools/doc.asciidoc
+++ b/rc/tools/doc.asciidoc
@@ -10,6 +10,6 @@
 == Options
 
 *docsclient* (str)::
-    If set, the `:doc` command (and other commands that display documentation)
-    will try to display documentation in the Kakoune client with this name.
+    If set, the `:doc` command will try to display documentation in the Kakoune
+    client with this name.
     See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak
index b68f9363..d88dcda2 100644
--- a/rc/tools/doc.kak
+++ b/rc/tools/doc.kak
@@ -137,18 +137,20 @@ define-command -params 1 -hidden doc-render %{
 define-command -params 1..2 \
     -shell-script-candidates %{
         if [ "$kak_token_to_complete" -eq 0 ]; then
-            (
-                find "${kak_runtime}/doc/" -type f -name "*.asciidoc"
-                find "${kak_runtime}/rc/" -type f -name "*.asciidoc"
-                find "${kak_config}/autoload/" -type f -name "*.asciidoc"
-            ) | sed 's,.*/,,; s/\.[^/]*$//'
+            find -L \
+                "${kak_config}/autoload/" \
+                "${kak_runtime}/doc/" \
+                "${kak_runtime}/rc/" \
+                -type f -name "*.asciidoc" |
+                sed 's,.*/,,; s/\.[^.]*$//'
         elif [ "$kak_token_to_complete" -eq 1 ]; then
             page=$(
-                (
-                    find "${kak_runtime}/doc/" -type f -name "$1.asciidoc"
-                    find "${kak_runtime}/rc/" -type f -name "$1.asciidoc"
-                    find "${kak_config}/autoload/" -type f -name "$1.asciidoc"
-                ) | head -1
+                find -L \
+                    "${kak_config}/autoload/" \
+                    "${kak_runtime}/doc/" \
+                    "${kak_runtime}/rc/" \
+                    -type f -name "$1.asciidoc" |
+                    head -1
             )
             if [ -f "${page}" ]; then
                 awk '
@@ -164,11 +166,12 @@ define-command -params 1..2 \
     } %{
     evaluate-commands %sh{
         page=$(
-            (
-                find "${kak_runtime}/doc/" -type f -name "$1.asciidoc"
-                find "${kak_runtime}/rc/" -type f -name "$1.asciidoc"
-                find "${kak_config}/autoload/" -type f -name "$1.asciidoc"
-            ) | head -1
+            find -L \
+                "${kak_config}/autoload/" \
+                "${kak_runtime}/doc/" \
+                "${kak_runtime}/rc/" \
+                -type f -name "$1.asciidoc" |
+                head -1
         )
         if [ -f "${page}" ]; then
             jump_cmd=""
diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc
index 3590eb7e..da7213bf 100644
--- a/rc/tools/lint.asciidoc
+++ b/rc/tools/lint.asciidoc
@@ -1,8 +1,8 @@
 = Integrate with tools that check files for problems.
 
 Many file-formats have "lint" tools that check for common problems and point out
-where they occur. Most of these tools produce output in the the traditional
-message format:
+where they occur. Most of these tools produce output in the traditional message
+format:
 
 ----
 {filename}:{line}:{column}: {kind}: {message}
@@ -15,7 +15,7 @@ This plugin can run such tools and collect the resulting messages. The complete
 output is collected in the `*lint-output*` buffer, and any lines in the current
 file with messages will have a marker displayed next to them in the left margin.
 When the cursor moves onto a line with the problem, the associated messages will
-be displayed in a tool tip..
+be displayed in a tool tip.
 
 == Commands
 
@@ -46,12 +46,11 @@ be displayed in a tool tip..
     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:
+    linted, and must produce output in the format described above.
 
 
 *toolsclient* (str)::
-    If set, the `:lint` command (and other commands that point out files and
-    line-numbers) will try to display its results in the Kakoune client with
-    this name.
+    If set, the `:lint` command will try to display its results in the Kakoune
+    client with this name.
     See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
 

From 9934788155f8f8e52ca629b0437464c11352807a Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 3 Sep 2020 16:49:18 +1000
Subject: [PATCH 4/6] Add more user-oriented documentation for the
 documentation system.

---
 rc/tools/doc.asciidoc | 49 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/rc/tools/doc.asciidoc b/rc/tools/doc.asciidoc
index 14ea2920..c33698bd 100644
--- a/rc/tools/doc.asciidoc
+++ b/rc/tools/doc.asciidoc
@@ -1,11 +1,26 @@
 = Kakoune's online documentation
 
+This is Kakoune's online documentation system.
+
+== Using the documentation browser
+
+Documentation buffers are like any other buffer, so you can scroll through them
+as normal, search within a topic with `/`, etc. However, they can also contain
+links, <<doc#demonstration-target,like this>>. When you see a link, you can
+follow it by moving the cursor onto it and pressing Enter. If the link takes you
+to a different documentation topic, you can get back by using the `:buffer`
+command.
+
 == Commands
 
-*doc* <topic>::
+*doc* <topic> [<target>]::
     *alias* help +
-    display documentation about a topic. The completion list displays the
-    available topics
+    This command displays documentation about the named topic in a new buffer.
+    If a target is supplied, Kakoune will automatically jump to that target
+    when the buffer is opened.
+    +
+    For a list of available topics, or available targets within a topic, check
+    the completion menu that appears when typing the command at the prompt.
 
 == Options
 
@@ -13,3 +28,31 @@
     If set, the `:doc` command will try to display documentation in the Kakoune
     client with this name.
     See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
+
+== Writing documentation
+
+Documentation must be in AsciiDoc format, with the extension `.asciidoc`,
+and stored somewhere within <<doc#sources,the documentation search path>>.
+Kakoune's built-in documentation renderer does not necessarily support every
+feature, so don't go overboard with formatting.
+
+To create a link to another documentation topic, the URL should be the topic-
+name, just like <<doc#commands,`:doc`>> uses. Because topics are identified
+only by their basename, you should take care that your topic's name does not
+collide with any of the names used by other plugins or Kakoune's standard
+library.
+
+== Sources
+
+The <<doc#commands,`:doc` command>> searches within the following locations for
+documents in the AsciiDoc format (`*.asciidoc`):
+
+* The user plugin directory, `"%val{config}/autoload"`
+* The system documentation directory, `"%val{runtime}/doc"`
+* The system plugin directory, `"%val{runtime}/rc"`
+
+It searches recursively, and follows symlinks.
+
+== Demonstration target
+
+Well done! You can <<doc#using-the-documentation-browser,go back now>>!

From 66cc39cb140065daa00ab4b11370c3bfef0d9d12 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Thu, 3 Sep 2020 17:18:19 +1000
Subject: [PATCH 5/6] Update plugin docs to not duplicate docstring
 information.

---
 rc/tools/autorestore.asciidoc | 20 ++++----------
 rc/tools/doc.asciidoc         | 28 ++++++-------------
 rc/tools/lint.asciidoc        | 51 +++++++----------------------------
 3 files changed, 23 insertions(+), 76 deletions(-)

diff --git a/rc/tools/autorestore.asciidoc b/rc/tools/autorestore.asciidoc
index 7112ae3b..528fcf5c 100644
--- a/rc/tools/autorestore.asciidoc
+++ b/rc/tools/autorestore.asciidoc
@@ -5,19 +5,9 @@ files with predictable names. When you edit a file, if such a backup file
 exists, this plugin will automatically load the content of the backup file
 instead.
 
-== Commands
+By default, backup files are deleted when restored. You can set the
+`autorestore_purge_restored` option to `false` to prevent this.
 
-*autorestore-restore-buffer*::
-    Restore the backup for the current file if it exists.
-
-*autorestore-purge-backups*::
-    Remove all the backups of the current buffer.
-
-*autorestore-disable*::
-    Disable automatic backup recovering for this session.
-
-== Options
-
-*autorestore_purge_restored* (bool)::
-    *default* true +
-    If true, remove backups once they've been restored
+If you don't want backups to be restored automatically, use the
+`autorestore-disable` command to disable the feature for the current session,
+or put it in your `kakrc` to disable the feature forever.
diff --git a/rc/tools/doc.asciidoc b/rc/tools/doc.asciidoc
index c33698bd..407260a6 100644
--- a/rc/tools/doc.asciidoc
+++ b/rc/tools/doc.asciidoc
@@ -2,6 +2,12 @@
 
 This is Kakoune's online documentation system.
 
+To see what documentation topics are available, type `:doc` and look at the
+completion menu. To view the a particular documentation topic, type the topic
+name or choose it from the completion menu and hit Enter.
+
+Documentation will be displayed in the client named in the `docsclient` option.
+
 == Using the documentation browser
 
 Documentation buffers are like any other buffer, so you can scroll through them
@@ -11,24 +17,6 @@ follow it by moving the cursor onto it and pressing Enter. If the link takes you
 to a different documentation topic, you can get back by using the `:buffer`
 command.
 
-== Commands
-
-*doc* <topic> [<target>]::
-    *alias* help +
-    This command displays documentation about the named topic in a new buffer.
-    If a target is supplied, Kakoune will automatically jump to that target
-    when the buffer is opened.
-    +
-    For a list of available topics, or available targets within a topic, check
-    the completion menu that appears when typing the command at the prompt.
-
-== Options
-
-*docsclient* (str)::
-    If set, the `:doc` command will try to display documentation in the Kakoune
-    client with this name.
-    See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
-
 == Writing documentation
 
 Documentation must be in AsciiDoc format, with the extension `.asciidoc`,
@@ -37,14 +25,14 @@ Kakoune's built-in documentation renderer does not necessarily support every
 feature, so don't go overboard with formatting.
 
 To create a link to another documentation topic, the URL should be the topic-
-name, just like <<doc#commands,`:doc`>> uses. Because topics are identified
+name, just like `:doc` uses. Because topics are identified
 only by their basename, you should take care that your topic's name does not
 collide with any of the names used by other plugins or Kakoune's standard
 library.
 
 == Sources
 
-The <<doc#commands,`:doc` command>> searches within the following locations for
+The `:doc` command searches within the following locations for
 documents in the AsciiDoc format (`*.asciidoc`):
 
 * The user plugin directory, `"%val{config}/autoload"`
diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc
index da7213bf..3fe7f5ad 100644
--- a/rc/tools/lint.asciidoc
+++ b/rc/tools/lint.asciidoc
@@ -11,46 +11,15 @@ format:
 If the 'kind' field contains 'error', the message is treated as an error,
 otherwise it is assumed to be a warning.
 
-This plugin can run such tools and collect the resulting messages. The complete
-output is collected in the `*lint-output*` buffer, and any lines in the current
-file with messages will have a marker displayed next to them in the left margin.
-When the cursor moves onto a line with the problem, the associated messages will
-be displayed in a tool tip.
+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.
 
-== Commands
-
-*lint-buffer*::
-    *alias* lint +
-    Pass the entire buffer through the program named in `lintcmd`. The buffer
-    may contain unsaved changes.
-
-*lint-selections* [-command <cmd>]::
-    Pass each of the selections through `<cmd>` or, if the `-command` switch is
-    not provided, through the program named in `lintcmd`. The buffer may contain
-    unsaved changes.
-
-*lint-hide-diagnostics*::
-    Hide line markers and disable the automatic display of messages, if any.
-
-*lint-next-message*::
-    Jump to the next message generated by the last `lint-buffer` or
-    `lint-selections` command.
-
-*lint-previous-message*::
-    Jump to the previous message generated by the last `lint-buffer` or
-    `lint-selections` command.
-
-== Options
-
-*lintcmd* (str)::
-    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 described above.
-
-
-*toolsclient* (str)::
-    If set, the `:lint` command will try to display its results in the Kakoune
-    client with this name.
-    See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
+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
+line, the associated messages are displayed. If they get distracting, you can
+turn off the markers and messages with the `:lint-hide-diagnostics` command.
 
+You can also use `:lint-next-message` and `:lint-previous-message` to jump
+between the lines with messages.

From a25cc215e8065c246e61d89b883eeeb70bfad886 Mon Sep 17 00:00:00 2001
From: Tim Allen <screwtape@froup.com>
Date: Fri, 4 Sep 2020 19:20:50 +1000
Subject: [PATCH 6/6] 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 | 30 ++++++++++++++++++++++++++----
 rc/tools/doc.kak         |  2 ++
 rc/tools/lint.asciidoc   |  7 ++++---
 rc/tools/lint.kak        | 12 ++++--------
 4 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/rc/tools/autorestore.kak b/rc/tools/autorestore.kak
index a59ce850..d3e60994 100644
--- a/rc/tools/autorestore.kak
+++ b/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
 }
 
diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak
index d88dcda2..5a6c8e1d 100644
--- a/rc/tools/doc.kak
+++ b/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=$(
diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc
index 3fe7f5ad..469b1e57 100644
--- a/rc/tools/lint.asciidoc
+++ b/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
diff --git a/rc/tools/lint.kak b/rc/tools/lint.kak
index abacf8fd..c53b6b71 100644
--- a/rc/tools/lint.kak
+++ b/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 \
 %{