Update the doc and make some fixes regarding anchors

Solve #10

autoload/vimwiki/base.vim

@@ -663,7 +663,8 @@ function! vimwiki#base#get_links(pat) "{{{ return string-list for files
   return globlinks
 endfunction "}}}
 
-function! s:jump_to_anchor(anchor)
+" s:jump_to_anchor
+function! s:jump_to_anchor(anchor) "{{{
   let oldpos = getpos('.')
   call cursor(1, 1)
 
@@ -684,7 +685,7 @@ function! s:jump_to_anchor(anchor)
     endif
     let oldpos = getpos('.')
   endfor
-endfunction
+endfunction "}}}
 
 " vimwiki#base#edit_file
 function! vimwiki#base#edit_file(command, filename, anchor, ...) "{{{
@@ -947,8 +948,6 @@ function! vimwiki#base#nested_syntax(filetype, start, end, textSnipHl) abort "{{
   endif
 endfunction "}}}
 
-" }}}
-
 " WIKI link following functions {{{
 " vimwiki#base#find_next_link
 function! vimwiki#base#find_next_link() "{{{
@@ -1487,38 +1486,45 @@ function! vimwiki#base#RemoveHeaderLevel() "{{{
   endif
 endfunction " }}}
 
-"creates or updates TOC in current file
+" a:create == 1: creates or updates TOC in current file
-function! vimwiki#base#table_of_contents()
+" a:create == 0: update if TOC exists
-  let old_cursor_pos = getpos('.')
+function! vimwiki#base#table_of_contents(create)
-  let bullet = vimwiki#lst#default_symbol().' '
-  let rx_bullet = vimwiki#u#escape(bullet)
-  let toc_line = 0
-  let whitespaces = ''
 
-  " delete old TOC
+  " look for existing TOC
   let toc_header = '^\s*'.substitute(g:vimwiki_rxH1_Template, '__Header__',
-        \ '\='."'".g:vimwiki_toc_string."'", '').'\s*$'
+        \ '\='."'".g:vimwiki_toc_header."'", '').'\s*$'
+  let toc_line = 0
   let lnum = 1
   while lnum <= &modelines + 2 && lnum <= line('$')
-    let line_content = getline(lnum)
+    if getline(lnum) =~# toc_header
-    if line_content =~# toc_header
+      let toc_line = lnum
-      let toc_line = lnum - 1
-      let whitespaces = matchstr(line_content, '^\s*')
-      let tl = lnum
-      while 1
-        let tl += 1
-        if tl > line('$') || getline(tl) !~ '^\s*'.rx_bullet.g:vimwiki_rxWikiLink.'\s*$'
-          silent exe lnum.','.string(tl-1).'delete _'
-          break
-        endif
-      endwhile
       break
     endif
     let lnum += 1
   endwhile
 
+  if !a:create && toc_line <= 0
+    return
+  endif
+
+  let old_cursor_pos = getpos('.')
+  let bullet = vimwiki#lst#default_symbol().' '
+  let rx_bullet = vimwiki#u#escape(bullet)
+  let whitespaces = matchstr(getline(toc_line), '^\s*')
+
+  " delete old TOC
+  if toc_line > 0
+    let endoftoc = toc_line+1
+    while endoftoc <= line('$') && getline(endoftoc) =~ '^\s*'.rx_bullet.g:vimwiki_rxWikiLink.'\s*$'
+      let endoftoc += 1
+    endwhile
+    silent exe toc_line.','.string(endoftoc-1).'delete _'
+  else
+    let toc_line = 1
+  endif
+
   " collect new headers
-  let toc_lines = []
+  let headers = []
   let headers_levels = [['', 0], ['', 0], ['', 0], ['', 0], ['', 0], ['', 0]]
   for lnum in range(1, line('$'))
     let line_content = getline(lnum)
@@ -1546,17 +1552,16 @@ function! vimwiki#base#table_of_contents()
       let h_text = h_number.' '.h_text
     endif
 
-    call add(toc_lines, [h_level, h_complete_id, h_text])
+    call add(headers, [h_level, h_complete_id, h_text])
   endfor
 
   " write new TOC
