Provide dictionaries containing default mappings

[qadzek]

Currently, the help page contains a table of the default mappings:

  MODE  LHS                 RHS ~
  ====  ===                 ===
  `n`     <leader>ww          |<plug>(wiki-index)|                 [GLOBAL]
  `n`     <leader>wn          |<plug>(wiki-open)|                  [GLOBAL]
  `n`     <leader>w<leader>w  |<plug>(wiki-journal)|               [GLOBAL]
  `n`     <leader>wx          |<plug>(wiki-reload)|                [GLOBAL]
  `n`     <leader>wgb         |<plug>(wiki-graph-find-backlinks)|
  `n`     <leader>wgr         |<plug>(wiki-graph-related)|
  `n`     <leader>wgc         |<plug>(wiki-graph-check-links)|
  `n`     <leader>wgC         |<plug>(wiki-graph-check-links-g)|
  `n`     <leader>wgO         |<plug>(wiki-graph-check-orphans)|
  `n`     <leader>wgi         |<plug>(wiki-graph-in)|
  `n`     <leader>wgo         |<plug>(wiki-graph-out)|
  `n`     <leader>wf          |<plug>(wiki-link-transform)|
  `n`     <leader>wd          |<plug>(wiki-page-delete)|
  `n`     <leader>wr          |<plug>(wiki-page-rename)|
  `n`     <leader>wt          |<plug>(wiki-page-toc)|
  `n`     <leader>wT          |<plug>(wiki-page-toc-local)|
  `n`     <leader>wp          |<plug>(wiki-export)|
  `x`     <leader>wp          |<plug>(wiki-export)|
  `n`     <leader>wll         |<plug>(wiki-link-show)|
  `n`     <leader>wlh         |<plug>(wiki-link-extract-header)|
  `n`     <leader>wli         |<plug>(wiki-link-incoming-toggle)|
  `n`     <leader>wlI         |<plug>(wiki-link-incoming-hover)|
  `n`     <leader>wsl         |<plug>(wiki-tag-list)|
  `n`     <leader>wsr         |<plug>(wiki-tag-reload)|
  `n`     <leader>wsn         |<plug>(wiki-tag-rename)|
  `n`     <leader>wss         |<plug>(wiki-tag-search)|
  `n`     <leader>wa          |<plug>(wiki-link-add)|
  `i`     <c-q>               |<plug>(wiki-link-add)|
  `n`     <tab>               |<plug>(wiki-link-next)|
  `n`     <s-tab>             |<plug>(wiki-link-prev)|
  `n`     <cr>                |<plug>(wiki-link-follow)|
  `n`     <c-w><cr>           |<plug>(wiki-link-follow-split)|
  `n`     <c-w><tab>          |<plug>(wiki-link-follow-vsplit)|
  `n`     <c-w>u              |<plug>(wiki-link-follow-tab)|
  `n`     <bs>                |<plug>(wiki-link-return)|
  `n`     gl                  |<plug>(wiki-link-transform-operator)|
  `x`     <cr>                |<plug>(wiki-link-transform-visual)|
  `ox`    au                  |<plug>(wiki-au)|
  `ox`    iu                  |<plug>(wiki-iu)|
  `ox`    at                  |<plug>(wiki-at)|
  `ox`    it                  |<plug>(wiki-it)|
  `n`     <c-p>               |<plug>(wiki-journal-prev)|          [JOURNAL]
  `n`     <c-n>               |<plug>(wiki-journal-next)|          [JOURNAL]
  `n`     <leader><c-n>       |<plug>(wiki-journal-copy-tonext)|   [JOURNAL]
  `n`     <leader>wu          |<plug>(wiki-journal-toweek)|        [JOURNAL]
  `n`     <leader>wm          |<plug>(wiki-journal-tomonth)|       [JOURNAL]

I already use <Leader>w for another plugin, so I had to convert all its occurrences to <Leader>h and added a couple of other changes:

let g:wiki_mappings_global = {
      \ '<plug>(wiki-index)':   '<Leader>hi',
      \ '<plug>(wiki-open)':    '<Leader>ho',
      \ '<plug>(wiki-journal)': '<Leader>hj',
      \ '<plug>(wiki-reload)':  '<Leader>hr',
      \ }

