Merge #6632 from justinmk/doc

65 files changed, 220 insertions, 402 deletions

diff --git a/runtime/autoload/man.vim b/runtime/autoload/man.vim
index 96f03e47cc..c49c550b20 100644
--- a/runtime/autoload/man.vim
+++ b/runtime/autoload/man.vim
@@ -151,6 +151,31 @@ function! s:put_page(page) abort
   setlocal filetype=man
 endfunction
 
+function! man#show_toc() abort
+  let bufname = bufname('%')
+  let info = getloclist(0, {'winid': 1})
+  if !empty(info) && getwinvar(info.winid, 'qf_toc') ==# bufname
+    lopen
+    return
+  endif
+
+  let toc = []
+  let lnum = 2
+  let last_line = line('$') - 1
+  while lnum && lnum < last_line
+    let text = getline(lnum)
+    if text =~# '^\%( \{3\}\)\=\S.*$'
+      call add(toc, {'bufnr': bufnr('%'), 'lnum': lnum, 'text': text})
+    endif
+    let lnum = nextnonblank(lnum + 1)
+  endwhile
+
+  call setloclist(0, toc, ' ')
+  call setloclist(0, [], 'a', {'title': 'Man TOC'})
+  lopen
+  let w:qf_toc = bufname
+endfunction
+
 " attempt to extract the name and sect out of 'name(sect)'
 " otherwise just return the largest string of valid characters in ref
 function! man#extract_sect_and_name_ref(ref) abort
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index a118690876..9b2795863b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -11,6 +11,8 @@ via |msgpack-rpc|, Lua and VimL (|eval-api|).
 
 Applications can also embed libnvim to work with the C API directly.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 API Types							   *api-types*
 
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 50af870975..2a98d08c4e 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -8,17 +8,7 @@ Automatic commands					*autocommand*
 
 For a basic explanation, see section |40.3| in the user manual.
 
-1.  Introduction		|autocmd-intro|
-2.  Defining autocommands	|autocmd-define|
-3.  Removing autocommands	|autocmd-remove|
-4.  Listing autocommands	|autocmd-list|
-5.  Events			|autocmd-events|
-6.  Patterns			|autocmd-patterns|
-7.  Buffer-local autocommands	|autocmd-buflocal|
-8.  Groups			|autocmd-groups|
-9.  Executing autocommands	|autocmd-execute|
-10. Using autocommands		|autocmd-use|
-11. Disabling autocommands	|autocmd-disable|
+				      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Introduction						*autocmd-intro*
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 98cf459714..6af3c4d5d7 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -9,20 +9,10 @@ changing text means deleting the text and replacing it with other text using
 one command.  You can undo all of these commands.  You can repeat the non-Ex
 commands with the "." command.
 
-1. Deleting text		|deleting|
-2. Delete and insert		|delete-insert|
-3. Simple changes		|simple-change|		*changing*
-4. Complex changes		|complex-change|
-   4.1 Filter commands		   |filter|
-   4.2 Substitute		   |:substitute|
-   4.3 Search and replace	   |search-replace|
-   4.4 Changing tabs		   |change-tabs|
-5. Copying and moving text	|copy-move|
-6. Formatting text		|formatting|
-7. Sorting text			|sorting|
-
 For inserting text see |insert.txt|.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 1. Deleting text					*deleting* *E470*
 
@@ -259,7 +249,7 @@ Or use "caw" (see |aw|).
 			command is executed.
 
 ==============================================================================
-3. Simple changes					*simple-change*
+3. Simple changes				*simple-change* *changing*
 
 							*r*
 r{char}			Replace the character under the cursor with {char}.
@@ -398,11 +388,6 @@ CTRL-X			Subtract [count] from the number or alphabetic
 {Visual}CTRL-X		Subtract [count] from the number or alphabetic
 			character in the highlighted text.  {not in Vi}
 
-			On MS-Windows, this is mapped to cut Visual text
-			|dos-standard-mappings|.  If you want to disable the
-			mapping, use this: >
-				silent! vunmap <C-X>
-<
 							*v_g_CTRL-X*
 {Visual}g CTRL-X	Subtract [count] from the number or alphabetic
 			character in the highlighted text. If several lines
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 80b6cbbeab..948c921431 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -13,13 +13,7 @@ Command-line mode is used to enter Ex commands (":"), search patterns
 Basic command line editing is explained in chapter 20 of the user manual
 |usr_20.txt|.
 
-1. Command-line editing		|cmdline-editing|
-2. Command-line completion	|cmdline-completion|
-3. Ex command-lines		|cmdline-lines|
-4. Ex command-line ranges	|cmdline-ranges|
-5. Ex command-line flags	|ex-flags|
-6. Ex special characters	|cmdline-special|
-7. Command-line window		|cmdline-window|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Command-line editing					*cmdline-editing*
diff --git a/runtime/doc/debug.txt b/runtime/doc/debug.txt
index c5414e91ca..fd2c4fa54e 100644
--- a/runtime/doc/debug.txt
+++ b/runtime/doc/debug.txt
@@ -9,9 +9,7 @@ Debugging Vim						*debug-vim*
 This is for debugging Vim itself, when it doesn't work properly.
 For debugging Vim scripts, functions, etc. see |debug-scripts|
 
