fix(docs-html): keycodes, taglinks, column_heading #20498

Problem:
- Docs HTML: "foo ~" headings (column_heading) are not aligned with
  their table columns/contents because the leading whitespace is not
  emitted.
- taglinks starting with hyphen like |-x| were not recognized.
- keycodes like `<foo>` and `CTRL-x` were not recognized.
- ToC is not scrollable.

Solution:
- Add ws() to the column_heading case.
- Update help parser to latest version
  - supports `keycode`
  - fixes for taglink, argument
- Update .toc CSS. https://github.com/neovim/neovim.github.io/issues/297

fix https://github.com/neovim/neovim.github.io/issues/297

13 files changed, 76 insertions, 83 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 97a1bdc134..e27f191e0d 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -590,6 +590,7 @@ FileChangedShell		When Vim notices that the modification time of
 				- executing a shell command
 				- |:checktime|
 				- |FocusGained| 
+
 				Not used when 'autoread' is set and the buffer
 				was not changed.  If a FileChangedShell
 				autocommand exists the warning message and
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index d4bed7a5f2..f4a17b1842 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -48,21 +48,22 @@ a job channel using RPC, bytes can still be read over its stderr. Similarly,
 only bytes can be written to Nvim's own stderr.
 
 						*channel-callback*
-on_stdout({chan-id}, {data}, {name})		*on_stdout* 
-on_stderr({chan-id}, {data}, {name})		*on_stderr* 
-on_stdin({chan-id}, {data}, {name})		*on_stdin* 
-on_data({chan-id}, {data}, {name})		*on_data*
+- on_stdout({chan-id}, {data}, {name})		*on_stdout*
+- on_stderr({chan-id}, {data}, {name})		*on_stderr*
+- on_stdin({chan-id}, {data}, {name})		*on_stdin*
+- on_data({chan-id}, {data}, {name})		*on_data*
+
     Scripts can react to channel activity (received data) via callback
     functions assigned to the `on_stdout`, `on_stderr`, `on_stdin`, or
     `on_data` option keys. Callbacks should be fast: avoid potentially
     slow/expensive work.
 
     Parameters: ~
-      {chan-id}     Channel handle. |channel-id|
-      {data}	    Raw data (|readfile()|-style list of strings) read from
+      - {chan-id}   Channel handle. |channel-id|
+      - {data}	    Raw data (|readfile()|-style list of strings) read from
 		    the channel. EOF is a single-item list: `['']`. First and
 		    last items may be partial lines! |channel-lines|
-      {name}	    Stream name (string) like "stdout", so the same function
+      - {name}	    Stream name (string) like "stdout", so the same function
 		    can handle multiple streams. Event names depend on how the
 		    channel was opened and in what mode/protocol.
 
@@ -83,13 +84,14 @@ on_data({chan-id}, {data}, {name})		*on_data*
     the final `['']` emitted at EOF):
       - `foobar` may arrive as `['fo'], ['obar']` 
       - `foo\nbar` may arrive as
-	   `['foo','bar']`
-	or `['foo',''], ['bar']`
-	or `['foo'], ['','bar']`
-	or `['fo'], ['o','bar']`
+	- `['foo','bar']`
+	- or `['foo',''], ['bar']`
+	- or `['foo'], ['','bar']`
+	- or `['fo'], ['o','bar']`
+
     There are two ways to deal with this:
-    1. To wait for the entire output, use |channel-buffered| mode.
-    2. To read line-by-line, use the following code: >
+    - 1. To wait for the entire output, use |channel-buffered| mode.
+    - 2. To read line-by-line, use the following code: >
 	let s:lines = ['']
 	func! s:on_event(job_id, data, event) dict
 	  let eof = (a:data == [''])