let g:wiki_mappings_local = {
      \ '<plug>(wiki-graph-find-backlinks)':    '<Leader>hgb',
      \ '<plug>(wiki-graph-related)':           '<Leader>hgr',
      \ '<plug>(wiki-graph-check-links)':       '<Leader>hgc',
      \ '<plug>(wiki-graph-check-links-g)':     '<Leader>hgC',
      \ '<plug>(wiki-graph-check-orphans)':     '<Leader>hgO',
      \ '<plug>(wiki-graph-in)':                '<Leader>hgi',
      \ '<plug>(wiki-graph-out)':               '<Leader>hgo',
      \ '<plug>(wiki-link-transform)':          '<Leader>hc',
      \ '<plug>(wiki-page-delete)':             '<Leader>hd',
      \ '<plug>(wiki-page-rename)':             '<Leader>hr',
      \ '<plug>(wiki-page-toc)':                '<Leader>ht',
      \ '<plug>(wiki-page-toc-local)':          '<Leader>hT',
      \ '<plug>(wiki-toc-generate)':            '<Leader>htg',
      \ '<plug>(wiki-toc-generate-local)':      '<Leader>htG',
      \ '<plug>(wiki-export)':                  '<Leader>hp',
      \ 'x_<plug>(wiki-export)':                '<Leader>hp',
      \ '<plug>(wiki-link-show)':               '<Leader>hll',
      \ '<plug>(wiki-link-extract-header)':     '<Leader>hlh',
      \ 'x_<plug>(wiki-link-extract-header)':   '<Leader>hlh',
      \ '<plug>(wiki-link-incoming-toggle)':    '<Leader>hli',
      \ '<plug>(wiki-link-incoming-hover)':     '<Leader>hlI',
      \ '<plug>(wiki-tag-list)':                '<Leader>hsl',
      \ '<plug>(wiki-tag-reload)':              '<Leader>hsr',
      \ '<plug>(wiki-tag-rename)':              '<Leader>hsn',
      \ '<plug>(wiki-tag-search)':              '<Leader>hss',
      \ '<plug>(wiki-link-add)':                '<Leader>ha',
      \ 'i_<plug>(wiki-link-add)':              '<Leader>ha',
      \ '<plug>(wiki-link-next)':               '<C-n>',
      \ '<plug>(wiki-link-prev)':               '<C-p>',
      \ '<plug>(wiki-link-follow)':             '<CR>',
      \ '<plug>(wiki-link-follow-split)':       '<C-q>s',
      \ '<plug>(wiki-link-follow-vsplit)':      '<C-q>v',
      \ '<plug>(wiki-link-follow-tab)':         '<C-q>t',
      \ '<plug>(wiki-link-return)':             '<BS>',
      \ '<plug>(wiki-link-transform-operator)': 'gl',
      \ 'x_<plug>(wiki-link-transform-visual)': '<CR>',
      \ 'ox_<plug>(wiki-au)':                   'au',
      \ 'ox_<plug>(wiki-iu)':                   'iu',
      \ 'ox_<plug>(wiki-at)':                   'at',
      \ 'ox_<plug>(wiki-it)':                   'it',
      \ }

let g:wiki_mappings_local_journal = {
      \ '<plug>(wiki-journal-prev)' :           '[j',
      \ '<plug>(wiki-journal-next)' :           ']j',
      \ '<plug>(wiki-journal-copy-tonext)':     '<leader><c-n>',
      \ '<plug>(wiki-journal-toweek)':          '<leader>wu',
      \ '<plug>(wiki-journal-tomonth)':         '<leader>wm',
      \ }

It's a bit of a hassle to convert the table to dictionaries, so I am wondering if it would be a good idea to provide dictionaries containing the default mappings in the help file? I could make a PR; it would add about 60 lines to the help file, though.

[lervag]

Good question. I can see the convenience of being able to copy the dicts from the docs and then changing it as desired. The current presentation makes it easy to quickly navigate to the relevant docs, though, which is not possible if we remove it and instead list a dictionary. So, you are probably proposing that we include both?

[lervag]

Notice, though, that you will find the dicts in the source code:

wiki.vim/autoload/wiki/buffer.vim

