fix(docs): vimdoc syntax errors

gen_help_html: truncate parse-error sample text

runtime/doc/builtin.txt

@@ -1939,7 +1939,7 @@ exists({expr})	The result is a Number, which is |TRUE| if {expr} is
 			$ENVNAME	environment variable (could also be
 					done by comparing with an empty
 					string)
-			*funcname	built-in function (see |functions|)
+			`*funcname`	built-in function (see |functions|)
 					or user defined function (see
 					|user-function|). Also works for a
 					variable that is a Funcref.
@@ -3019,7 +3019,7 @@ getcmdtype()						*getcmdtype()*
 		    /	forward search command
 		    ?	backward search command
 		    @	|input()| command
-		    -	|:insert| or |:append| command
+		    `-`	|:insert| or |:append| command
 		    =	|i_CTRL-R_=|
 		Only works when editing the command line, thus requires use of
 		|c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
@@ -3364,20 +3364,26 @@ getmatches([{win}])					*getmatches()*
 		If {win} is specified, use the window with this number or
 		window ID instead of the current window.  If {win} is invalid,
 		an empty list is returned.
-		Example: >
+		Example: >vim
 			:echo getmatches()
-<			[{"group": "MyGroup1", "pattern": "TODO",
+>
+ 			[{"group": "MyGroup1", "pattern": "TODO",
 			"priority": 10, "id": 1}, {"group": "MyGroup2",
-			"pattern": "FIXME", "priority": 10, "id": 2}] >
+			"pattern": "FIXME", "priority": 10, "id": 2}]
+>vim
 			:let m = getmatches()
 			:call clearmatches()
 			:echo getmatches()
-<			[] >
+>
+			[]
+>vim
 			:call setmatches(m)
 			:echo getmatches()
-<			[{"group": "MyGroup1", "pattern": "TODO",
+>
+			[{"group": "MyGroup1", "pattern": "TODO",
 			"priority": 10, "id": 1}, {"group": "MyGroup2",
-			"pattern": "FIXME", "priority": 10, "id": 2}] >
+			"pattern": "FIXME", "priority": 10, "id": 2}]
+>vim
 			:unlet m
 <
 getmousepos()						*getmousepos()*
@@ -8268,7 +8274,7 @@ string({expr})	Return {expr} converted to a String.  If {expr} is a Number,
 			Funcref		`function('name')`
 			Blob		0z00112233.44556677.8899
 			List		[item, item]
-			Dictionary	{key: value, key: value}
+			Dictionary	`{key: value, key: value}`
 		Note that in String values the ' character is doubled.
 		Also see |strtrans()|.
 		Note 2: Output format is mostly compatible with YAML, except

runtime/doc/change.txt

@@ -1490,7 +1490,7 @@ white space).  Three types of comments can be used:
   lines.  An example is this list with dashes.
 - Three-piece comments that have a start string, an end string, and optional
   lines in between.  The strings for the start, middle and end are different.
-  An example is the C style comment:
+  An example is the C style comment: >
 	/*
 	 * this is a C comment
 	 */
@@ -1565,20 +1565,20 @@ When you hit Return in a C-comment, Vim will insert the middle comment leader
 for the new line: " * ".  To close this comment you just have to type "/"
 before typing anything else on the new line.  This will replace the
 middle-comment leader with the end-comment leader and apply any specified
-alignment, leaving just " */".  There is no need to hit Backspace first.
+alignment, leaving just `" */"`.  There is no need to hit Backspace first.
 
 When there is a match with a middle part, but there also is a matching end
 part which is longer, the end part is used.  This makes a C style comment work
 without requiring the middle part to end with a space.
 
 Here is an example of alignment flags at work to make a comment stand out
-(kind of looks like a 1 too). Consider comment string: >
+(kind of looks like a 1 too). Consider comment string: >vim
 	:set comments=sr:/***,m:**,ex-2:******/
-<
+>
                                    /*** ~
                                      **<--right aligned from "r" flag ~
                                      ** ~
-offset 2 spaces for the "-2" flag--->** ~
+ offset 2 spaces for the "-2" flag-->** ~
                                    ******/ ~
 In this case, the first comment was typed, then return was pressed 4 times,
 then "/" was pressed to end the comment.
@@ -1741,10 +1741,10 @@ happens with formatting and auto-wrapping.  Opening a line after a line
 starting with "/*" or "*" and containing "*/", will cause no comment leader to
 be inserted, and the indent of the new line is taken from the line containing
 the start of the comment.
-E.g.:
+E.g.: >
-    /* ~
+    /*
-     * Your typical comment. ~
+     * Your typical comment.
-     */ ~
+     */
     The indent on this line is the same as the start of the above
     comment.
 

runtime/doc/cmdline.txt

@@ -100,7 +100,7 @@ CTRL-E or <End>					*c_CTRL-E* *c_<End>* *c_End*
 
 							*c_<MiddleMouse>*
 <MiddleMouse>	Paste the contents of the clipboard (for X11 the primary
-		selection).  This is similar to using CTRL-R *, but no CR
+		selection).  This is similar to using `CTRL-R *`, but no CR
 		characters are inserted between lines.
 
 CTRL-H						*c_<BS>* *c_CTRL-H* *c_BS*
@@ -190,8 +190,8 @@ CTRL-R CTRL-L				*c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>*
 
 					*c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>*
 					*c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>*
-CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}
+CTRL-R CTRL-R `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}`
-CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}
+CTRL-R CTRL-O `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}`
 		Insert register or object under the cursor.  Works like
 		|c_CTRL-R| but inserts the text literally.  For example, if
 		register a contains "xy^Hz" (where ^H is a backspace),
@@ -1058,7 +1058,7 @@ But expansion is only done if there are any wildcards before expanding the
 '%', '#', etc..  This avoids expanding wildcards inside a file name.  If you
 want to expand the result of <cfile>, add a wildcard character to it.
 Examples: (alternate file name is "?readme?")
-	command		expands to  ~
+	command		expands to >
 	:e #		:e ?readme?
 	:e `ls #`	:e {files matching "?readme?"}
 	:e #.*		:e {files matching "?readme?.*"}
@@ -1230,6 +1230,6 @@ The character used for the pattern indicates the type of command-line:
 	?	backward search string
 	=	expression for "= |expr-register|
 	@	string for |input()|
-	-	text for |:insert| or |:append|
+	`-`	text for |:insert| or |:append|
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/deprecated.txt

@@ -130,11 +130,11 @@ LSP FUNCTIONS
 - *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
 - *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
 - *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_active_clients()| with
-						{buffer = bufnr} instead.
+						{buffer=bufnr} instead.
 - *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
-						{async = true} instead.
+						{async=true} instead.
 - *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
-						{async = false} instead.
+						{async=false} instead.
 - *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
 						or |vim.lsp.buf.format()| instead.
 - *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| or access

runtime/doc/editing.txt

@@ -804,8 +804,8 @@ first line (the last line in Ex mode).
 
 							*{arglist}*
 The wildcards in the argument list are expanded and the file names are sorted.
-Thus you can use the command "vim *.c" to edit all the C files.  From within
+Thus you can use the command `vim *.c` to edit all the C files.  From within
-Vim the command ":n *.c" does the same.
+Vim the command `:n *.c` does the same.
 
 White space is used to separate file names.  Put a backslash before a space or
 tab to include it in a file name.  E.g., to edit the single file "foo bar": >
@@ -889,7 +889,7 @@ Example: >
 	:args *.c
 	:argdo set ff=unix | update
 This sets the 'fileformat' option to "unix" and writes the file if it is now