-  call append(toc_line, whitespaces . substitute(g:vimwiki_rxH1_Template,
+  call append(toc_line-1, whitespaces . substitute(g:vimwiki_rxH1_Template,
-        \ '__Header__', '\='."'".g:vimwiki_toc_string."'", ''))
+        \ '__Header__', '\='."'".g:vimwiki_toc_header."'", ''))
-  let toc_line += 1
 
   let startindent = repeat(' ', vimwiki#lst#get_list_margin())
   let indentstring = repeat(' ', &shiftwidth)
-  for [lvl, link, desc] in toc_lines
+  for [lvl, link, desc] in headers
     let esc_link = substitute(link, "'", "''", 'g')
     let esc_desc = substitute(desc, "'", "''", 'g')
     let link = substitute(g:vimwiki_WikiLinkTemplate2, '__LinkUrl__',

autoload/vimwiki/html.vim

@@ -961,7 +961,7 @@ function! s:process_tag_h(line, id) "{{{
     let h_id = s:safe_html_anchor(h_text)
     let centered = (a:line =~ '^\s')
 
-    if h_text != g:vimwiki_toc_string
+    if h_text != g:vimwiki_toc_header
 
       let a:id[h_level-1] = [h_text, a:id[h_level-1][1]+1]
 
@@ -1325,6 +1325,11 @@ endfunction " }}}
 
 function! vimwiki#html#Wiki2HTML(path_html, wikifile) "{{{
 
+  if VimwikiGet('auto_toc') >= 1
+    call vimwiki#base#table_of_contents(0)
+    noautocmd update
+  endif
+
   let starttime = reltime()  " start the clock
 
   let done = 0

doc/vimwiki.txt

@@ -698,6 +698,9 @@ il                      A single list item.
     Open previous day diary link if available.
     Mapped to <C-Up>.
 
+*:VimwikiTOC*
+    Create or update the Table of Contents for the current wiki file.
+    See |vimwiki-toc|
 
 ==============================================================================
 5. Wiki syntax                                                *vimwiki-syntax*
@@ -1256,24 +1259,6 @@ To turn folding on/off check |g:vimwiki_folding|.
 ==============================================================================
 7. Placeholders                                         *vimwiki-placeholders*
 
-------------------------------------------------------------------------------
-%toc Table of Contents               *vimwiki-toc* *vimwiki-table-of-contents*
-
-You can add 'table of contents' to your HTML page generated from wiki one.
-Just place >
-
-%toc
-
-into your wiki page.
-You can also add a caption to your 'toc': >
-
-%toc Table of Contents
-
-or >
-
-%toc Whatever
-
-
 ------------------------------------------------------------------------------
 %title Title of the page                                       *vimwiki-title*
 
@@ -1614,6 +1599,29 @@ If you don't feel like typing the whole stuff, type just [[Todo# and then
 For jumping inside a single file, you can omit the file in the link: >
   [[#pay rise]]
 
+
+------------------------------------------------------------------------------
+Table of Contents                    *vimwiki-toc* *vimwiki-table-of-contents*
+
+You can add  a 'table of contents' to your wiki file.
+Use the commando |:VimwikiTOC| to create the magic header >
+  = Contents =
+at the top of your file and create a list of all the headers in the current
+file as links, so you can directly jump to specific parts of the file.
+
+For the indentation, the value of *vimwiki-option-list_margin* is used.
+
+If you don't want the TOC so sit in the very first line, e.g. if you have a
+modeline there, put the magic header in the second or third line and run
+:VimwikiTOC to update the TOC.
+
+If your language is not english, set the option |g:vimwiki_toc_header| to your
+favorite translation.
+
+If you want to keep the TOC up to date automatically, use the option
+|vimwiki-option-auto_toc|.
+
+
 ==============================================================================
 12. Options                                                  *vimwiki-options*
 
@@ -1741,6 +1749,21 @@ corresponding wiki page is saved: >
 
 This will keep your HTML files up to date.
 
+
+*vimwiki-option-auto_toc*
+------------------------------------------------------------------------------
+Set this option to a value greater than 0 to automatically update the Table of
+Contents: >
+  let g:vimwiki_list = [{'path': '~/my_site/', 'auto_toc': 1}]
+
+Value           Description~
+0               Don't update it automatically.
+1               Update when the wiki file is converted to HTML.
+2               Update when the wiki file is saved.
+
+Default: 0
+
+
 *vimwiki-option-index*
 ------------------------------------------------------------------------------
 Key             Default value~
@@ -2005,11 +2028,11 @@ list_margin       -1
 Description~
 Width of left-hand margin for lists.  When negative, the current |shiftwidth|
 is used.  This affects the appearance of the generated links (see
-|:VimwikiGenerateLinks|) and the behavior of the list manipulation commands
+|:VimwikiGenerateLinks|), the Table of contents (|vimwiki-toc|) and the
-|:VimwikiListChangeLevel| and the local mappings |vimwiki_glstar|,
+behavior of the list manipulation commands |:VimwikiListChangeLevel| and the
-|vimwiki_gl#| |vimwiki_gl-|, |vimwiki_gl.|, |vimwiki_gl-|, |vimwiki_gl1|,
+local mappings |vimwiki_glstar|, |vimwiki_gl#| |vimwiki_gl-|, |vimwiki_gl.|,
-|vimwiki_gla|, |vimwiki_glA|, |vimwiki_gli|, |vimwiki_glI| and
+|vimwiki_gl-|, |vimwiki_gl1|, |vimwiki_gla|, |vimwiki_glA|, |vimwiki_gli|,
-|vimwiki_i_<C-L>_<C-M>|.
+|vimwiki_glI| and |vimwiki_i_<C-L>_<C-M>|.
 
 Note: if you use MediaWiki syntax, you probably would like to set this option
 to 0, because every indented line is considered verbatim text.
@@ -2023,7 +2046,7 @@ Global options are configured using the following pattern: >
     let g:option_name = option_value
 
 
------------------------------------------------------------------------------
+------------------------------------------------------------------------------
 *g:vimwiki_hl_headers*
 
 Highlight headers with =Reddish=, ==Greenish==, ===Blueish=== colors.
@@ -2241,7 +2264,7 @@ similar to 'local:' and 'file:' schemes, but are always opened with Vim: >
   endfunction " }}}
 
 
------------------------------------------------------------------------------
+------------------------------------------------------------------------------
 *VimwikiWikiIncludeHandler*
 
 Vimwiki includes the contents of a wiki-include URL as an image by default.
@@ -2518,6 +2541,15 @@ let g:vimwiki_diary_months = {
       \ 10: 'October', 11: 'November', 12: 'December'
       \ }
 
+------------------------------------------------------------------------------
+*g:vimwiki_toc_header*
+
+A string with the magic header that tells vimwiki where the Table of Contents
+is located in the file. You can change it to the appropriate word in your
+mother tongue like this: >
+  let g:vimwiki_toc_header = 'Inhalt'
+
+The default is 'Contents'.
 
 ==============================================================================
 13. Help                                                        *vimwiki-help*
@@ -2547,6 +2579,14 @@ Vim plugins: http://www.vim.org/scripts/script.php?script_id=2226
 
 ???~
 
+    * Support for anchors, see |vimwiki-anchors|
+        * in this context, add support for TOC, see |vimwiki-toc|
+        * remove the now useless %toc placeholder
+        * add omni completion of wiki links (files and anchors)
+        * the function base#resolve_scheme() now also returns the anchor
+          (important for custom VimwikiLinkHandlers)
+        * new local option |vimwiki-option-auto_toc|
+        * new global option |g:vimwiki_toc_header|
     * List editing capabilities, see |vimwiki-lists|:
         * support for auto incrementing numbered lists
         * more key maps for list manipulation, see |vimwiki-list-manipulation|

ftplugin/vimwiki.vim

@@ -286,20 +286,20 @@ endfunction "}}}
 
 " COMMANDS {{{
 command! -buffer Vimwiki2HTML
-      \ silent w <bar> 
+      \ silent noautocmd w <bar>
       \ let res = vimwiki#html#Wiki2HTML(expand(VimwikiGet('path_html')),
       \                             expand('%'))
       \<bar>
       \ if res != '' | echo 'Vimwiki: HTML conversion is done.' | endif
 command! -buffer Vimwiki2HTMLBrowse
-      \ silent w <bar> 
+      \ silent noautocmd w <bar>
       \ call vimwiki#base#system_open_link(vimwiki#html#Wiki2HTML(
       \         expand(VimwikiGet('path_html')),
       \         expand('%')))
 command! -buffer VimwikiAll2HTML
       \ call vimwiki#html#WikiAll2HTML(expand(VimwikiGet('path_html')))
 
