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

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

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 <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:

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 "update-option buffer doc_render_ranges"
-            echo "set-option -add buffer doc_ranges '$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 {
+                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
+    # Setup the doc_render_ranges option
-    set-option buffer doc_ranges %val{timestamp}
+    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