Merge remote-tracking branch 'Screwtapello/extensible-docs' into master
This commit is contained in:
commit
9401a9fd25
13
rc/tools/autorestore.asciidoc
Normal file
13
rc/tools/autorestore.asciidoc
Normal 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.
|
|
@ -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
46
rc/tools/doc.asciidoc
Normal 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>>!
|
|
@ -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
26
rc/tools/lint.asciidoc
Normal 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.
|
|
@ -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 \
|
||||||
%{
|
%{
|
||||||
|
|
Loading…
Reference in New Issue
Block a user