Merge remote-tracking branch 'Screwtapello/extensible-docs' into master

rc/tools/autorestore.asciidoc

@@ -0,0 +1,13 @@
+= 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.
+
+By default, backup files are deleted when restored. You can set the
+`autorestore_purge_restored` option to `false` to prevent this.
+
+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.

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.asciidoc

@@ -0,0 +1,46 @@
+= Kakoune's online documentation
+
+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
+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.
+
+== 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` 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` 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>>!

rc/tools/doc.kak

@@ -137,9 +137,21 @@ 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 -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
-            readonly page="${kak_runtime}/doc/${1}.asciidoc"
+            page=$(
+                find -L \
+                    "${kak_config}/autoload/" \
+                    "${kak_runtime}/doc/" \
+                    "${kak_runtime}/rc/" \
+                    -type f -name "$1.asciidoc" |
+                    head -1
+            )
             if [ -f "${page}" ]; then
                 awk '
                     /^==+ +/ { sub(/^==+ +/, ""); print }
@@ -151,9 +163,18 @@ 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{
-        readonly page="${kak_runtime}/doc/${1}.asciidoc"
+        page=$(
+            find -L \
+                "${kak_config}/autoload/" \
+                "${kak_runtime}/doc/" \
+                "${kak_runtime}/rc/" \
+                -type f -name "$1.asciidoc" |
+                head -1
+        )
         if [ -f "${page}" ]; then
             jump_cmd=""
             if [ $# -eq 2 ]; then

rc/tools/lint.asciidoc

@@ -0,0 +1,26 @@
+= 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 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.
+
+The `:lint-buffer` and `:lint-selections` commands will run the shell command
+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
+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.

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 \
 %{