doc.kak: Support anchors and internal links
Underline links, support jumping to a specific anchor either in the current page or another one, use those new features in some pages.
This commit is contained in:
Maxime Coste
parent
1fe9db3c30
commit
b63f16e7a2
|
|
@ -82,7 +82,8 @@ command *q!* has to be used). Aliases are mentionned below each commands.
|
|||
show *text* in status line, with the following *options*:
|
||||
|
||||
*-markup*:::
|
||||
expand the markup strings in *text* (See <<expansions#,`:doc expansions`>>)
|
||||
expand the markup strings in *text* (See
|
||||
<<expansions#Markup strings,`:doc expansions 'Markup strings'`>>)
|
||||
|
||||
*-debug*:::
|
||||
print the given text to the *\*debug** buffer
|
||||
|
|
@ -96,7 +97,7 @@ command *q!* has to be used). Aliases are mentionned below each commands.
|
|||
*declare-option* [-hidden] <type> <name> [<value>]::
|
||||
*alias* decl +
|
||||
declare a new option, the -hidden hides the option in completion
|
||||
suggestions (See <<options#,`:doc options`>>)
|
||||
suggestions (See <<options#declare-option,`:doc options declare-option`>>)
|
||||
|
||||
*set-option* <scope> <name> <value>::
|
||||
*alias* set +
|
||||
|
|
@ -105,15 +106,15 @@ command *q!* has to be used). Aliases are mentionned below each commands.
|
|||
target *scope* is 'buffer', e.g. set buffer=/path/to/buffer foo "bar";
|
||||
the scope can also take the `current` special value, which will automatically
|
||||
point to the narrowest scope available in the current context
|
||||
(See <<options#,`:doc options`>>)
|
||||
(See <<options#set-option,`:doc options set-option`>>)
|
||||
|
||||
*unset-option* <scope> <name>::
|
||||
*alias* unset +
|
||||
unset the value of an option (See <<options#,`:doc options`>>)
|
||||
unset the value of an option (See <<options#unset-option,`:doc options unset-option`>>)
|
||||
|
||||
*update-option* <scope> <name>::
|
||||
update the value of an option if its type supports that operation
|
||||
(See <<options#,`:doc options`>>)
|
||||
(See <<options#update-option,`:doc options update-option`>>)
|
||||
|
||||
*alias* <scope> <name> <command>::
|
||||
define a new alias, within the context of a scope
|
||||
|
|
|
|||
|
|
@ -6,6 +6,7 @@ Kakoune can store named and typed values that can be used both to
|
|||
customize the core editor behaviour, and to store data used by extension
|
||||
scripts.
|
||||
|
||||
[[set-option]]
|
||||
Options can be modified using the `set-option` command:
|
||||
|
||||
---------------------------------
|
||||
|
|
@ -16,6 +17,7 @@ set-option <scope> <name> <value>
|
|||
<<scopes#,`:doc scopes`>>). *current* relate to the narrowest scope in
|
||||
which the option is already set.
|
||||
|
||||
[[unset-option]]
|
||||
Options values can be unset in a specific scope with the `unset-option`
|
||||
command:
|
||||
|
||||
|
|
@ -26,6 +28,7 @@ unset-option <scope> <name>
|
|||
Unsetting an option will make it fallback to the value of its parent mode,
|
||||
hence options cannot be unset from the *global* scope.
|
||||
|
||||
[[declare-option]]
|
||||
New options can be declared using the `declare-option` command:
|
||||
|
||||
------------------------------------------------
|
||||
|
|
@ -35,6 +38,7 @@ declare-option [-hidden] <type> <name> [<value>]
|
|||
If `-hidden` is specified, the option will not be displayed in completion
|
||||
suggestions.
|
||||
|
||||
[[update-option]]
|
||||
Certain option type can be *updated*, usually to match potential changes
|
||||
in the buffer they relate to. This can be triggered by the `update-option`
|
||||
command:
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
declare-option -docstring "name of the client in which documentation is to be displayed" \
|
||||
str docsclient
|
||||
|
||||
declare-option -hidden range-specs doc_ranges
|
||||
declare-option -hidden range-specs doc_render_ranges
|
||||
declare-option -hidden range-specs doc_render_links
|
||||
declare-option -hidden range-specs doc_links
|
||||
declare-option -hidden range-specs doc_anchors
|
||||
|
||||
define-command -hidden -params 4 doc-render-regex %{
|
||||
evaluate-commands -draft %{ try %{
|
||||
|
|
@ -11,34 +13,74 @@ define-command -hidden -params 4 doc-render-regex %{
|
|||
execute-keys "%arg{3}"
|
||||
%sh{
|
||||
ranges=$(echo "$kak_selections_desc" | sed -e "s/:/|$4:/g; s/\$/|$4/")
|
||||
echo "update-option buffer doc_ranges"
|
||||
echo "set-option -add buffer doc_ranges '$ranges'"
|
||||
echo "update-option buffer doc_render_ranges"
|
||||
echo "set-option -add buffer doc_render_ranges '$ranges'"
|
||||
}
|
||||
} }
|
||||
}
|
||||
|
||||
define-command -hidden doc-parse-links %{
|
||||
evaluate-commands -draft %{ try %{
|
||||
execute-keys \%s <lt><lt>(.*?)#,.*?<gt><gt> <ret>
|
||||
execute-keys \%s <lt><lt>(.*?),.*?<gt><gt> <ret>
|
||||
execute-keys -draft s <lt><lt>.*,|<gt><gt> <ret> d
|
||||
execute-keys H
|
||||
set-option buffer doc_links %val{timestamp}
|
||||
set-option buffer doc_render_links %val{timestamp}
|
||||
evaluate-commands -itersel %{
|
||||
set-option -add buffer doc_links "%val{selection_desc}|%reg{1}"
|
||||
set-option -add buffer doc_render_links "%val{selection_desc}|default+u"
|
||||
}
|
||||
} }
|
||||
}
|
||||
|
||||
define-command doc-jump %{
|
||||
define-command -hidden doc-parse-anchors %{
|
||||
evaluate-commands -draft %{ try %{
|
||||
set-option buffer doc_anchors %val{timestamp}
|
||||
# Find sections as add them as imlicit anchors
|
||||
execute-keys \%s ^={2,}\h+([^\n]+)$ <ret>
|
||||
evaluate-commands -itersel %{
|
||||
set-option -add buffer doc_anchors "%val{selection_desc}|%reg{1}"
|
||||
}
|
||||
|
||||
# Parse explicit anchors and remove their text
|
||||
execute-keys \%s \[\[(.*?)\]\]\s* <ret>
|
||||
evaluate-commands -itersel %{
|
||||
set-option -add buffer doc_anchors "%val{selection_desc}|%reg{1}"
|
||||
}
|
||||
execute-keys d
|
||||
update-option buffer doc_anchors
|
||||
} }
|
||||
}
|
||||
|
||||
define-command doc-jump-to-anchor -params 1 %{
|
||||
update-option buffer doc_anchors
|
||||
%sh{
|
||||
range=$(printf "%s" "$kak_opt_doc_anchors" | tr ':' '\n' | grep "$1" | head -n1)
|
||||
if [ -n "$range" ]; then
|
||||
printf '%s\n' "select '${range%|*}'; execute-keys vv"
|
||||
else
|
||||
printf '%s\n' "echo -markup %{{Error}No such anchor '$1'}"
|
||||
fi
|
||||
}
|
||||
}
|
||||
|
||||
define-command doc-follow-link %{
|
||||
update-option buffer doc_links
|
||||
%sh{
|
||||
printf "%s" "$kak_opt_doc_links" | awk -v RS=':' -v FS='[.,|]' '
|
||||
printf "%s" "$kak_opt_doc_links" | awk -v RS=':' -v FS='[.,|#]' '
|
||||
BEGIN {
|
||||
l=ENVIRON["kak_cursor_line"];
|
||||
c=ENVIRON["kak_cursor_column"];
|
||||
}
|
||||
l >= $1 && c >= $2 && l <= $3 && c <= $4 {
|
||||
print "doc " $5
|
||||
if (NF == 6) {
|
||||
print "doc " $5
|
||||
if ($6 != "") {
|
||||
print "doc-jump-to-anchor %{" $6 "}"
|
||||
}
|
||||
} else {
|
||||
print "doc-jump-to-anchor %{" $5 "}"
|
||||
}
|
||||
exit
|
||||
}
|
||||
'
|
||||
|
|
@ -46,35 +88,39 @@ define-command doc-jump %{
|
|||
}
|
||||
|
||||
define-command -params 1 -hidden doc-render %{
|
||||
edit! -scratch *doc*
|
||||
edit! -scratch "*doc-%sh{basename $1 .asciidoc}*"
|
||||
execute-keys "!cat %arg{1}<ret>gg"
|
||||
|
||||
doc-parse-anchors
|
||||
|
||||
# Join paragraphs together
|
||||
try %{ execute-keys -draft \%S \n{2,}|(?<=\+)\n|^[^\n]+::\n <ret> <a-K>^-{2,}(\n|\z)<ret> S\n\z<ret> <a-k>\n<ret> <a-j> }
|
||||
|
||||
# Remove some line end markers
|
||||
try %{ execute-keys -draft \%s \h*(\+|:{2,})$ <ret> d }
|
||||
|
||||
# Setup the doc_ranges option
|
||||
set-option buffer doc_ranges %val{timestamp}
|
||||
# Setup the doc_render_ranges option
|
||||
set-option buffer doc_render_ranges %val{timestamp}
|
||||
doc-render-regex \B(?<!\\)\*[^\n]+?(?<!\\)\*\B \A|.\z 'H' default+b
|
||||
doc-render-regex \b(?<!\\)_[^\n]+?(?<!\\)_\b \A|.\z 'H' default+i
|
||||
doc-render-regex \B(?<!\\)`[^\n]+?(?<!\\)`\B \A|.\z 'H' mono
|
||||
doc-render-regex ^=\h+[^\n]+ ^=\h+ '~' title
|
||||
doc-render-regex ^={2,}\h+[^\n]+ ^={2,}\h+ '' header
|
||||
doc-render-regex ^-{2,}\n.*?^-{2,}\n ^-{2,}\n '' block
|
||||
|
||||
doc-parse-links
|
||||
|
||||
# Remove escaping of * and `
|
||||
try %{ execute-keys -draft \%s \\((?=\*)|(?=`)) <ret> d }
|
||||
|
||||
set-option buffer readonly true
|
||||
add-highlighter buffer ranges doc_ranges
|
||||
add-highlighter buffer ranges doc_render_ranges
|
||||
add-highlighter buffer ranges doc_render_links
|
||||
add-highlighter buffer wrap -word -indent
|
||||
map buffer normal <ret> :doc-jump<ret>
|
||||
map buffer normal <ret> :doc-follow-link<ret>
|
||||
}
|
||||
|
||||
define-command -params 1 \
|
||||
define-command -params 1..2 \
|
||||
-shell-candidates %{
|
||||
find "${kak_runtime}/doc/" -type f -name "*.asciidoc" | sed 's,.*/,,; s/\.[^/]*$//'
|
||||
} \
|
||||
|
|
@ -83,7 +129,10 @@ An optional keyword argument can be passed to the function, which will be automa
|
|||
%sh{
|
||||
readonly page="${kak_runtime}/doc/${1}.asciidoc"
|
||||
if [ -f "${page}" ]; then
|
||||
printf %s\\n "evaluate-commands -try-client %opt{docsclient} doc-render ${page}"
|
||||
if [ $# -eq 2 ]; then
|
||||
jump_cmd="doc-jump-to-anchor '$2'"
|
||||
fi
|
||||
printf %s\\n "evaluate-commands -try-client %opt{docsclient} %{ doc-render ${page}; ${jump_cmd} }"
|
||||
else
|
||||
printf %s\\n "echo -markup '{Error}No such doc file: ${page}'"
|
||||
fi
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user