diff --git a/runtime/doc/ft_ada.txt b/runtime/doc/ft_ada.txt
index 3f002f2df7..e4ac37a86e 100644
--- a/runtime/doc/ft_ada.txt
+++ b/runtime/doc/ft_ada.txt
@@ -51,7 +51,7 @@ for a complete list.
 To enable them, assign a value to the option.  For example, to turn one on:
  >
     > let g:ada_standard_types = 1
->
+
 To disable them use ":unlet".  Example:
 >
     > unlet g:ada_standard_types
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index a5630dabaa..60c2b4c5dd 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -308,7 +308,7 @@ These names for keys are used in the documentation.  They can also be used
 with the ":map" command.
 
 notation	meaning		    equivalent	decimal value(s)	~
------------------------------------------------------------------------
+----------------------------------------------------------------------- ~
 <Nul>		zero			CTRL-@	  0 (stored as 10) *<Nul>*
 <BS>		backspace		CTRL-H	  8	*backspace*
 <Tab>		tab			CTRL-I	  9	*tab* *Tab*
@@ -530,29 +530,29 @@ Ex		 :vi	  --	  --	 --	    --	      --
 
 -- not possible
 
-*1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
-   "A", "o", "O", "c", "C", "s" or S".
-*2 Go from Visual mode to Normal mode by giving a non-movement command, which
-   causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V"
-   (see |v_v|), which just stops Visual mode without side effects.
-*3 Go from Command-line mode to Normal mode by:
-   - Hitting <CR> or <NL>, which causes the entered command to be executed.
-   - Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>.
-   - Hitting CTRL-C or <Esc>, which quits the command-line without executing
-     the command.
-   In the last case <Esc> may be the character defined with the 'wildchar'
-   option, in which case it will start command-line completion.  You can
-   ignore that and type <Esc> again.
-*4 Go from Normal to Select mode by:
-   - use the mouse to select text while 'selectmode' contains "mouse"
-   - use a non-printable command to move the cursor while keeping the Shift
-     key pressed, and the 'selectmode' option contains "key"
-   - use "v", "V" or "CTRL-V" while 'selectmode' contains "cmd"
-   - use "gh", "gH" or "g CTRL-H"  |g_CTRL-H|
-*5 Go from Select mode to Normal mode by using a non-printable command to move
-   the cursor, without keeping the Shift key pressed.
-*6 Go from Select mode to Insert mode by typing a printable character.  The
-   selection is deleted and the character is inserted.
+* 1 Go from Normal mode to Insert mode by giving the command "i", "I", "a",
+    "A", "o", "O", "c", "C", "s" or S".
+* 2 Go from Visual mode to Normal mode by giving a non-movement command, which
+    causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V"
+    (see |v_v|), which just stops Visual mode without side effects.
+* 3 Go from Command-line mode to Normal mode by:
+    - Hitting <CR> or <NL>, which causes the entered command to be executed.
+    - Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>.
+    - Hitting CTRL-C or <Esc>, which quits the command-line without executing
+      the command.
+    In the last case <Esc> may be the character defined with the 'wildchar'
+    option, in which case it will start command-line completion.  You can
+    ignore that and type <Esc> again.
+* 4 Go from Normal to Select mode by:
+    - use the mouse to select text while 'selectmode' contains "mouse"
+    - use a non-printable command to move the cursor while keeping the Shift
+      key pressed, and the 'selectmode' option contains "key"
+    - use "v", "V" or "CTRL-V" while 'selectmode' contains "cmd"
+    - use "gh", "gH" or "g CTRL-H"  |g_CTRL-H|
+* 5 Go from Select mode to Normal mode by using a non-printable command to move
+    the cursor, without keeping the Shift key pressed.
+* 6 Go from Select mode to Insert mode by typing a printable character.  The
+    selection is deleted and the character is inserted.
 
 			*CTRL-\_CTRL-N* *i_CTRL-\_CTRL-N* *c_CTRL-\_CTRL-N*
 				      *v_CTRL-\_CTRL-N* *t_CTRL-\_CTRL-N*
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index 9ce3637563..5387900d16 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -24,7 +24,6 @@ Type |gO| to see the table of contents.
 
 ==============================================================================
 1  INTRODUCTION                                                   *luaref-intro*