Lines 153 to 206 in 0dc5fff

	let l:mappings = {
	\ '<plug>(wiki-graph-find-backlinks)': '<leader>wgb',
	\ '<plug>(wiki-graph-related)': '<leader>wgr',
	\ '<plug>(wiki-graph-check-links)': '<leader>wgc',
	\ '<plug>(wiki-graph-check-links-g)': '<leader>wgC',
	\ '<plug>(wiki-graph-check-orphans)': '<leader>wgO',
	\ '<plug>(wiki-graph-in)': '<leader>wgi',
	\ '<plug>(wiki-graph-out)': '<leader>wgo',
	\ '<plug>(wiki-link-add)': '<leader>wa',
	\ 'i_<plug>(wiki-link-add)': '<c-q>',
	\ '<plug>(wiki-link-next)': '<tab>',
	\ '<plug>(wiki-link-prev)': '<s-tab>',
	\ '<plug>(wiki-link-show)': '<leader>wll',
	\ '<plug>(wiki-link-extract-header)': '<leader>wlh',
	\ 'x_<plug>(wiki-link-extract-header)': '<leader>wlh',
	\ '<plug>(wiki-link-follow)': '<cr>',
	\ '<plug>(wiki-link-follow-split)': '<c-w><cr>',
	\ '<plug>(wiki-link-follow-vsplit)': '<c-w><tab>',
	\ '<plug>(wiki-link-follow-tab)': '<c-w>u',
	\ '<plug>(wiki-link-return)': '<bs>',
	\ '<plug>(wiki-link-transform)': '<leader>wf',
	\ '<plug>(wiki-link-transform-operator)': 'gl',
	\ '<plug>(wiki-link-incoming-toggle)': '<leader>wli',
	\ '<plug>(wiki-link-incoming-hover)': '<leader>wlI',
	\ '<plug>(wiki-page-delete)': '<leader>wd',
	\ '<plug>(wiki-page-rename)': '<leader>wr',
	\ '<plug>(wiki-page-rename-section)': '<f2>',
	\ '<plug>(wiki-toc-generate)': '<leader>wt',
	\ '<plug>(wiki-toc-generate-local)': '<leader>wT',
	\ '<plug>(wiki-export)': '<leader>wp',
	\ 'x_<plug>(wiki-export)': '<leader>wp',
	\ '<plug>(wiki-tag-list)': '<leader>wsl',
	\ '<plug>(wiki-tag-reload)': '<leader>wsr',
	\ '<plug>(wiki-tag-search)': '<leader>wss',
	\ '<plug>(wiki-tag-rename)': '<leader>wsn',
	\ 'x_<plug>(wiki-link-transform-visual)': '<cr>',
	\ 'o_<plug>(wiki-au)': 'au',
	\ 'x_<plug>(wiki-au)': 'au',
	\ 'o_<plug>(wiki-iu)': 'iu',
	\ 'x_<plug>(wiki-iu)': 'iu',
	\ 'o_<plug>(wiki-at)': 'at',
	\ 'x_<plug>(wiki-at)': 'at',
	\ 'o_<plug>(wiki-it)': 'it',
	\ 'x_<plug>(wiki-it)': 'it',
	\}
	if b:wiki.in_journal
	call extend(l:mappings, {
	\ '<plug>(wiki-journal-prev)': '<c-p>',
	\ '<plug>(wiki-journal-next)': '<c-n>',
	\ '<plug>(wiki-journal-copy-tonext)': '<leader><c-n>',
	\ '<plug>(wiki-journal-toweek)': '<leader>wu',
	\ '<plug>(wiki-journal-tomonth)': '<leader>wm',
	\})

wiki.vim/plugin/wiki.vim

Lines 165 to 170 in 0dc5fff

	\ ? {
	\ '<plug>(wiki-index)': '<leader>ww',
	\ '<plug>(wiki-open)': '<leader>wn',
	\ '<plug>(wiki-journal)': '<leader>w<leader>w',
	\ '<plug>(wiki-reload)': '<leader>wx',
	\} : {}

Perhaps another alternative may be to instead give links to these locations in the docs?

[qadzek]

So, you are probably proposing that we include both?

Indeed. The current table provides a clear overview, but the dictionaries would be helpful too, so a new user can just copy them.

Notice, though, that you will find the dicts in the source code:

I should have thought of that.

Perhaps another alternative may be to instead give links to these locations in the docs?

That might be the best solution, as it avoids the help file from getting too long.

[lervag]

Notice, though, that you will find the dicts in the source code:

I should have thought of that.

Well, I guess it is not really obvious that the main source would first create the dictionaries.

Perhaps another alternative may be to instead give links to these locations in the docs?

That might be the best solution, as it avoids the help file from getting too long.

Yes; one challenge here is that a link to the file and line number in the master branch is "volatile". That is, the precise line number may change over time. So, I suggest adding the following paragraph just before the table starts:

For those who want to adjust the mappings, it may be useful to know that the
default maps are available in a dictionary format compatible with the above
mentioned configuration options. The global mappings are defined in the
wiki.vim source code in `plugin/wiki.vim` (somewhere near line 165), whereas
the buffer mappings are defined in `autoload/wiki/buffer.vim` (close to line
155).

[qadzek]

So, I suggest adding the following paragraph

That seems like a good solution. Even if the line numbers aren't accurate, being pointed to the correct files should make it trivial to find the dictionaries.

Mentioning the variable names s:mappings and l:mappings could be an alternative to the line numbers.

[lervag]

Thanks; I've pushed an update for this now. Let me know if you think I somehow missed something.