kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

doc.kak (6685B)


      1 declare-option -docstring "name of the client in which documentation is to be displayed" \
      2     str docsclient
      3 
      4 declare-option -hidden range-specs doc_render_ranges
      5 declare-option -hidden range-specs doc_links
      6 declare-option -hidden range-specs doc_anchors
      7 
      8 define-command -hidden -params 4 doc-render-regex %{
      9     evaluate-commands -draft %{ try %{
     10         execute-keys <percent> s %arg{1} <ret>
     11         execute-keys -draft s %arg{2} <ret> d
     12         execute-keys "%arg{3}"
     13         evaluate-commands %sh{
     14             face="$4"
     15             eval "set -- $kak_quoted_selections_desc"
     16             ranges=""
     17             for desc in "$@"; do ranges="$ranges '$desc|$face'"; done
     18             echo "update-option buffer doc_render_ranges"
     19             echo "set-option -add buffer doc_render_ranges $ranges"
     20         }
     21     } }
     22 }
     23 
     24 define-command -hidden doc-parse-links %{
     25     evaluate-commands -draft %{ try %{
     26         execute-keys <percent> s <lt><lt>(.*?),.*?<gt><gt> <ret>
     27         execute-keys -draft s <lt><lt>.*,|<gt><gt> <ret> d
     28         execute-keys H
     29         set-option buffer doc_links %val{timestamp}
     30         update-option buffer doc_render_ranges
     31         evaluate-commands -itersel %{
     32             set-option -add buffer doc_links "%val{selection_desc}|%reg{1}"
     33             set-option -add buffer doc_render_ranges "%val{selection_desc}|default+u"
     34         }
     35     } }
     36 }
     37 
     38 define-command -hidden doc-parse-anchors %{
     39     evaluate-commands -draft %{ try %{
     40         set-option buffer doc_anchors %val{timestamp}
     41         # Find sections as add them as imlicit anchors
     42         execute-keys <percent> s ^={2,}\h+(\N+)$ <ret>
     43         evaluate-commands -itersel %{
     44             set-option -add buffer doc_anchors "%val{selection_desc}|%sh{printf '%s' ""$kak_main_reg_1"" | tr '[A-Z ]' '[a-z-]'}"
     45         }
     46 
     47         # Parse explicit anchors and remove their text
     48         execute-keys <percent> s \[\[(.*?)\]\]\s* <ret>
     49         evaluate-commands -itersel %{
     50             set-option -add buffer doc_anchors "%val{selection_desc}|%reg{1}"
     51         }
     52         execute-keys d
     53         update-option buffer doc_anchors
     54     } }
     55 }
     56 
     57 define-command -hidden doc-jump-to-anchor -params 1 %{
     58     update-option buffer doc_anchors
     59     evaluate-commands %sh{
     60         anchor="$1"
     61         eval "set -- $kak_quoted_opt_doc_anchors"
     62 
     63         shift
     64         for range in "$@"; do
     65             if [ "${range#*|}" = "$anchor" ]; then
     66                 printf '%s\n'  "select '${range%|*}'; execute-keys vv"
     67                 exit
     68             fi
     69         done
     70         printf "fail No such anchor '%s'\n" "${anchor}"
     71     }
     72 }
     73 
     74 define-command -hidden doc-follow-link %{
     75     update-option buffer doc_links
     76     evaluate-commands %sh{
     77         eval "set -- $kak_quoted_opt_doc_links"
     78         for link in "$@"; do
     79             printf '%s\n' "$link"
     80         done | awk -v FS='[.,|#]' '
     81             BEGIN {
     82                 l=ENVIRON["kak_cursor_line"];
     83                 c=ENVIRON["kak_cursor_column"];
     84             }
     85             l >= $1 && c >= $2 && l <= $3 && c <= $4 {
     86                 if (NF == 6) {
     87                     print "doc " $5
     88                     if ($6 != "") {
     89                         print "doc-jump-to-anchor %{" $6 "}"
     90                     }
     91                 } else {
     92                     print "doc-jump-to-anchor %{" $5 "}"
     93                 }
     94                 exit
     95             }
     96         '
     97     }
     98 }
     99 
    100 define-command -params 1 -hidden doc-render %{
    101     edit! -scratch "*doc-%sh{basename $1 .asciidoc}*"
    102     execute-keys "!cat '%arg{1}'<ret>gg"
    103 
    104     doc-parse-anchors
    105 
    106     # Join paragraphs together
    107     try %{
    108         execute-keys -draft '%S\n{2,}|(?<lt>=\+)\n|^\N+::\n|^\h*[*-]\h+<ret>' \
    109             <a-K>^\h*-{2,}(\n|\z)<ret> S\n\z<ret> <a-k>\n<ret> <a-j>
    110     }
    111 
    112     # Remove some line end markers
    113     try %{ execute-keys -draft <percent> s \h*(\+|:{2,})$ <ret> d }
    114 
    115     # Setup the doc_render_ranges option
    116     set-option buffer doc_render_ranges %val{timestamp}
    117     doc-render-regex \B(?<!\\)\*(?=\S)\N+?(?<=\S)(?<!\\)\*\B \A|.\z 'H' default+b
    118     doc-render-regex \b(?<!\\)_(?=\S)\N+?(?<=\S)(?<!\\)_\b \A|.\z 'H' default+i
    119     doc-render-regex \B(?<!\\)`(?=\S)\N+?(?<=\S)`\B \A|.\z 'H' mono
    120     doc-render-regex ^=\h+\N+ ^=\h+ '~' title
    121     doc-render-regex ^={2,}\h+\N+ ^={2,}\h+ '' header
    122     doc-render-regex ^\h*-{2,}\n\h*.*?^\h*-{2,}\n ^\h*-{2,}\n '' block
    123 
    124     doc-parse-links
    125 
    126     # Remove escaping of * and `
    127     try %{ execute-keys -draft <percent> s \\((?=\*)|(?=`)) <ret> d }
    128     # Go to beginning of file
    129     execute-keys 'gg'
    130 
    131     set-option buffer readonly true
    132     add-highlighter buffer/ ranges doc_render_ranges
    133     add-highlighter buffer/ wrap -word -indent
    134     map buffer normal <ret> :doc-follow-link<ret>
    135 }
    136 
    137 define-command doc -params 0..2 -docstring %{
    138         doc <topic> [<keyword>]: open a buffer containing documentation about a given topic
    139         An optional keyword argument can be passed to the function, which will be automatically selected in the documentation
    140 
    141         See `:doc doc` for details.
    142     } %{
    143     evaluate-commands %sh{
    144         topic="doc"
    145         if [ $# -ge 1 ]; then
    146             topic="$1"
    147         fi
    148         page=$(
    149             find -L \
    150                 "${kak_config}/autoload/" \
    151                 "${kak_runtime}/doc/" \
    152                 "${kak_runtime}/rc/" \
    153                 -type f -name "$topic.asciidoc" 2>/dev/null |
    154                 head -1
    155         )
    156         if [ -f "${page}" ]; then
    157             jump_cmd=""
    158             if [ $# -eq 2 ]; then
    159                 jump_cmd="doc-jump-to-anchor '$2'"
    160             fi
    161             printf %s\\n "evaluate-commands -try-client %opt{docsclient} %{ doc-render ${page}; ${jump_cmd} }"
    162         else
    163             printf 'fail No such doc file: %s\n' "$topic.asciidoc"
    164         fi
    165     }
    166 }
    167 
    168 complete-command -menu doc shell-script-candidates %{
    169     case "$kak_token_to_complete" in
    170         0)
    171             find -L \
    172                 "${kak_config}/autoload/" \
    173                 "${kak_runtime}/doc/" \
    174                 "${kak_runtime}/rc/" \
    175                 -type f -name "*.asciidoc" 2>/dev/null |
    176                 sed 's,.*/,,; s/\.[^.]*$//';;
    177         1)
    178             page=$(
    179                 find -L \
    180                     "${kak_config}/autoload/" \
    181                     "${kak_runtime}/doc/" \
    182                     "${kak_runtime}/rc/" \
    183                     -type f -name "$1.asciidoc" 2>/dev/null |
    184                     head -1
    185             )
    186             if [ -f "${page}" ]; then
    187                 awk '
    188                     /^==+ +/ { sub(/^==+ +/, ""); print }
    189                     /^\[\[[^\]]+\]\]/ { sub(/^\[\[/, ""); sub(/\]\].*/, ""); print }
    190                 ' < $page | tr '[A-Z ]' '[a-z-]'
    191             fi;;
    192     esac | sort
    193 }
    194 
    195 alias global help doc