-==============================================================================
 
 Lua is an extension programming language designed to support general
 procedural programming with data description facilities.  It also offers good
@@ -1504,7 +1503,6 @@ When you run it, it produces the following output:
 
 ==============================================================================
 3  THE APPLICATION PROGRAM INTERFACE                                *luaref-API*
-==============================================================================
 
 This section describes the C API for Lua, that is, the set of C functions
 available to the host program to communicate with Lua. All API functions and
@@ -2979,7 +2977,6 @@ lua_setupvalue                                                *lua_setupvalue()*
 
 ==============================================================================
 4  THE AUXILIARY LIBRARY                                            *luaref-aux*
-==============================================================================
 
 The auxiliary library provides several convenient functions to interface C
 with Lua. While the basic API provides the primitive functions for all
@@ -3511,7 +3508,6 @@ luaL_where                                                        *luaL_where()*
 
 ==============================================================================
 5  STANDARD LIBRARIES                                               *luaref-Lib*
-==============================================================================
 
 The standard libraries provide useful functions that are implemented directly
 through the C API. Some of these functions provide essential services to the
@@ -4064,7 +4060,7 @@ string.gmatch({s}, {pattern})                                  *string.gmatch()*
                end
 <
 
-string.gsub({s}, {pattern}, {repl} [, {n}])                    *string.gsu{b}()*
+string.gsub({s}, {pattern}, {repl} [, {n}])                    *string.gsub()*
         Returns a copy of {s} in which all occurrences of the {pattern} have
         been replaced by a replacement string specified by {repl}, which may
         be a string, a table, or a function. `gsub` also returns, as its
@@ -4831,7 +4827,6 @@ debug.traceback([{thread},] [{message}] [,{level}])          *debug.traceback()*
 
 ==============================================================================
 A  BIBLIOGRAPHY                                            *luaref-bibliography*
-==============================================================================
 
 This help file is a minor adaptation from this main reference:
 
@@ -4858,7 +4853,6 @@ Lua is discussed in these references:
 
 ==============================================================================
 B  COPYRIGHT & LICENSES                                       *luaref-copyright*
-==============================================================================
 
 This help file has the same copyright and license as Lua 5.1 and the Lua 5.1
  manual:
@@ -4885,7 +4879,6 @@ SOFTWARE.
 
 ==============================================================================
 C  LUAREF DOC                 *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc*
-==============================================================================
 
 This is a Vim help file containing a reference for Lua 5.1, and it is -- with
 a few exceptions and adaptations -- a copy of the Lua 5.1 Reference Manual
diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt
index 7a76c57fc2..dd2c99669c 100644
--- a/runtime/doc/mbyte.txt
+++ b/runtime/doc/mbyte.txt
@@ -334,8 +334,8 @@ Vim will automatically convert from one to another encoding in several places:
   "utf-8" (requires a gettext version that supports this).
 - When reading a Vim script where |:scriptencoding| is different from
   "utf-8".
-Most of these require the |+iconv| feature.  Conversion for reading and
-writing files may also be specified with the 'charconvert' option.
+Most of these require iconv.  Conversion for reading and writing files may
+also be specified with the 'charconvert' option.
 
 Useful utilities for converting the charset:
     All:	    iconv
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 8a629e0c05..837c3e7652 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -3920,9 +3920,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	`:lgrepadd`, `:cfile`, `:cgetfile`, `:caddfile`, `:lfile`, `:lgetfile`,
 	and `:laddfile`.
 