-changed.  This is done for all *.c files.
+changed.  This is done for all `*.c` files.
 
 Example: >
 	:args *.[ch]
@@ -1245,8 +1245,8 @@ If you want to always use ":confirm", set the 'confirm' option.
 			|:diffsplit|, |:diffpatch|, |:pedit|, |:redir|,
 			|:source|, |:update|, |:visual|, |:vsplit|,
 			and |:qall| if 'confirm' is set.
-			{only in Win32 GUI, in console `browse edit` works
+			Note: only in Win32 GUI; in console `:browse edit`
-			if the FileExplorer autocommand group exists}
+			works if the FileExplorer autocommand group exists.
 			When ":browse" is not possible you get an error
 			message.  If {command} doesn't support browsing, the
 			{command} is executed without a dialog.

runtime/doc/eval.txt

@@ -841,19 +841,19 @@ Expression syntax summary, from least to most significant:
 
 |expr9|	number			number constant
 	"string"		string constant, backslash is special
-	'string'		string constant, ' is doubled
+	`'string'`		string constant, ' is doubled
 	[expr1, ...]		|List|
-	{expr1: expr1, ...}	|Dictionary|
+	`{expr1: expr1, ...}`	|Dictionary|
 	#{key: expr1, ...}	|Dictionary|
 	&option			option value
 	(expr1)			nested expression
 	variable		internal variable
 	va{ria}ble		internal variable with curly braces
 	$VAR			environment variable
-	@r			contents of register 'r'
+	@r			contents of register "r"
 	function(expr1, ...)	function call
 	func{ti}on(expr1, ...)	function call with curly braces
-	{args -> expr1}		lambda expression
+	`{args -> expr1}`	lambda expression
 
 
 "..." indicates that the operations in this level can be concatenated.
@@ -1547,7 +1547,7 @@ See below |functions|.
 ------------------------------------------------------------------------------
 lambda expression				*expr-lambda* *lambda*
 
-{args -> expr1}		lambda expression			*E451*
+`{args -> expr1}`	lambda expression			*E451*
 
 A lambda expression creates a new unnamed function which returns the result of
 evaluating |expr1|.  Lambda expressions differ from |user-function|s in
@@ -1846,7 +1846,7 @@ v:ctype		The current locale setting for characters of the runtime
 v:dying		Normally zero.  When a deadly signal is caught it's set to
 		one.  When multiple signals are caught the number increases.
 		Can be used in an autocommand to check if Vim didn't
-		terminate normally. {only works on Unix}
+		terminate normally.
 		Example: >
 	:au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
 <		Note: if another deadly signal is caught when v:dying is one,
@@ -2493,7 +2493,7 @@ This does NOT work: >
 			*:let/=* *:let%=* *:let.=* *:let..=* *E734*
 :let {var} += {expr1}	Like ":let {var} = {var} + {expr1}".
 :let {var} -= {expr1}	Like ":let {var} = {var} - {expr1}".
-:let {var} *= {expr1}	Like ":let {var} = {var} * {expr1}".
+`:let {var} *= {expr1}`	Like ":let {var} = {var} * {expr1}".
 :let {var} /= {expr1}	Like ":let {var} = {var} / {expr1}".
 :let {var} %= {expr1}	Like ":let {var} = {var} % {expr1}".
 :let {var} .= {expr1}	Like ":let {var} = {var} . {expr1}".

runtime/doc/fold.txt

@@ -253,7 +253,7 @@ This does not work properly when:
   know what to do.
 - Folds nearby use a level number in their marker which gets in the way.
 - The line is inside a comment, 'commentstring' isn't empty and nested
-  comments don't work.  For example with C: adding /* {{{ */ inside a comment
+  comments don't work.  For example with C: adding `/* {{{ */` inside a comment
   will truncate the existing comment.  Either put the marker before or after
   the comment, or add the marker manually.
 Generally it's not a good idea to let Vim create markers when you already have

runtime/doc/ft_ada.txt

@@ -112,8 +112,8 @@ NOTE: "gnat xref -v" is very tricky to use as it has almost no diagnostic
     your .ali files.
 2)  "gnat xref -v ../Include/adacl.ads" won't work - use  the "gnat xref -v
     -aI../Include adacl.ads" instead.
-3)  "gnat xref -v -aI../Include *.ad?" won't work - use "cd ../Include" and
+3)  `gnat xref -v -aI../Include *.ad?` won't work - use "cd ../Include" and
-    then "gnat xref -v *.ad?"
+    then `gnat xref -v *.ad?`
 4)  Project manager support is completely broken - don't even try "gnat xref
     -Padacl.gpr".
 5)  Vim is faster when the tags file is sorted - use "sort --unique

runtime/doc/ft_raku.txt

@@ -35,10 +35,10 @@ Some of them are available with standard Vim digraphs:
 	(- ∈    ?= ≅    != ≠  ~
 	-) ∋    ?- ≃  ~
 
-The Greek alphabet is available with "*" followed by a similar Latin symbol:
+The Greek alphabet is available with "*" followed by a similar Latin symbol: >
-	*p π  ~
+	*p π
-	*t τ  ~
+	*t τ
-	*X ×  ~
+	*X ×
 
 Numbers, subscripts and superscripts are available with 's' and 'S':
 	0s ₀    0S ⁰  ~

runtime/doc/ft_sql.txt

@@ -728,7 +728,7 @@ You can create as many additional key maps as you like.  Generally, the maps
 will be specifying different syntax highlight groups.
 
 If you do not wish the default maps created or the key choices do not work on
-your platform (often a case on *nix) you define the following variable in
+your platform (often a case on unix) you define the following variable in
 your |init.vim|: >
     let g:omni_sql_no_default_maps = 1
 
@@ -738,7 +738,7 @@ which allows you to make customizations without changing the files that are
 included with the Vim distribution.  If you wish to customize the maps
 create an after/ftplugin/sql.vim (see |after-directory|) and place the same
 maps from the ftplugin/sql.vim in it using your own key strokes.  <C-C> was
-chosen since it will work on both Windows and *nix platforms.  On the windows
+chosen since it will work on both Windows and unix platforms.  On the windows
 platform you can also use <C-Space> or ALT keys.
 
 

runtime/doc/gui.txt

@@ -466,12 +466,11 @@ If no argument is given after :menu at all, then ALL menu items are shown
 for the appropriate mode (e.g., Command-line mode for :cmenu).
 
 Special characters in the list, just before the rhs:
-*	The menu was defined with "nore" to disallow remapping.
+• * Menu was defined with "nore" to disallow remapping.
-&	The menu was defined with "<script>" to allow remapping script-local
+• & Menu was defined with "<script>" to allow remapping script-local mappings.
-	mappings only.
+• s Menu was defined with "<silent>" to avoid showing what it is mapped to
-s	The menu was defined with "<silent>" to avoid showing what it is
+    when triggered.
-	mapped to when triggered.
+• - Menu was disabled.
--	The menu was disabled.
 
 Note that hitting <Tab> while entering a menu name after a menu command may
 be used to complete the name of the menu item.

runtime/doc/helphelp.txt

@@ -317,9 +317,9 @@ standard Vim help files, except for the first line.  If you are writing a new
 help file it's best to copy one of the existing files and use it as a
 template.
 
-The first line in a help file should have the following format:
+The first line in a help file should have the following format: >
 
-*plugin_name.txt*	{short description of the plugin}
+	*plugin_name.txt*	{short description of the plugin}
 
 The first field is a help tag where ":help plugin_name" will jump to.  The
 remainder of the line, after a Tab, describes the plugin purpose in a short
