doc: deprecate 'highlight'; remove howto.txt (#7497)

runtime/doc/cmdline.txt

@@ -361,7 +361,7 @@ These are the commands that can be used:
 							*c_CTRL-D*
 CTRL-D		List names that match the pattern in front of the cursor.
 		When showing file names, directories are highlighted (see
-		'highlight' option).  Names where 'suffixes' matches are moved
+		|highlight-groups|).  Names where 'suffixes' matches are moved
 		to the end.
 		The 'wildoptions' option can be set to "tagfile" to list the
 		file of matching tags.

runtime/doc/deprecated.txt

@@ -47,6 +47,7 @@ Modifiers ~
 
 Options ~
 *'fe'*			'fenc'+'enc' before Vim 6.0; no longer used.
+*'highlight'* *'hl'* 	Names of builtin |highlight-groups| cannot be changed.
 *'langnoremap'*		Deprecated alias to 'nolangremap'.
 *'vi'*
 *'viminfo'*		Deprecated alias to 'shada' option.

runtime/doc/help.txt

@@ -93,7 +93,6 @@ General subjects ~
 |helphelp.txt|	about using the help files
 |index.txt|	alphabetical index of all commands
 |help-tags|	all the tags you can jump to (index of tags)
-|howto.txt|	how to do the most common editing tasks
 |tips.txt|	various tips on using Vim
 |message.txt|	(error) messages and explanations
 |develop.txt|	development of Nvim

runtime/doc/howto.txt

@@ -1,96 +0,0 @@
-*howto.txt*	Nvim
-
-
-		  VIM REFERENCE MANUAL	  by Bram Moolenaar
-
-
-How to ...				*howdoi* *how-do-i* *howto* *how-to*
-
-|tutor|			get started
-|:quit|			exit?  I'm trapped, help me!
-|initialization|	initialize Vim
-|vimrc-intro|		write a Vim script file (vimrc)
-|suspend|		suspend Vim
-|usr_11.txt|		recover after a crash
-|07.4|			keep a backup of my file when writing over it
-
-|usr_07.txt|		edit files
-|23.4|			edit binary files
-|usr_24.txt|		insert text
-|deleting|		delete text
-|usr_04.txt|		change text
-|04.5|			copy and move text
-|usr_25.txt|		format text
-|30.6|			format comments
-|30.2|			indent C programs
-|25.3|			automatically set indent
-
-|usr_26.txt|		repeat commands
-|02.5|			undo and redo
-
-|usr_03.txt|		move around
-|word-motions|		word motions
-|left-right-motions|	left-right motions
-|up-down-motions|	up-down motions
-|object-motions|	text-object motions
-|various-motions|	various motions
-|object-select|		text-object selection
-|'whichwrap'|		move over line breaks
-|'virtualedit'|		move to where there is no text
-|usr_27.txt|		specify pattern for searches
-|tags-and-searches|	do tags and special searches
-|29.4|			search in include'd files used to find
-			variables, functions, or macros
-|K|			look up manual for the keyword under cursor
-
-|03.7|			scroll
-|'sidescroll'|		scroll horizontally/sideways
-|'scrolloff'|		set visible context lines
-
-|mode-switching|	change modes
-|04.4|			use Visual mode
-|'insertmode'|		start Vim in Insert mode
-
-|40.1|			map keys
-|24.7|			create abbreviations
-
-|ins-expandtab|		expand a tab to spaces in Insert mode
-|i_CTRL-R|		insert contents of a register in Insert mode
-|24.3|			complete words in Insert mode
-|25.1|			break a line before it gets too long
-
-|20.1|			do command-line editing
-|20.3|			do command-line completion
-|'cmdheight'|		increase the height of command-line
-|10.3|			specify command-line ranges
-|40.3|			specify commands to be executed automatically
-			before/after reading/writing entering/leaving a
-			buffer/window
-
-|'autowrite'|		write automatically
-|30.1|			speedup edit-compile-edit cycle or compile and fix
-			errors within Vim
-
-|options|		set options
-|auto-setting|		set options automatically
-|term-dependent-settings| set options depending on terminal name
-|save-settings|		save settings
-|:quote|		comment my .vim files
-|'helpheight'|		change the default help height
-|'highlight'|		set various highlighting modes
-|'title'|		set the window title
-|'icon'|		set window icon title
-|'report'|		avoid seeing the change messages on every line
-|'shortmess'|		avoid |hit-enter| prompts
-
-|mouse-using|		use mouse with Vim
-|usr_08.txt|		manage multiple windows and buffers
-|gui.txt|		use the gui
-
-|You can't! (yet)|	do dishes using Vim
-
-|usr_06.txt|		switch on syntax highlighting
-|2html.vim|		convert a colored file to HTML
-|less|			use Vim like less or more with syntax highlighting
-
- vim:tw=78:ts=8:ft=help:norl:

