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] 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>>!