@@ -383,8 +383,8 @@ The following are highlighted differently in a Vim help file:
 
 The word "Note", "Notes" and similar automagically receive distinctive
 highlighting.  So do these:
-	*Todo	something to do
+	Todo	something to do
-	*Error	something wrong
+	Error	something wrong
 
 You can find the details in $VIMRUNTIME/syntax/help.vim
 

runtime/doc/if_pyth.txt

@@ -187,8 +187,8 @@ vim.foreach_rtp(callable)				*python-foreach_rtp*
 	are no longer paths. If stopped in case callable returned non-None,
 	vim.foreach_rtp function returns the value returned by callable.
 
-vim.chdir(*args, **kwargs)				*python-chdir*
+`vim.chdir(*args, **kwargs)`				*python-chdir*
-vim.fchdir(*args, **kwargs)				*python-fchdir*
+`vim.fchdir(*args, **kwargs)`				*python-fchdir*
 	Run os.chdir or os.fchdir, then all appropriate vim stuff.
 	Note: you should not use these functions directly, use os.chdir and
 	      os.fchdir instead. Behavior of vim.fchdir is undefined in case

runtime/doc/indent.txt

@@ -553,9 +553,9 @@ The examples below assume a 'shiftwidth' of 4.
 	      20 lines).
 
 								*cino-star*
-	*N    Vim searches for unclosed comments at most N lines away.  This
+	`*N`    Vim searches for unclosed comments at most N lines away.  This
 	      limits the time needed to search for the start of a comment.
-	      If your /* */ comments stop indenting after N lines this is the
+	      If your `/* */` comments stop indenting after N lines this is the
 	      value you will want to change.
 	      (default 70 lines).
 

runtime/doc/intro.txt

@@ -517,16 +517,15 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type
 <Esc> again.
 
 							*i_esc*
-		TO mode						    ~
+ FROM mode	TO mode						    ~
-		Normal	Visual	Select	Insert	  Replace   Cmd-line  Ex ~
+		Normal	Visual	Select	Insert	  Replace   Cmd-line  Ex >
-FROM mode								 ~
+ Normal			v V ^V	  *4	 *1	   R gR     : / ? !   Q
-Normal			v V ^V	  `*4`	 *1	   R gR     : / ? !   Q
+ Visual		 *2		  ^G	 c C	    --	      :       --
-Visual		 `*2`		  ^G	 c C	    --	      :       --
+ Select		 *5	^O ^G		 *6	    --	      --      --
-Select		 `*5`	^O ^G		 `*6`	    --	      --      --
+ Insert		 <Esc>	  --	  --		  <Insert>    --      --
-Insert		 <Esc>	  --	  --		  <Insert>    --      --
+ Replace		 <Esc>	  --	  --	<Insert>	      --      --
-Replace		 <Esc>	  --	  --	<Insert>	      --      --
+ Command-line	 `*3`	  --	  --	 :start	    --		      --
-Command-line	 `*3`	  --	  --	 :start	    --		      --
+ Ex		 :vi	  --	  --	 --	    --	      --
-Ex		 :vi	  --	  --	 --	    --	      --
 
 -- not possible
 

runtime/doc/lsp.txt

@@ -1093,7 +1093,7 @@ code_action({options})                             *vim.lsp.buf.code_action()*
                    • range: (table|nil) Range for which code actions should be
                      requested. If in visual mode this defaults to the active
                      selection. Table must contain `start` and `end` keys with
-                     {row, col} tuples using mark-like indexing. See
+                     {row,col} tuples using mark-like indexing. See
                      |api-indexing|
 
     See also: ~
@@ -1200,7 +1200,7 @@ format({options})                                       *vim.lsp.buf.format()*
                    • name (string|nil): Restrict formatting to the client with
                      name (client.name) matching this field.
                    • range (table|nil) Range to format. Table must contain
-                     `start` and `end` keys with {row, col} tuples using (1,0)
+                     `start` and `end` keys with {row,col} tuples using (1,0)
                      indexing. Defaults to current selection in visual mode
                      Defaults to `nil` in other modes, formatting the full
                      buffer
@@ -1728,9 +1728,9 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
     similar to |vim.lsp.util.make_range_params()|.
 
     Parameters: ~
-      • {start_pos}        integer[]|nil {row, col} mark-indexed position.
+      • {start_pos}        integer[]|nil {row,col} mark-indexed position.
                            Defaults to the start of the last visual selection.
-      • {end_pos}          integer[]|nil {row, col} mark-indexed position.
+      • {end_pos}          integer[]|nil {row,col} mark-indexed position.
                            Defaults to the end of the last visual selection.
       • {bufnr}            (integer|nil) buffer handle or 0 for current,
                            defaults to current
@@ -1867,8 +1867,8 @@ set_lines({lines}, {A}, {B}, {new_lines})           *vim.lsp.util.set_lines()*
 
     Parameters: ~
       • {lines}      (table) Original list of strings
-      • {A}          (table) Start position; a 2-tuple of {line, col} numbers
+      • {A}          (table) Start position; a 2-tuple of {line,col} numbers
-      • {B}          (table) End position; a 2-tuple of {line, col} numbers
+      • {B}          (table) End position; a 2-tuple of {line,col} numbers
       • {new_lines}  A list of strings to replace the original
 
     Return: ~

runtime/doc/map.txt

@@ -1051,8 +1051,7 @@ typed after an abbreviation: >
 There are no default abbreviations.
 
 Abbreviations are never recursive.  You can use ":ab f f-o-o" without any
-problem.  But abbreviations can be mapped.  {some versions of Vi support
+problem.  But abbreviations can be mapped.
-recursive abbreviations, for no apparent reason}
 
 				*:abbreviate-local* *:abbreviate-<buffer>*
 Just like mappings, abbreviations can be local to a buffer.  This is mostly

runtime/doc/mbyte.txt

@@ -357,150 +357,6 @@ conversion needs to be done.  These conversions are supported:
 	request a very large buffer, more than Vim is willing to provide).
 	Try getting another iconv() implementation.
 