runtime/doc/intro.txt

@@ -713,9 +713,9 @@ special situation.  Vim will show only part of the line, around where the
 cursor is.  There are no special characters shown, so that you can edit all
 parts of this line.
 
-The '@' occasion in the 'highlight' option can be used to set special
+The |hl-NonText| highlight group can be used to set special highlighting
-highlighting for the '@' and '~' characters.  This makes it possible to
+for the '@' and '~' characters.  This makes it possible to distinguish them
-distinguish them from real characters in the buffer.
+from real characters in the buffer.
 
 The 'showbreak' option contains the string to put in front of wrapped lines.
 

runtime/doc/options.txt

@@ -3094,11 +3094,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 	WARNING: It's easy to forget that you have changes in hidden buffers.
 	Think twice when using ":q!" or ":qa!".
 
-						*'highlight'* *'hl'*
-'highlight' 'hl'	Removed. |vim-differences|
-			global
-	The builtin |highlight-groups| cannot be changed.
-
 						*'history'* *'hi'*
 'history' 'hi'		number	(Vim default: 10000, Vi default: 0)
 			global
@@ -3127,10 +3122,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 			{not available when compiled without the
 			|+extra_search| feature}
 	When there is a previous search pattern, highlight all its matches.
-	The type of highlighting used can be set with the 'l' occasion in the
+	The |hl-Search| highlight group determines the highlighting. Note that
-	'highlight' option.  This uses the "Search" highlight group by
+	only the matching text is highlighted, any offsets are not applied.
-	default.  Note that only the matching text is highlighted, any offsets
-	are not applied.
 	See also: 'incsearch' and |:match|.
 	When you get bored looking at the highlighted matches, you can turn it
 	off with |:nohlsearch|.  This does not change the option value, as
@@ -3298,7 +3291,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Vim only searches for about half a second.  With a complicated
 	pattern and/or a lot of text the match may not be found.  This is to
 	avoid that Vim hangs while you are typing the pattern.
-	The highlighting can be set with the 'i' flag in 'highlight'.
+	The |hl-IncSearch| highlight group determines the highlighting.
 	See also: 'hlsearch'.
 	CTRL-L can be used to add one character from after the current match
 	to the command line.  If 'ignorecase' and 'smartcase' are set and the
@@ -5346,8 +5339,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 <	Only printable single-cell characters are allowed, excluding <Tab> and
 	comma (in a future version the comma might be used to separate the
 	part that is shown at the end and at the start of a line).
-	The characters are highlighted according to the '@' flag in
+	The |hl-NonText| highlight group determines the highlighting.
-	'highlight'.
 	Note that tabs after the showbreak will be displayed differently.
 	If you want the 'showbreak' to appear in between line numbers, add the
 	"n" flag to 'cpoptions'.
@@ -5402,10 +5394,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 'showmode' 'smd'	boolean	(Vim default: on, Vi default: off)
 			global
 	If in Insert, Replace or Visual mode put a message on the last line.
-	Use the 'M' flag in 'highlight' to set the type of highlighting for
+	The |hl-ModeMsg| highlight group determines the highlighting.
-	this message.
-	When |XIM| may be used the message will include "XIM".  But this
-	doesn't mean XIM is really active.
 
 						*'showtabline'* *'stal'*
 'showtabline' 'stal'	number	(default 1)

runtime/doc/quickref.txt

@@ -721,7 +721,6 @@ Short explanation of each option:		*option-list*
 'helpheight'	  'hh'	    minimum height of a new help window
 'helplang'	  'hlg'     preferred help languages
 'hidden'	  'hid'     don't unload buffer when it is |abandon|ed