-command! -buffer VimwikiTOC call vimwiki#base#table_of_contents()
+command! -buffer VimwikiTOC call vimwiki#base#table_of_contents(1)
 
 command! -buffer VimwikiNextLink call vimwiki#base#find_next_link()
 command! -buffer VimwikiPrevLink call vimwiki#base#find_prev_link()
@@ -671,15 +671,21 @@ nnoremap <silent><buffer> <Plug>VimwikiRemoveHeaderLevel :
 " KEYBINDINGS }}}
 
 " AUTOCOMMANDS {{{
-if VimwikiGet('auto_export')
+function! s:toc_html()
-  " Automatically generate HTML on page write.
+  if VimwikiGet('auto_toc') >= 2 && VimwikiGet('auto_export') == 0
+    call vimwiki#base#table_of_contents(0)
+  endif
+  if VimwikiGet('auto_export')
+    call vimwiki#html#Wiki2HTML(expand(VimwikiGet('path_html')),
+      \                         expand('%'))
+  endif
+endfunction
+
+if VimwikiGet('auto_export') || VimwikiGet('auto_toc') >= 2
   augroup vimwiki
-    au BufWritePost <buffer> 
+    au BufWritePost <buffer> call s:toc_html()
-      \ call vimwiki#html#Wiki2HTML(expand(VimwikiGet('path_html')),
-      \                             expand('%'))
   augroup END
 endif
-
 " AUTOCOMMANDS }}}
 
 " PASTE, CAT URL {{{

plugin/vimwiki.vim

@@ -361,6 +361,7 @@ let s:vimwiki_defaults.template_ext = ''
 
 let s:vimwiki_defaults.nested_syntaxes = {}
 let s:vimwiki_defaults.auto_export = 0
+let s:vimwiki_defaults.auto_toc = 0
 " is wiki temporary -- was added to g:vimwiki_list by opening arbitrary wiki
 " file.
 let s:vimwiki_defaults.temp = 0
@@ -401,7 +402,7 @@ call s:default('dir_link', '')
 call s:default('valid_html_tags', 'b,i,s,u,sub,sup,kbd,br,hr,div,center,strong,em')
 call s:default('user_htmls', '')
 call s:default('autowriteall', 1)
-call s:default('toc_string', 'Contents')
+call s:default('toc_header', 'Contents')
 
 call s:default('html_header_numbering', 0)
 call s:default('html_header_numbering_sym', '')