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

This commit is contained in:
Maxime Coste 2020-10-01 22:16:23 +10:00
commit 9401a9fd25
6 changed files with 139 additions and 15 deletions

View File

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

View File

@ -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 bool autorestore_purge_restored true
## Insert the content of the backup file into the current buffer, if a suitable one is found ## 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{ evaluate-commands %sh{
buffer_basename="${kak_buffile##*/}" buffer_basename="${kak_buffile##*/}"
buffer_dirname=$(dirname "${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 ## 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{ evaluate-commands %sh{
[ ! -f "${kak_buffile}" ] && exit [ ! -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 ## 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 remove-hooks global autorestore
} }

46
rc/tools/doc.asciidoc Normal file
View File

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

View File

@ -137,9 +137,21 @@ define-command -params 1 -hidden doc-render %{
define-command -params 1..2 \ define-command -params 1..2 \
-shell-script-candidates %{ -shell-script-candidates %{
if [ "$kak_token_to_complete" -eq 0 ]; then 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 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 if [ -f "${page}" ]; then
awk ' awk '
/^==+ +/ { sub(/^==+ +/, ""); print } /^==+ +/ { sub(/^==+ +/, ""); print }
@ -151,9 +163,18 @@ define-command -params 1..2 \
doc -docstring %{ doc -docstring %{
doc <topic> [<keyword>]: open a buffer containing documentation about a given topic 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 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{ 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 if [ -f "${page}" ]; then
jump_cmd="" jump_cmd=""
if [ $# -eq 2 ]; then if [ $# -eq 2 ]; then

26
rc/tools/lint.asciidoc Normal file
View File

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

View File

@ -2,13 +2,7 @@ declare-option \
-docstring %{ -docstring %{
The shell command used by lint-buffer and lint-selections. The shell command used by lint-buffer and lint-selections.
It will be given the path to a file containing the text to be See `:doc lint` for details.
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.
} \ } \
str lintcmd str lintcmd
@ -230,6 +224,8 @@ define-command \
Switches: Switches:
-command <cmd> Use the given linter. -command <cmd> Use the given linter.
If not given, the lintcmd option is used. If not given, the lintcmd option is used.
See `:doc lint` for details.
} \ } \
lint-selections \ lint-selections \
%{ %{
@ -275,7 +271,7 @@ define-command \
-docstring %{ -docstring %{
lint-buffer: Check the current buffer with a linter. 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 \ lint-buffer \
%{ %{