From b63f16e7a23a9954cd62046ff40efd5f7cf4d263 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Wed, 8 Nov 2017 16:32:49 +0800 Subject: [PATCH] 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. --- doc/pages/commands.asciidoc | 11 +++--- doc/pages/options.asciidoc | 4 ++ rc/core/doc.kak | 77 ++++++++++++++++++++++++++++++------- 3 files changed, 73 insertions(+), 19 deletions(-) diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc index 588a7543..ea4bf9e5 100644 --- a/doc/pages/commands.asciidoc +++ b/doc/pages/commands.asciidoc @@ -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 <>) + expand the markup strings in *text* (See + <>) *-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] []:: *alias* decl + declare a new option, the -hidden hides the option in completion - suggestions (See <>) + suggestions (See <>) *set-option* :: *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 <>) + (See <>) *unset-option* :: *alias* unset + - unset the value of an option (See <>) + unset the value of an option (See <>) *update-option* :: update the value of an option if its type supports that operation - (See <>) + (See <>) *alias* :: define a new alias, within the context of a scope diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index 0d470b01..0398af30 100644 --- a/doc/pages/options.asciidoc +++ b/doc/pages/options.asciidoc @@ -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 <>). *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 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] [] 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: diff --git a/rc/core/doc.kak b/rc/core/doc.kak index 46e670d2..e91cc60d 100644 --- a/rc/core/doc.kak +++ b/rc/core/doc.kak @@ -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 (.*?)#,.*? + execute-keys \%s (.*?),.*? execute-keys -draft s .*,| 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]+)$ + 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* + 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}gg" + doc-parse-anchors + # Join paragraphs together try %{ execute-keys -draft \%S \n{2,}|(?<=\+)\n|^[^\n]+::\n ^-{2,}(\n|\z) S\n\z \n } # Remove some line end markers try %{ execute-keys -draft \%s \h*(\+|:{2,})$ 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(? 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 :doc-jump + map buffer normal :doc-follow-link } -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