-==============================================================================
-Input on X11					*mbyte-XIM*
-
-X INPUT METHOD (XIM) BACKGROUND			*XIM* *xim* *x-input-method*
-
-XIM is an international input module for X.  There are two kinds of structures,
-Xlib unit type and |IM-server| (Input-Method server) type.  |IM-server| type
-is suitable for complex input, such as CJK.
-
-- IM-server
-							*IM-server*
-  In |IM-server| type input structures, the input event is handled by either
-  of the two ways: FrontEnd system and BackEnd system.  In the FrontEnd
-  system, input events are snatched by the |IM-server| first, then |IM-server|
-  give the application the result of input.  On the other hand, the BackEnd
-  system works reverse order.  MS-Windows adopt BackEnd system.  In X, most of
-  |IM-server|s adopt FrontEnd system.  The demerit of BackEnd system is the
-  large overhead in communication, but it provides safe synchronization with
-  no restrictions on applications.
-
-- Conversion Server
-							*conversion-server*
-  Some system needs additional server: conversion server.  Most of Japanese
-  |IM-server|s need it, Kana-Kanji conversion server.  For Chinese inputting,
-  it depends on the method of inputting, in some methods, PinYin or ZhuYin to
-  HanZi conversion server is needed.  For Korean inputting, if you want to
-  input Hanja, Hangul-Hanja conversion server is needed.
-
-  For example, the Japanese inputting process is divided into 2 steps.  First
-  we pre-input Hira-gana, second Kana-Kanji conversion.  There are so many
-  Kanji characters (6349 Kanji characters are defined in JIS X 0208) and the
-  number of Hira-gana characters are 76.  So, first, we pre-input text as
-  pronounced in Hira-gana, second, we convert Hira-gana to Kanji or Kata-Kana,
-  if needed.  There are some Kana-Kanji conversion server: jserver
-  (distributed with Wnn, see below) and canna.  Canna can be found at:
-  http://canna.sourceforge.jp/
-
-There is a good input system: Wnn4.2.  Wnn 4.2 contains,
-    xwnmo (|IM-server|)
-    jserver (Japanese Kana-Kanji conversion server)
-    cserver (Chinese PinYin or ZhuYin to simplified HanZi conversion server)
-    tserver (Chinese PinYin or ZhuYin to traditional HanZi conversion server)
-    kserver (Hangul-Hanja conversion server)
-Wnn 4.2 for several systems can be found at various places on the internet.
-Use the RPM or port for your system.
-
-
-- Input Style
-							*xim-input-style*
-  When inputting CJK, there are four areas:
-      1. The area to display of the input while it is being composed
-      2. The area to display the currently active input mode.
-      3. The area to display the next candidate for the selection.
-      4. The area to display other tools.
-
-  The third area is needed when converting.  For example, in Japanese
-  inputting, multiple Kanji characters could have the same pronunciation, so
-  a sequence of Hira-gana characters could map to a distinct sequence of Kanji
-  characters.
-
-  The first and second areas are defined in international input of X with the
-  names of "Preedit Area", "Status Area" respectively.  The third and fourth
-  areas are not defined and are left to be managed by the |IM-server|.  In the
-  international input, four input styles have been defined using combinations
-  of Preedit Area and Status Area: |OnTheSpot|, |OffTheSpot|, |OverTheSpot|
-  and |Root|.
-
-  Currently, GUI Vim supports three styles, |OverTheSpot|, |OffTheSpot| and
-  |Root|.
-
-*.  on-the-spot						*OnTheSpot*
-    Preedit Area and Status Area are performed by the client application in
-    the area of application.  The client application is directed by the
-    |IM-server| to display all pre-edit data at the location of text
-    insertion.  The client registers callbacks invoked by the input method
-    during pre-editing.
-*.  over-the-spot					*OverTheSpot*
-    Status Area is created in a fixed position within the area of application,
-    in case of Vim, the position is the additional status line.  Preedit Area
-    is made at present input position of application.  The input method
-    displays pre-edit data in a window which it brings up directly over the
-    text insertion position.
-*.  off-the-spot					*OffTheSpot*
-    Preedit Area and Status Area are performed in the area of application, in
-    case of Vim, the area is additional status line.  The client application
-    provides display windows for the pre-edit data to the input method which
-    displays into them directly.
-*.  root-window						*Root*
-    Preedit Area and Status Area are outside of the application.  The input
-    method displays all pre-edit data in a separate area of the screen in a
-    window specific to the input method.
-
-
-USING XIM			*multibyte-input* *E284* *E285* *E286* *E287*
-					*E288* *E289*
-
-Note that Display and Input are independent.  It is possible to see your
-language even though you have no input method for it.  But when your Display
-method doesn't match your Input method, the text will be displayed wrong.
-
-To input your language you should run the |IM-server| which supports your
-language and |conversion-server| if needed.
-
-The next 3 lines should be put in your ~/.Xdefaults file.  They are common for
-all X applications which uses |XIM|.  If you already use |XIM|, you can skip
-this. >
-
-	*international: True
-	*.inputMethod: your_input_server_name
-	*.preeditType: your_input_style
-<
-input_server_name	is your |IM-server| name (check your |IM-server|
-			manual).
-your_input_style	is one of |OverTheSpot|, |OffTheSpot|, |Root|.  See
-			also |xim-input-style|.
-
-*international may not be necessary if you use X11R6.
-*.inputMethod and *.preeditType are optional if you use X11R6.
-
-For example, when you are using kinput2 as |IM-server|, >
-
-	*international: True
-	*.inputMethod: kinput2
-	*.preeditType: OverTheSpot
-<
-When using |OverTheSpot|, GUI Vim always connects to the IM Server even in
-Normal mode, so you can input your language with commands like "f" and "r".
-But when using one of the other two methods, GUI Vim connects to the IM Server
-only if it is not in Normal mode.
-
-If your IM Server does not support |OverTheSpot|, and if you want to use your
-language with some Normal mode command like "f" or "r", then you should use a
-localized xterm  or an xterm which supports |XIM|
-
-If needed, you can set the XMODIFIERS environment variable:
-
-	sh:  export XMODIFIERS="@im=input_server_name"
-	csh: setenv XMODIFIERS "@im=input_server_name"
-
-For example, when you are using kinput2 as |IM-server| and sh, >
-
-	export XMODIFIERS="@im=kinput2"
-<
-
 ==============================================================================
 Input with a keymap					*mbyte-keymap*
 

runtime/doc/message.txt

@@ -820,13 +820,13 @@ Type					effect ~
 					the clipboard ("* and "+ registers)
     {menu-entry}			what the menu is defined to in
 					Cmdline-mode.
-    <LeftMouse>				next page (*)
+    <LeftMouse>				next page*
 
 Any other key causes the meaning of the keys to be displayed.
 