-1. Location of a crash, using gcc and gdb	|debug-gcc|
-2. Locating memory leaks			|debug-leaks|
-3. Windows Bug Reporting			|debug-win32|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 0e909aac65..7fd1f90173 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -6,14 +6,13 @@
 
 Development of Nvim.					*development*
 
-1. Design goals		        |design-goals|
-2. Developer guidelines	        |dev-help|
-
 Nvim is open source software.  Everybody is encouraged to contribute.
     https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
 
 See src/nvim/README.md for an overview of the source code.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 Design goals						*design-goals*
 
diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt
index e04aa55b5a..74a3d183a3 100644
--- a/runtime/doc/diff.txt
+++ b/runtime/doc/diff.txt
@@ -10,11 +10,7 @@ eight versions of the same file.
 
 The basics are explained in section |08.7| of the user manual.
 
-1. Starting diff mode		|diff-mode|
-2. Viewing diffs		|view-diffs|
-3. Jumping to diffs		|jumpto-diffs|
-4. Copying diffs		|copy-diffs|
-5. Diff options			|diff-options|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Starting diff mode
diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt
index 20fbe60602..89351c5b4f 100644
--- a/runtime/doc/digraph.txt
+++ b/runtime/doc/digraph.txt
@@ -14,9 +14,7 @@ with CTRL-V (see |i_CTRL-V|).
 There is a brief introduction on digraphs in the user manual: |24.9|
 An alternative is using the 'keymap' option.
 
-1. Defining digraphs	|digraphs-define|
-2. Using digraphs	|digraphs-use|
-3. Default digraphs	|digraphs-default|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Defining digraphs					*digraphs-define*
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 7007a89611..9fe815ea9c 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -6,17 +6,7 @@
 
 Editing files						*edit-files*
 
-1.  Introduction		|edit-intro|
-2.  Editing a file		|edit-a-file|
-3.  The argument list		|argument-list|
-4.  Writing			|writing|
-5.  Writing and quitting	|write-quit|
-6.  Dialogs			|edit-dialogs|
-7.  The current directory	|current-directory|
-8.  Editing binary files	|edit-binary|
-9.  Encryption			|encryption|
-10. Timestamps			|timestamps|
-11. File Searching		|file-searching|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Introduction						*edit-intro*
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index b7ff1b953c..3b9c11770e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -12,23 +12,7 @@ Note: Expression evaluation can be disabled at compile time.  If this has been
 done, the features in this document are not available.	See |+eval| and
 |no-eval-feature|.
 
-1.  Variables			|variables|
-    1.1 Variable types
-    1.2 Function references		|Funcref|
-    1.3 Lists				|Lists|
-    1.4 Dictionaries			|Dictionaries|
-    1.5 More about variables		|more-variables|
-2.  Expression syntax		|expression-syntax|
-3.  Internal variable		|internal-variables|
-4.  Builtin Functions		|functions|
-5.  Defining functions		|user-functions|
-6.  Curly braces names		|curly-braces-names|
-7.  Commands			|expression-commands|
-8.  Exception handling		|exception-handling|
-9.  Examples			|eval-examples|
-10. No +eval feature		|no-eval-feature|
-11. The sandbox			|eval-sandbox|
-12. Textlock			|textlock|
+				      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Variables						*variables*
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index c03100460d..64d9c6daa9 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -6,12 +6,10 @@
 
 Filetypes						*filetype* *file-type*
 
-1. Filetypes					|filetypes|
-2. Filetype plugin				|filetype-plugins|
-3. Docs for the default filetype plugins.	|ftplugin-docs|
-
 Also see |autocmd.txt|.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 1. Filetypes					*filetypes* *file-types*
 
@@ -542,6 +540,7 @@ K or CTRL-]               Jump to the manpage for the <cWORD> under the
                           cursor. Takes a count for the section.
 CTRL-T                    Jump back to the location that the manpage was
                           opened from.
+META-]                    Show the manpage outline in the |location-list|.
 q                         :quit if invoked as $MANPAGER, otherwise :close.
 
 Variables:
diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt
index 4826a65d7b..88dde9f61d 100644
--- a/runtime/doc/fold.txt
+++ b/runtime/doc/fold.txt
@@ -9,10 +9,7 @@ Folding						*Folding* *folding* *folds*
 You can find an introduction on folding in chapter 28 of the user manual.
 |usr_28.txt|
 
-1. Fold methods		|fold-methods|
-2. Fold commands	|fold-commands|
-3. Fold options		|fold-options|
-4. Behavior of folds	|fold-behavior|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Fold methods					*fold-methods*
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 7cf489d769..314799d083 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -6,12 +6,7 @@
 
 Vim's Graphical User Interface				*gui* *GUI*
 
-1. Starting the GUI		|gui-start|
-2. Scrollbars			|gui-scrollbars|
-3. Mouse Control		|gui-mouse|
-4. Making GUI Selections	|gui-selections|
-5. Menus			|menus|
-6. Extras			|gui-extras|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Starting the GUI				*gui-start* *E229* *E233*
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index 31a425bdee..5948b24667 100644
--- a/runtime/doc/helphelp.txt
+++ b/runtime/doc/helphelp.txt
@@ -6,9 +6,7 @@
 
 Help on help files					*helphelp*
 