-	This would be mostly useful when you use MS-Windows.  If |+iconv| is
-	enabled and GNU libiconv is used, setting 'makeencoding' to "char" has
-	the same effect as setting to the system locale encoding.  Example: >
+	This would be mostly useful when you use MS-Windows.  If iconv is
+	enabled, setting 'makeencoding' to "char" has the same effect as
+	setting to the system locale encoding.  Example: >
 		:set makeencoding=char	" system locale is used
 <
 						*'makeprg'* *'mp'*
diff --git a/runtime/doc/pi_msgpack.txt b/runtime/doc/pi_msgpack.txt
index 801c56e49f..24a31f1de7 100644
--- a/runtime/doc/pi_msgpack.txt
+++ b/runtime/doc/pi_msgpack.txt
@@ -63,16 +63,16 @@ msgpack#is_uint({msgpack-value})			*msgpack#is_uint()*
 							*msgpack#strftime*
 msgpack#strftime({format}, {msgpack-integer})		*msgpack#strftime()*
 	Same as |strftime()|, but second argument may be 
-	|msgpack-special-dict|.  Requires |+python| or |+python3| to really 
-	work with |msgpack-special-dict|s.
+	|msgpack-special-dict|.  Requires |Python| to really work with
+	|msgpack-special-dict|s.
 
 							*msgpack#strptime*
 msgpack#strptime({format}, {time})			*msgpack#strptime()*
 	Reverse of |msgpack#strftime()|: for any time and format 
 	|msgpack#equal|( |msgpack#strptime|(format, |msgpack#strftime|(format, 
-	time)), time) be true.  Requires |+python| or |+python3|, without it 
-	only supports non-|msgpack-special-dict| nonnegative times and format 
-	equal to `%Y-%m-%dT%H:%M:%S`.
+	time)), time) be true.  Requires ||Python|, without it only supports
+	non-|msgpack-special-dict| nonnegative times and format equal to
+	`%Y-%m-%dT%H:%M:%S`.
 
 msgpack#int_dict_to_str({msgpack-special-int})	*msgpack#int_dict_to_str()*
 	Function which converts |msgpack-special-dict| integer value to 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 4ac076027c..2c18398598 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -35,7 +35,7 @@ filename	One or more file names.  The first one will be the current
 		no other options or "+command" argument can follow.
 
 							*--*
--		Alias for stdin (standard input).
+`-`		Alias for stdin (standard input).
 		Example: >
 			echo text | nvim - file
 <		"text" is read into buffer 1, "file" is opened as buffer 2.
@@ -1182,7 +1182,7 @@ exactly four MessagePack objects:
                        encoding   Binary, effective 'encoding' value.
                        max_kbyte  Integer, effective |shada-s| limit value.
                        pid        Integer, instance process ID.
-                       *          It is allowed to have any number of
+                       `*`          It is allowed to have any number of
                                   additional keys with any data.
    2 (SearchPattern)   Map containing data describing last used search or
                        substitute pattern.  Normally ShaDa file contains two
@@ -1213,7 +1213,7 @@ exactly four MessagePack objects:
                        sp   Binary   N/A      Actual pattern.  Required.
                        sb   Boolean  false    True if search direction is
                                               backward.
-                       *    any      none     Other keys are allowed for
+                       `*`    any      none     Other keys are allowed for
                                               compatibility reasons, see
                                               |shada-compatibility|.
    3 (SubString)       Array containing last |:substitute| replacement string.
@@ -1284,7 +1284,7 @@ exactly four MessagePack objects:
                                                GlobalMark and LocalMark
                                                entries.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
    9 (BufferList)      Array containing maps.  Each map in the array
@@ -1294,10 +1294,10 @@ exactly four MessagePack objects:
                                                greater then zero.
                        c    UInteger  0        Position column number.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
-   * (Unknown)         Any other entry type is allowed for compatibility
+   `*` (Unknown)         Any other entry type is allowed for compatibility
                        reasons, see |shada-compatibility|.
 
 								*E575* *E576*
diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt
index 4e4a908d0f..f4375c3363 100644
--- a/runtime/doc/testing.txt
+++ b/runtime/doc/testing.txt
@@ -134,7 +134,7 @@ assert_match({pattern}, {actual} [, {msg}])
 		When {pattern} does not match {actual} an error message is
 		added to |v:errors|.  Also see |assert-return|.
 
-		{pattern} is used as with |=~|: The matching is always done
+		{pattern} is used as with |expr-=~|: The matching is always done
 		like 'magic' was set and 'cpoptions' is empty, no matter what
 		the actual value of 'magic' or 'cpoptions' is.
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index fb9d59f885..6690dad4a7 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1074,8 +1074,8 @@ Various:					*various-functions*
 	wordcount()		get byte/word/char count of buffer
 
 	luaeval()		evaluate |Lua| expression
-	py3eval()		evaluate Python expression (|+python3|)
-	pyeval()		evaluate Python expression (|+python|)
+	py3eval()		evaluate |Python| expression
+	pyeval()		evaluate |Python| expression
 	pyxeval()		evaluate |python_x| expression
 	rubyeval()		evaluate |Ruby| expression
 
diff --git a/runtime/doc/usr_toc.txt b/runtime/doc/usr_toc.txt
index bf9c02882c..c61bb55c26 100644
--- a/runtime/doc/usr_toc.txt
+++ b/runtime/doc/usr_toc.txt
@@ -5,7 +5,7 @@
 			      Table Of Contents			*user-manual*
 
 ==============================================================================
-Overview ~
+Overview
 
 Getting Started
 |usr_01.txt|  About the manuals
@@ -52,7 +52,7 @@ The user manual is online:
 	https://neovim.io/doc/user
 
 ==============================================================================
-Getting Started ~
+Getting Started
 
 Read this from start to end to learn the essential commands.
 
@@ -167,7 +167,7 @@ Read this from start to end to learn the essential commands.
 		|12.8|	Find where a word is used
 
 ==============================================================================
-Editing Effectively ~
+Editing Effectively
 
 Subjects that can be read independently.
 
@@ -275,7 +275,7 @@ Subjects that can be read independently.
 		|32.4|	Time travelling
 
 ==============================================================================
-Tuning Vim ~
+Tuning Vim
 
 Make Vim work as you like it.
 
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 7c1658df76..8c6585a941 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -82,27 +82,24 @@ centralized reference of the differences.
 
 Default Mouse ~
 						*default-mouse* *disable-mouse*
-By default the mouse is enabled.  The right button click opens |popup-menu|
-with standard actions, such as "Cut", "Copy" and "Paste".
-
-If you don't like this you can add to your |config| any of the following:
-
-- ignore mouse completely >
+By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with
+standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in
+|command-mode| or the |more-prompt|, so you can temporarily disable it just by
+typing ":".
+
+If you don't like this you can disable the mouse in your |config| using any of
+the following:
+- Disable mouse completely by unsetting the 'mouse' option: >
   set mouse=
-<
-- no |popup-menu| but the right button extends selection >
+- Pressing <RightMouse> extends selection instead of showing popup-menu: >
   set mousemodel=extend
->
-- pressing ALT+LeftMouse releases mouse until main cursor moves  >
-  nnoremap <M-LeftMouse> <Cmd>
+- Pressing <A-LeftMouse> releases mouse until the cursor moves:  >
+  nnoremap <A-LeftMouse> <Cmd>
     \ set mouse=<Bar>
     \ echo 'mouse OFF until next cursor-move'<Bar>
     \ autocmd CursorMoved * ++once set mouse&<Bar>
     \ echo 'mouse ON'<CR>
 <
-Also, mouse is not in use in |command-mode| or at |more-prompt|.  So if you
-need to copy/paste with your terminal then just pressing ':' makes Nvim to
-release the mouse cursor temporarily.
 
 Default Mappings ~
 							*default-mappings*