-'highlight'	  'hl'	    sets highlighting mode for various occasions
 'hlsearch'	  'hls'     highlight matches with last search pattern
 'history'	  'hi'	    number of command-lines that are remembered
 'hkmap'		  'hk'	    Hebrew keyboard mapping

runtime/doc/syntax.txt

@@ -4543,12 +4543,11 @@ is mostly used, because it looks better.
 ==============================================================================
 12. Highlight command			*:highlight* *:hi* *E28* *E411* *E415*
 
-There are three types of highlight groups:
+There are two types of highlight groups:
+- The built-in |highlight-groups|.
 - The ones used for specific languages.  For these the name starts with the
   name of the language.  Many of these don't have any attributes, but are
   linked to a group of the second type.
-- The ones used for all syntax languages.
-- The ones used for the 'highlight' option.
 							*hitest.vim*
 You can see all the groups currently active with this command: >
     :so $VIMRUNTIME/syntax/hitest.vim
@@ -5080,8 +5079,6 @@ defaults back: >
 It is a bit of a wrong name, since it does not reset any syntax items, it only
 affects the highlighting.
 
-This doesn't change the colors for the 'highlight' option.
-
 Note that the syntax colors that you set in your vimrc file will also be reset
 back to their Vim default.
 Note that if you are using a color scheme, the colors defined by the color

runtime/doc/various.txt

@@ -102,8 +102,7 @@ g8			Print the hex values of the bytes used in the
 							*:nu* *:number*
 :[range]nu[mber] [count] [flags]
 			Same as :print, but precede each line with its line
-			number.  (See also 'highlight' and 'numberwidth'
+			number.  (See also |hl-LineNr| and 'numberwidth').
-			option).
 			See |ex-flags| for [flags].
 
 							*:#*

runtime/doc/vim_diff.txt

@@ -377,7 +377,7 @@ Other options:
   'esckeys'
   'guioptions' "t" flag was removed
   *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.)
-  'highlight' (the builtin |highlight-groups| cannot be changed)
+  'highlight' (Names of builtin |highlight-groups| cannot be changed.)
   *'imactivatefunc'* *'imaf'*
   *'imactivatekey'* *'imak'*
   *'imstatusfunc'* *'imsf'*

runtime/doc/visual.txt

@@ -25,8 +25,7 @@ Using Visual mode consists of three parts:
 3. Type an operator command.
    The highlighted characters will be operated upon.
 
-The 'highlight' option can be used to set the display mode to use for
+The |hl-Visual| group determines the highlighting of the visual selection.
-highlighting in Visual mode.
 The 'virtualedit' option can be used to allow positioning the cursor to
 positions where there is no actual character.
 

runtime/doc/windows.txt

@@ -106,18 +106,10 @@ This option can be local to the window, so that you can have a different
 status line in each window.
 
 Normally, inversion is used to display the status line.  This can be changed
-with the 's' character in the 'highlight' option.  For example, "sb" sets it to
+with the |hl-StatusLine| highlight group.  If no highlighting is used for the
-bold characters.  If no highlighting is used for the status line ("sn"), the
+status line, the '^' character is used for the current window, and '=' for
-'^' character is used for the current window, and '=' for other windows.  If
+other windows.  If 'mouse' is enabled, a status line can be dragged to resize
-the mouse is supported and enabled with the 'mouse' option, a status line can
+windows.
-be dragged to resize windows.
-
-Note: If you expect your status line to be in reverse video and it isn't,
-check if the 'highlight' option contains "si".  In version 3.0, this meant to
-invert the status line.  Now it should be "sr", reverse the status line, as
-"si" now stands for italic!  If italic is not available on your terminal, the
-status line is inverted anyway; you will only see this problem on terminals
-that have |terminfo| capabilities for italics.
 
 ==============================================================================
 3. Opening and closing a window				*opening-window* *E36*

src/nvim/syntax.c

@@ -79,7 +79,7 @@ struct hl_group {
 #define SG_LINK         8       // link has been set
 /// @}
 
-// highlight groups for 'highlight' option
+// builtin |highlight-groups|
 static garray_T highlight_ga = GA_EMPTY_INIT_VALUE;
 
 static inline struct hl_group * HL_TABLE(void)