-(*)  Clicking the left mouse button only works:
+* Clicking the left mouse button only works:
-     - For the GUI: in the last line of the screen.
+    - For the GUI: in the last line of the screen.
-     - When 'r' is included in 'mouse' (but then selecting text won't work).
+    - When 'r' is included in 'mouse' (but then selecting text won't work).
 
 
 Note: The typed key is directly obtained from the terminal, it is not mapped

runtime/doc/motion.txt

@@ -1230,7 +1230,7 @@ remembered.
 			([{}])		parenthesis or (curly/square) brackets
 					(this can be changed with the
 					'matchpairs' option)
-			/* */		start or end of C-style comment
+			`/* */`		start or end of C-style comment
 			#if, #ifdef, #else, #elif, #endif
 					C preprocessor conditionals (when the
 					cursor is on the # or no ([{

runtime/doc/options.txt

@@ -676,9 +676,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 	line.
 	When 'smartindent' or 'cindent' is on the indent is changed in
 	a different way.
-	{small difference from Vi: After the indent is deleted when typing
-	<Esc> or <CR>, the cursor position when moving up or down is after the
-	deleted indent; Vi puts the cursor somewhere in the deleted indent}.
 
 				 *'autoread'* *'ar'* *'noautoread'* *'noar'*
 'autoread' 'ar'		boolean	(default on)
@@ -1866,9 +1863,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Pattern to be used to find a macro definition.  It is a search
 	pattern, just like for the "/" command.  This option is used for the
 	commands like "[i" and "[d" |include-search|.  The 'isident' option is
-	used to recognize the defined name after the match:
+	used to recognize the defined name after the match: >
 		{match with 'define'}{non-ID chars}{defined name}{non-ID char}
-	See |option-backslash| about inserting backslashes to include a space
+<	See |option-backslash| about inserting backslashes to include a space
 	or backslash.
 	For C++ this value would be useful, to include const type declarations: >
 		^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\)
@@ -4042,9 +4039,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	per word depends very much on how similar the words are, that's why
 	this tuning is complicated.
 
-	There are three numbers, separated by commas:
+	There are three numbers, separated by commas: >
 		{start},{inc},{added}
-
+<
 	For most languages the uncompressed word tree fits in memory.  {start}
 	gives the amount of memory in Kbyte that can be used before any
 	compression is done.  It should be a bit smaller than the amount of

runtime/doc/pi_gzip.txt

@@ -19,7 +19,7 @@ You can avoid loading this plugin by setting the "loaded_gzip" variable: >
 The plugin installs autocommands to intercept reading and writing of files
 with these extensions:
 
-	extension	compression ~
+	extension	compression >
 	*.Z		compress (Lempel-Ziv)
 	*.gz		gzip
 	*.bz2		bzip2

runtime/doc/pi_msgpack.txt

@@ -6,7 +6,7 @@ Copyright: (c) 2015 by Nikolay Pavlov
 The Apache license applies to the files in this package, including 
 runtime/autoload/msgpack.vim, runtime/doc/pi_msgpack.txt and 
 test/functional/plugin/msgpack_spec.lua.  Like anything else that's free, 
-msgpack.vim and its associated files are provided *as is* and comes with no 
+msgpack.vim and its associated files are provided as is and comes with no 
 warranty of any kind, either expressed or implied.  No guarantees of 
 merchantability.  No guarantees of suitability for any purpose.  By using this 
 plugin, you agree that in no event will the copyright holder be liable for any 

runtime/doc/pi_tar.txt

@@ -11,7 +11,7 @@ Copyright 2005-2017:					*tar-copyright*
 	package, including tarPlugin.vim, tar.vim, and pi_tar.txt.  Like
 	anything else that's except use "tar.vim" instead of "VIM".  Like
 	anything else that's free, tar.vim and its associated files are
-	provided *as is* and comes with no warranty of any kind, either
+	provided as is and comes with no warranty of any kind, either
 	expressed or implied.  No guarantees of merchantability.  No
 	guarantees of suitability for any purpose.  By using this plugin, you
 	agree that in no event will the copyright holder be liable for any
@@ -27,7 +27,7 @@ Copyright 2005-2017:					*tar-copyright*
 ==============================================================================
 2. Usage					*tar-usage* *tar-manual*
 
-   When one edits a *.tar file, this plugin will handle displaying a
+   When one edits a `*.tar` file, this plugin will handle displaying a
    contents page.  Select a file to edit by moving the cursor atop
    the desired file, then hit the <return> key.  After editing, one may
    also write to the file.  Currently, one may not make a new file in
@@ -121,8 +121,8 @@ Copyright 2005-2017:					*tar-copyright*
 		May 28, 2008	* various security improvements.  Now requires
 				  patch 299 which provides the fnameescape()
 				  function
-		May 30, 2008	* allows one to view *.gz and *.bz2 files that
+		May 30, 2008	* allows one to view `*.gz` and `*.bz2` files that
-				  are in *.tar files.
+				  are in `*.tar` files.
 	v12	Sep 07, 2007	* &shq now used if not the empty string for
 				  g:tar_shq
 	v10	May 02, 2006	* now using "redraw then echo" to show messages,

runtime/doc/pi_zip.txt

@@ -10,7 +10,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell	 *zip-copyright*
 	The VIM LICENSE (see |copyright|) applies to the files in this
 	package, including zipPlugin.vim, zip.vim, and pi_zip.vim.  except use
 	"zip.vim" instead of "VIM".  Like anything else that's free, zip.vim
-	and its associated files are provided *as is* and comes with no
+	and its associated files are provided as is and comes with no
 	warranty of any kind, either expressed or implied.  No guarantees of
 	merchantability.  No guarantees of suitability for any purpose.  By
 	using this plugin, you agree that in no event will the copyright
@@ -27,7 +27,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell	 *zip-copyright*
 ==============================================================================
 2. Usage						*zip-usage* *zip-manual*
 
-   When one edits a *.zip file, this plugin will handle displaying a
+   When one edits a `*.zip` file, this plugin will handle displaying a
    contents page.  Select a file to edit by moving the cursor atop
    the desired file, then hit the <return> key.  After editing, one may
    also write to the file.  Currently, one may not make a new file in
@@ -102,7 +102,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell	 *zip-copyright*
 
 ==============================================================================
 4. History							*zip-history* {{{1
-   v33 Dec 07, 2021 * *.xlam mentioned twice in zipPlugin
+   v33 Dec 07, 2021 * `*.xlam` mentioned twice in zipPlugin
    v32 Oct 22, 2021 * to avoid an issue with a vim 8.2 patch, zipfile: has
 		      been changed to zipfile:// . This often shows up
 		      as zipfile:/// with zipped files that are root-based.
@@ -114,8 +114,8 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell	 *zip-copyright*
 		      the command actually to be attempted in zip#Read()
 		      and zip#Write()
 		    * added the extraction of a file capability
-       Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list
+       Nov 30, 2015 * added `*.epub` to the |g:zipPlugin_ext| list
-       Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and
+       Sep 13, 2016 * added `*.apk` to the |g:zipPlugin_ext| list and
 		      sorted the suffices.
    v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first
 		      two bytes.

runtime/doc/quickfix.txt

@@ -867,11 +867,11 @@ lists.  They set one of the existing error lists as the current one.
 
 						*:chistory* *:chi*
 :[count]chi[story]	Show the list of error lists.  The current list is
-			marked with ">".  The output looks like:
+			marked with ">".  The output looks like: >
-			  error list 1 of 3; 43 errors   :make  ~
+			  error list 1 of 3; 43 errors   :make
-			> error list 2 of 3; 0 errors    :helpgrep tag  ~
+			> error list 2 of 3; 0 errors    :helpgrep tag
-			  error list 3 of 3; 15 errors   :grep ex_help *.c ~
+			  error list 3 of 3; 15 errors   :grep ex_help *.c
-
+<
 			When [count] is given, then the count'th quickfix
 			list is made the current list. Example: >
 				" Make the 4th quickfix list current
@@ -1317,8 +1317,8 @@ TEX COMPILER						*compiler-tex*
 Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
 uses make command if possible.  If the compiler finds a file named "Makefile"
 or "makefile" in the current directory, it supposes that you want to process
-your *TeX files with make, and the makefile does the right work.  In this case
+your `*TeX` files with make, and the makefile does the right work.  In this case
-compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched.  If
+compiler sets 'errorformat' for `*TeX` output and leaves 'makeprg' untouched.  If
 neither "Makefile" nor "makefile" is found, the compiler will not use make.
 You can force the compiler to ignore makefiles by defining
 b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
@@ -1933,7 +1933,7 @@ You can customize the given setting to suit your own purposes, for example,
 all the annoying "Overfull ..." warnings could be excluded from being
 recognized as an error.
 Alternatively to filtering the LaTeX compiler output, it is also possible
-to directly read the *.log file that is produced by the [La]TeX compiler.
+to directly read the `*.log` file that is produced by the [La]TeX compiler.
 This contains even more useful information about possible error causes.
 However, to properly parse such a complex file, an external filter should
 be used.  See the description further above how to make such a filter known

runtime/doc/remote_plugin.txt

@@ -119,7 +119,7 @@ would also be spawned, which could take seconds!
 
 With the manifest, each host will only be loaded when required. Continuing with
 the example, say the Java plugin is a semantic completion engine for Java code.
-If it defines the autocommand "BufEnter *.java", then the Java host is spawned
+If it defines the autocommand `BufEnter *.java`, then the Java host is spawned
 only when Nvim loads a buffer matching "*.java".
 
 If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see

runtime/doc/scroll.txt

@@ -40,9 +40,6 @@ CTRL-D			Scroll window Downwards in the buffer.  The number of
 			difference).  When the cursor is on the last line of
 			the buffer nothing happens and a beep is produced.
 			See also 'startofline' option.
-			{difference from vi: Vim scrolls 'scroll' screen
-			lines, instead of file lines; makes a difference when
-			lines wrap}
 
 <S-Down>	or				*<S-Down>* *<kPageDown>*
 <PageDown>	or				*<PageDown>* *CTRL-F*

runtime/doc/starting.txt

@@ -824,7 +824,7 @@ resulting file, when executed with a ":source" command:
 9. Restores the Views for all the windows, as with |:mkview|.  But
    'sessionoptions' is used instead of 'viewoptions'.
 10. If a file exists with the same name as the Session file, but ending in
-   "x.vim" (for eXtra), executes that as well.  You can use *x.vim files to
+   "x.vim" (for eXtra), executes that as well.  You can use `*x.vim` files to
    specify additional settings and actions associated with a given Session,
    such as creating menu items in the GUI version.
 
@@ -908,7 +908,7 @@ found.
 
 You might want to clean up your 'viewdir' directory now and then.
 
-To automatically save and restore views for *.c files: >
+To automatically save and restore views for `*.c` files: >
 	au BufWinLeave *.c mkview
 	au BufWinEnter *.c silent! loadview
 

runtime/doc/tagsrch.txt

@@ -695,7 +695,7 @@ do not have an absolute path.
 The 'comments' option is used for the commands that display a single line or
 jump to a line.  It defines patterns that may start a comment.  Those lines
 are ignored for the search, unless [!] is used.  One exception: When the line
-matches the pattern "^# *define" it is not considered to be a comment.
+matches the pattern `"^# *define"` it is not considered to be a comment.
 
 If you want to list matches, and then select one to jump to, you could use a
 mapping to do that for you.  Here is an example: >
@@ -838,7 +838,7 @@ Common arguments for the commands above:
 [!]	When included, find matches in lines that are recognized as comments.
 	When excluded, a match is ignored when the line is recognized as a
 	comment (according to 'comments'), or the match is in a C comment
-	(after "//" or inside /* */).  Note that a match may be missed if a
+	(after "//" or inside `/* */`).  Note that a match may be missed if a
 	line is recognized as a comment, but the comment ends halfway the line.
 	And if the line is a comment, but it is not recognized (according to
 	'comments') a match may be found in it anyway.  Example: >

runtime/doc/tips.txt

@@ -47,7 +47,7 @@ is an overview with tags to jump to:
 
 |gf|			Go to file name under the cursor.
 
-|%|			Go to matching (), {}, [], /* */, #if, #else, #endif.
+|%|			Go to matching (), {}, [], `/* */`, #if, #else, #endif.
 |[/|			Go to previous start of comment.
 |]/|			Go to next end of comment.
 |[#|			Go back to unclosed #if, #ifdef, or #else.
@@ -196,7 +196,7 @@ charset.c
 digraph.c
 ...
 
-and I want to rename *.c *.bla.  I'd do it like this: >
+and I want to rename `*.c` `*.bla`.  I'd do it like this: >
 
 	$ vim
 	:r !ls *.c

runtime/doc/usr_09.txt

@@ -63,10 +63,10 @@ Vim will set the title to show the name of the current file.  First comes the
 name of the file.  Then some special characters and the directory of the file
 in parens.  These special characters can be present:
 
-	-	The file cannot be modified (e.g., a help file)
+	• -	The file cannot be modified (e.g., a help file)
-	+	The file contains changes
+	• +	The file contains changes
-	=	The file is read-only
+	• =	The file is read-only
-	=+	The file is read-only, contains changes anyway
+	• =+	The file is read-only, contains changes anyway
 
 If nothing is shown you have an ordinary, unchanged file.
 
@@ -223,7 +223,7 @@ Remember, "y" is yank, which is Vim's copy command.
 	"+P
 
 It's the same as for the current selection, but uses the plus (+) register
-instead of the star (*) register.
+instead of the star "*" register.
 
 ==============================================================================
 *09.4*	Select mode

runtime/doc/usr_12.txt

@@ -59,7 +59,7 @@ playback.
    Let's assume you have a directory with C++ files, all ending in ".cpp".
 There is a function called "GetResp" that you want to rename to "GetAnswer".
 
-	vim *.cpp		Start Vim, defining the argument list to
+	vim `*.cpp`		Start Vim, defining the argument list to
 				contain all the C++ files.  You are now in the
 				first file.
 	qq			Start recording into the q register
@@ -331,7 +331,7 @@ program files, for example, enter the following command: >
 	:grep error_string *.c
 
 This causes Vim to search for the string "error_string" in all the specified
-files (*.c).  The editor will now open the first file where a match is found
+files (`*.c`).  The editor will now open the first file where a match is found
 and position the cursor on the first matching line.  To go to the next
 matching line (no matter in what file it is), use the ":cnext" command.  To go
 to the previous match, use the ":cprev" command.  Use ":clist" to see all the

runtime/doc/usr_21.txt

@@ -426,7 +426,7 @@ a line of text that tells Vim the values of options, to be used in this file
 only.
    A typical example is a C program where you make indents by a multiple of 4
 spaces.  This requires setting the 'shiftwidth' option to 4.  This modeline
-will do that:
+will do that: >
 
 	/* vim:set shiftwidth=4: */ ~
 

runtime/doc/usr_22.txt

@@ -50,8 +50,8 @@ You can see these items:
 1.  The name of the browsing tool and its version number
 2.  The name of the browsing directory
 3.  The method of sorting (may be by name, time, or size)
-4.  How names are to be sorted (directories first, then *.h files,
+4.  How names are to be sorted (directories first, then `*.h` files,
-    *.c files, etc)
+    `*.c` files, etc)
 5.  How to get help (use the <F1> key), and an abbreviated listing
     of available commands
 6.  A listing of files, including "../", which allows one to list

runtime/doc/usr_24.txt

@@ -241,11 +241,11 @@ some other editors it's called intellisense, but that is a trademark.
 
 The key to Omni completion is CTRL-X CTRL-O.  Obviously the O stands for Omni
 here, so that you can remember it easier.  Let's use an example for editing C
-source:
+source: >
 
-	{ ~
+	{
-	    struct foo *p; ~
+	    struct foo *p;
-	    p-> ~
+	    p->
 
 The cursor is after "p->".  Now type CTRL-X CTRL-O.  Vim will offer you a list
 of alternatives, which are the items that "struct foo" contains.  That is
@@ -270,13 +270,13 @@ work.
 
 If you press CTRL-A, the editor inserts the text you typed the last time you
 were in Insert mode.
-   Assume, for example, that you have a file that begins with the following:
+   Assume, for example, that you have a file that begins with the following: >
 
 	"file.h" ~
 	/* Main program begins */ ~
 
 You edit this file by inserting "#include " at the beginning of the first
-line:
+line: >
 
 	#include "file.h" ~
 	/* Main program begins */ ~
@@ -286,13 +286,13 @@ now start to insert a new "#include" line.  So you type: >
 
 	i CTRL-A
 
-The result is as follows:
+The result is as follows: >
 
 	#include "file.h" ~
 	#include /* Main program begins */ ~
 
 The "#include " was inserted because CTRL-A inserts the text of the previous
-insert.  Now you type  "main.h"<Enter>  to finish the line:
+insert.  Now you type  "main.h"<Enter>  to finish the line: >
 
 
 	#include "file.h" ~
@@ -429,7 +429,7 @@ mistake.
 
 LISTING ABBREVIATIONS
 
-The ":abbreviate" command lists the abbreviations:
+The ":abbreviate" command lists the abbreviations: >
 
 	:abbreviate
 	i  #e		  ****************************************/

runtime/doc/usr_28.txt

@@ -277,7 +277,7 @@ Try it: >
 
 	:set foldmethod=marker
 
-Example text, as it could appear in a C program:
+Example text, as it could appear in a C program: >
 
 	/* foobar () {{{ */
 	int foobar()
@@ -292,7 +292,7 @@ Notice that the folded line will display the text before the marker.  This is
 very useful to tell what the fold contains.
 
 It's quite annoying when the markers don't pair up correctly after moving some
-lines around.  This can be avoided by using numbered markers.  Example:
+lines around.  This can be avoided by using numbered markers.  Example: >
 
 	/* global variables {{{1 */
 	int varA, varB;

runtime/doc/usr_29.txt

@@ -307,9 +307,9 @@ tags file.  Example: >
 	:psearch popen
 
 This will show the "stdio.h" file in the preview window, with the function
-prototype for popen():
+prototype for popen(): >c
 
-	FILE	*popen __P((const char *, const char *)); ~
+	FILE	*popen __P((const char *, const char *));
 
 You can specify the height of the preview window, when it is opened, with the
 'previewheight' option.
@@ -319,13 +319,13 @@ You can specify the height of the preview window, when it is opened, with the
 
 Since a program is structured, Vim can recognize items in it.  Specific
 commands can be used to move around.
-   C programs often contain constructs like this:
+   C programs often contain constructs like this: >c
 
-	#ifdef USE_POPEN ~
+	#ifdef USE_POPEN
-	    fd = popen("ls", "r") ~
+	    fd = popen("ls", "r")
-	#else ~
+	#else
-	    fd = fopen("tmp", "w") ~
+	    fd = fopen("tmp", "w")
-	#endif ~
+	#endif
 
 But then much longer, and possibly nested.  Position the cursor on the
 "#ifdef" and press %.  Vim will jump to the "#else".  Pressing % again takes
@@ -424,7 +424,7 @@ work on () pairs instead of {} pairs.
 MOVING IN COMMENTS
 
 To move back to the start of a comment use "[/".  Move forward to the end of a
-comment with "]/".  This only works for /* - */ comments.
+comment with "]/".  This only works for `/* - */` comments.
 >
 	  +->	  +-> /*
 	  |    [/ |    * A comment about      --+
@@ -446,10 +446,10 @@ You are editing a C program and wonder if a variable is declared as "int" or
 
 Vim will list the matching lines it can find.  Not only in the current file,
 but also in all included files (and files included in them, etc.).  The result
-looks like this:
+looks like this: >
 
-	structs.h ~
+	structs.h
-	 1:   29     unsigned     column;    /* column number */ ~
+	 1:   29     unsigned     column;    /* column number */
 
 The advantage over using tags or the preview window is that included files are
 searched.  In most cases this results in the right declaration to be found.

runtime/doc/usr_30.txt

@@ -517,12 +517,12 @@ The other way around works just as well: >
 
 One of the great things about Vim is that it understands comments.  You can
 ask Vim to format a comment and it will do the right thing.
-   Suppose, for example, that you have the following comment:
+   Suppose, for example, that you have the following comment: >c
 
-	/* ~
+	/*
-	 * This is a test ~
+	 * This is a test
-	 * of the text formatting. ~
+	 * of the text formatting.
-	 */ ~
+	 */
 
 You then ask Vim to format it by positioning the cursor at the start of the
 comment and type: >
@@ -530,33 +530,33 @@ comment and type: >
 	gq]/
 
 "gq" is the operator to format text.  "]/" is the motion that takes you to the
-end of a comment.  The result is:
+end of a comment.  The result is: >c
 
-	/* ~
+	/*
-	 * This is a test of the text formatting. ~
+	 * This is a test of the text formatting.
-	 */ ~
+	 */
 
 Notice that Vim properly handled the beginning of each line.
   An alternative is to select the text that is to be formatted in Visual mode
 and type "gq".
 
 To add a new line to the comment, position the cursor on the middle line and
-press "o".  The result looks like this:
+press "o".  The result looks like this: >c
 
-	/* ~
+	/*
-	 * This is a test of the text formatting. ~
+	 * This is a test of the text formatting.
-	 * ~
+	 *
-	 */ ~
+	 */
 
 Vim has automatically inserted a star and a space for you.  Now you can type
 the comment text.  When it gets longer than 'textwidth', Vim will break the
-line.  Again, the star is inserted automatically:
+line.  Again, the star is inserted automatically: >c
 
-	/* ~
+	/*
-	 * This is a test of the text formatting. ~
+	 * This is a test of the text formatting.
-	 * Typing a lot of text here will make Vim ~
+	 * Typing a lot of text here will make Vim
-	 * break ~
+	 * break
-	 */ ~
+	 */
 
 For this to work some flags must be present in 'formatoptions':
 

runtime/doc/usr_40.txt

@@ -159,7 +159,7 @@ RECURSIVE MAPPING
 When a mapping triggers itself, it will run forever.  This can be used to
 repeat an action an unlimited number of times.
    For example, you have a list of files that contain a version number in the
-first line.  You edit these files with "vim *.txt".  You are now editing the
+first line.  You edit these files with `vim *.txt`.  You are now editing the
 first file.  Define this mapping: >
 
 	:map ,, :s/5.1/5.2/<CR>:wnext<CR>,,
@@ -622,7 +622,7 @@ Example: >
 
 	:autocmd BufReadPost *.log normal G
 
-This will make the cursor jump to the last line of *.log files when you start
+This will make the cursor jump to the last line of `*.log` files when you start
 to edit it.
    Using the ":normal" command is a bit tricky.  First of all, make sure its
 argument is a complete command, including all the arguments.  When you use "i"

runtime/doc/usr_43.txt

@@ -123,12 +123,12 @@ That file is found in 'runtimepath' first.  Then use this in
 
 What will happen now is that Vim searches for "filetype.vim" files in each
 directory in 'runtimepath'.  First ~/.config/nvim/filetype.vim is found.  The
-autocommand to catch *.txt files is defined there.  Then Vim finds the
+autocommand to catch `*.txt` files is defined there.  Then Vim finds the
 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'.  Finally
 ~/.config/nvim/after/filetype.vim is found and the autocommand for detecting 
 ruby files in /usr/share/scripts is added.
    When you now edit /usr/share/scripts/README.txt, the autocommands are
-checked in the order in which they were defined.  The *.txt pattern matches,
+checked in the order in which they were defined.  The `*.txt` pattern matches,
 thus "setf text" is executed to set the filetype to "text".  The pattern for
 ruby matches too, and the "setf ruby" is executed.  But since 'filetype' was
 already set to "text", nothing happens here.

runtime/doc/vi_diff.txt

@@ -11,9 +11,9 @@ Differences between Vim and Vi				*vi-differences*
 ==============================================================================
 1. Limits						*limits*
 
-Vim has only a few limits for the files that can be edited {Vi: can not handle
+Vim has only a few limits for the files that can be edited. Vi cannot handle
 <Nul> characters and characters above 128, has limited line length, many other
-limits}.
+limits.
 
 Maximum line length	   2147483647 characters
 Maximum number of lines	   2147483647 lines
@@ -44,7 +44,7 @@ kept in memory:  Command-line history, error messages for Quickfix mode, etc.
 
 Support for different systems.
 	Vim can be used on:
-	- Modern Unix systems (*BSD, Linux, etc.)
+	- Modern Unix systems (BSD, Linux, etc.)
 	- Windows (XP SP 2 or greater)
 	- OS X
 

runtime/doc/windows.txt

@@ -631,7 +631,7 @@ times than |WinResized|, it may slow down editing a bit.
 
 The information provided by |WinScrolled| is a dictionary for each window that
 has changes, using the window ID as the key, and a total count of the changes
-with the key "all".  Example value for |v:event|:
+with the key "all".  Example value for |v:event|: >
 	{
 	   all: {width: 0, height: 2, leftcol: 0, skipcol: 0, topline: 1, topfill: 0},
 	   1003: {width: 0, height: -1, leftcol: 0, skipcol: 0, topline: 0, topfill: 0},
@@ -1090,7 +1090,7 @@ list of buffers. |unlisted-buffer|
 		  a	an active buffer: it is loaded and visible
 		  h	a hidden buffer: It is loaded, but currently not
 			   displayed in a window |hidden-buffer|
-		   -	a buffer with 'modifiable' off
+		   `-`	a buffer with 'modifiable' off
 		   =	a readonly buffer
 		   R	a terminal buffer with a running job
 		   F	a terminal buffer with a finished job
@@ -1101,7 +1101,7 @@ list of buffers. |unlisted-buffer|
 		[flags] can be a combination of the following characters,
 		which restrict the buffers to be listed:
 			+	modified buffers
-			-	buffers with 'modifiable' off
+			`-`	buffers with 'modifiable' off
 			=	readonly buffers
 			a	active buffers
 			u	unlisted buffers (overrides the "!")

runtime/lua/vim/iter.lua

@@ -359,7 +359,7 @@ function ListIter.totable(self)
   return self._table
 end
 
---- Fold an iterator or table into a single value.
+--- Fold ("reduce") an iterator or table into a single value.
 ---
 --- Examples:
 --- <pre>lua

runtime/lua/vim/lsp/buf.lua

@@ -122,7 +122,7 @@ end
 ---@private
 ---@param bufnr integer
 ---@param mode "v"|"V"
----@return table {start={row, col}, end={row, col}} using (1, 0) indexing
+---@return table {start={row,col}, end={row,col}} using (1, 0) indexing
 local function range_from_selection(bufnr, mode)
   -- TODO: Use `vim.region()` instead https://github.com/neovim/neovim/pull/13896
 
@@ -189,7 +189,7 @@ end
 ---         Restrict formatting to the client with name (client.name) matching this field.
 ---
 ---     - range (table|nil) Range to format.
----         Table must contain `start` and `end` keys with {row, col} tuples using
+---         Table must contain `start` and `end` keys with {row,col} tuples using
 ---         (1,0) indexing.
 ---         Defaults to current selection in visual mode
 ---         Defaults to `nil` in other modes, formatting the full buffer
@@ -741,7 +741,7 @@ end
 ---  - range: (table|nil)
 ---           Range for which code actions should be requested.
 ---           If in visual mode this defaults to the active selection.
----           Table must contain `start` and `end` keys with {row, col} tuples
+---           Table must contain `start` and `end` keys with {row,col} tuples
 ---           using mark-like indexing. See |api-indexing|
 ---
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction

runtime/lua/vim/lsp/util.lua

@@ -178,8 +178,8 @@ local _str_byteindex_enc = M._str_byteindex_enc
 --- CAUTION: Changes in-place!
 ---
 ---@param lines (table) Original list of strings
----@param A (table) Start position; a 2-tuple of {line, col} numbers
+---@param A (table) Start position; a 2-tuple of {line,col} numbers
----@param B (table) End position; a 2-tuple of {line, col} numbers
+---@param B (table) End position; a 2-tuple of {line,col} numbers
 ---@param new_lines A list of strings to replace the original
 ---@returns (table) The modified {lines} object
 function M.set_lines(lines, A, B, new_lines)
@@ -2075,9 +2075,9 @@ end
 --- Using the given range in the current buffer, creates an object that
 --- is similar to |vim.lsp.util.make_range_params()|.
 ---
----@param start_pos integer[]|nil {row, col} mark-indexed position.
+---@param start_pos integer[]|nil {row,col} mark-indexed position.
 --- Defaults to the start of the last visual selection.
----@param end_pos integer[]|nil {row, col} mark-indexed position.
+---@param end_pos integer[]|nil {row,col} mark-indexed position.
 --- Defaults to the end of the last visual selection.
 ---@param bufnr integer|nil buffer handle or 0 for current, defaults to current
 ---@param offset_encoding "utf-8"|"utf-16"|"utf-32"|nil defaults to `offset_encoding` of first client of `bufnr`

scripts/gen_help_html.lua

@@ -379,7 +379,9 @@ local function visit_validate(root, level, lang_tree, opt, stats)
       return
     end
     -- Store the raw text to give context to the error report.
-    local sample_text = not toplevel and getbuflinestr(root, opt.buf, 3) or '[top level!]'
+    local sample_text = not toplevel and getbuflinestr(root, opt.buf, 0) or '[top level!]'
+    -- Flatten the sample text to a single, truncated line.
+    sample_text = vim.trim(sample_text):gsub('[\t\n]', ' '):sub(1, 80)
     table.insert(stats.parse_errors, sample_text)
   elseif (node_name == 'word' or node_name == 'uppercase_name')
     and (not vim.tbl_contains({'codespan', 'taglink', 'tag'}, parent))
@@ -667,7 +669,7 @@ end
 ---
 --- @param fname string help file to validate
 --- @param parser_path string? path to non-default vimdoc.so
---- @returns { invalid_links: number, parse_errors: number }
+--- @returns { invalid_links: number, parse_errors: string[] }
 local function validate_one(fname, parser_path)
   local stats = {
     parse_errors = {},
@@ -1127,6 +1129,7 @@ function M.validate(help_dir, include, parser_path)
     parser_path={parser_path, function(f) return f == nil or vim.fn.filereadable(vim.fn.expand(f)) == 1 end, 'valid vimdoc.{so,dll} filepath'},
   }
   local err_count = 0
+  local files_to_errors = {}
   ensure_runtimepath()
   tagmap = get_helptags(help_dir)
   helpfiles = get_helpfiles(include)
@@ -1136,6 +1139,10 @@ function M.validate(help_dir, include, parser_path)
     local helpfile = vim.fs.basename(f)
     local rv = validate_one(f, parser_path)
     print(('validated (%-4s errors): %s'):format(#rv.parse_errors, helpfile))
+    if #rv.parse_errors > 0 then
+      files_to_errors[helpfile] = rv.parse_errors
+      vim.print(('%s'):format(vim.iter(rv.parse_errors):fold('', function(s, v) return s..'\n    '..v end)))
+    end
     err_count = err_count + #rv.parse_errors
   end
 
@@ -1145,6 +1152,7 @@ function M.validate(help_dir, include, parser_path)
     invalid_links = invalid_links,
     invalid_urls = invalid_urls,
     invalid_spelling = invalid_spelling,
+    parse_errors = files_to_errors,
   }
 end
 

test/functional/lua/help_spec.lua

@@ -19,11 +19,12 @@ describe(':help docs', function()
     local rv = exec_lua([[return require('scripts.gen_help_html').validate('./build/runtime/doc')]])
     -- Check that we actually found helpfiles.
     ok(rv.helpfiles > 100, '>100 :help files', rv.helpfiles)
+
+    eq({}, rv.parse_errors, 'no parse errors')
+    eq(0,  rv.err_count, 'no parse errors')
     eq({}, rv.invalid_links, 'invalid tags in :help docs')
     eq({}, rv.invalid_urls, 'invalid URLs in :help docs')
-    eq({}, rv.invalid_spelling, 'invalid spelling in :help docs')
+    eq({}, rv.invalid_spelling, 'invalid spelling in :help docs (see spell_dict in scripts/gen_help_html.lua)')
-    -- Check that parse errors did not increase.
-    ok(rv.err_count == 0, 'no parse errors', rv.err_count)
   end)
 
   it('gen_help_html.lua generates HTML', function()