-1. Help commands		|online-help|
-2. Translated help files	|help-translated|
-3. Writing help files		|help-writing|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Help commands					*online-help*
@@ -25,6 +23,8 @@ Help on help files					*helphelp*
 			The 'helplang' option is used to select a language, if
 			the main help file is available in several languages.
 
+			Type <M-]> to see the table of contents.
+
 						*{subject}* *E149* *E661*
 :h[elp] {subject}	Like ":help", additionally jump to the tag {subject}.
 			For example:  >
diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt
index 3ce1575c99..831b2c9840 100644
--- a/runtime/doc/if_cscop.txt
+++ b/runtime/doc/if_cscop.txt
@@ -12,15 +12,7 @@ a cscope query is just like jumping to any tag; it is saved on the tag stack
 so that with the right keyboard mappings, you can jump back and forth between
 functions as you normally would with |tags|.
 
-1. Cscope introduction		|cscope-intro|
-2. Cscope related commands	|cscope-commands|
-3. Cscope options		|cscope-options|
-4. How to use cscope in Vim	|cscope-howtouse|
-5. Limitations			|cscope-limitations|
-6. Suggested usage		|cscope-suggestions|
-7. Availability & Information	|cscope-info|
-
-This is currently for Unix and Win32 only.
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Cscope introduction					*cscope-intro*
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index e19a80059a..25da033190 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -6,18 +6,10 @@
 
 The Python Interface to Vim				*python* *Python*
 
-1. Commands					|python-commands|
-2. The vim module				|python-vim|
-3. Buffer objects				|python-buffer|
-4. Range objects				|python-range|
-5. Window objects				|python-window|
-6. Tab page objects				|python-tabpage|
-7. vim.bindeval objects				|python-bindeval-objects|
-8. pyeval(), py3eval() Vim functions		|python-pyeval|
-9. Python 3					|python3|
-
 See |provider-python| for more information. {Nvim}
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 1. Commands						*python-commands*
 
diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt
index e02ace67de..54d81a958d 100644
--- a/runtime/doc/if_ruby.txt
+++ b/runtime/doc/if_ruby.txt
@@ -5,18 +5,13 @@
 
 The Ruby Interface to Vim				*ruby* *Ruby*
 
-
-1. Commands			|ruby-commands|
-2. The VIM module		|ruby-vim|
-3. VIM::Buffer objects		|ruby-buffer|
-4. VIM::Window objects		|ruby-window|
-5. Global variables		|ruby-globals|
-
 			*E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273*
 
 The home page for ruby is http://www.ruby-lang.org/.  You can find links for
 downloading Ruby there.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 1. Commands						*ruby-commands*
 
diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt
index 4f4b39f559..8e17de3fb0 100644
--- a/runtime/doc/indent.txt
+++ b/runtime/doc/indent.txt
@@ -6,8 +6,7 @@
 
 This file is about indenting C programs and other files.
 
-1. Indenting C style programs	|C-indenting|
-2. Indenting by expression	|indent-expression|
+                                      Type <M-]> to see the table of contents.
 
 ==============================================================================
 1. Indenting C style programs				*C-indenting*
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 16e9d4a64d..06196dbefa 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -10,22 +10,13 @@ short description.  The lists are sorted on ASCII value.
 Tip: When looking for certain functionality, use a search command.  E.g.,
 to look for deleting something, use: "/delete".
 
-1. Insert mode				|insert-index|
-2. Normal mode				|normal-index|
-   2.1. Text objects			|objects|
-   2.2. Window commands			|CTRL-W|
-   2.3. Square bracket commands		|[|
-   2.4. Commands starting with 'g'	|g|
-   2.5. Commands starting with 'z'	|z|
-3. Visual mode				|visual-index|
-4. Command-line editing			|ex-edit-index|
-5. EX commands				|ex-cmd-index|
-
 For an overview of options see help.txt |option-list|.
 For an overview of built-in functions see |functions|.
 For a list of Vim variables see |vim-variable|.
 For a complete listing of all help items see |help-tags|.
 
+                                      Type <M-]> to see the table of contents.
+
 ==============================================================================
 1. Insert mode						*insert-index*
 
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 8b8c05c070..9219f45c83 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -13,20 +13,11 @@ commands for inserting text in other ways.
 An overview of the most often used commands can be found in chapter 24 of the
 user manual |usr_24.txt|.
 
-1. Special keys						|ins-special-keys|
-2. Special special keys					|ins-special-special|
-3. 'textwidth' and 'wrapmargin' options			|ins-textwidth|
-4. 'expandtab', 'smarttab' and 'softtabstop'  options	|ins-expandtab|
-5. Replace mode						|Replace-mode|
-6. Virtual Replace mode					|Virtual-Replace-mode|
-7. Insert mode completion				|ins-completion|
-8. Insert mode commands					|inserting|
-9. Ex insert commands					|inserti