diff --git a/rc/tools/autorestore.asciidoc b/rc/tools/autorestore.asciidoc new file mode 100644 index 00000000..528fcf5c --- /dev/null +++ b/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. 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.asciidoc b/rc/tools/doc.asciidoc new file mode 100644 index 00000000..407260a6 --- /dev/null +++ b/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, <>. 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 <>. +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 <>! diff --git a/rc/tools/doc.kak b/rc/tools/doc.kak index 6e0cf74e..5a6c8e1d 100644 --- a/rc/tools/doc.kak +++ b/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 []: 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 diff --git a/rc/tools/lint.asciidoc b/rc/tools/lint.asciidoc new file mode 100644 index 00000000..469b1e57 --- /dev/null +++ b/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. 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 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 \ %{