Adding upstream version 2:9.1.0016.upstream/2%9.1.0016

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 302 insertions, 0 deletions

diff --git a/runtime/doc/usr_06.txt b/runtime/doc/usr_06.txt
new file mode 100644
index 0000000..6d76c53
--- /dev/null
+++ b/runtime/doc/usr_06.txt
@@ -0,0 +1,302 @@
+*usr_06.txt*	For Vim version 9.1.  Last change: 2021 Nov 07
+
+		     VIM USER MANUAL - by Bram Moolenaar
+
+			  Using syntax highlighting
+
+
+Black and white text is boring.  With colors your file comes to life.  This
+not only looks nice, it also speeds up your work.  Change the colors used for
+the different sorts of text.  Print your text, with the colors you see on the
+screen.
+
+|06.1|	Switching it on
+|06.2|	No or wrong colors?
+|06.3|	Different colors
+|06.4|	With colors or without colors
+|06.5|	Printing with colors
+|06.6|	Further reading
+
+     Next chapter: |usr_07.txt|  Editing more than one file
+ Previous chapter: |usr_05.txt|  Set your settings
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*06.1*	Switching it on
+
+It all starts with one simple command: >
+
+	:syntax enable
+
+That should work in most situations to get color in your files.  Vim will
+automagically detect the type of file and load the right syntax highlighting.
+Suddenly comments are blue, keywords brown and strings red.  This makes it
+easy to overview the file.  After a while you will find that black&white text
+slows you down!
+
+If you always want to use syntax highlighting, put the ":syntax enable"
+command in your |vimrc| file.
+
+If you want syntax highlighting only when the terminal supports colors, you
+can put this in your |vimrc| file: >
+
+	if &t_Co > 1
+	   syntax enable
+	endif
+
+If you want syntax highlighting only in the GUI version, put the ":syntax
+enable" command in your |gvimrc| file.
+
+==============================================================================
+*06.2*	No or wrong colors?
+
+There can be a number of reasons why you don't see colors:
+
+- Your terminal does not support colors.
+	Vim will use bold, italic and underlined text, but this doesn't look
+	very nice.  You probably will want to try to get a terminal with
+	colors.  For Unix, I recommend the xterm from the XFree86 project:
+	|xfree-xterm|.
+
+- Your terminal does support colors, but Vim doesn't know this.
+	Make sure your $TERM setting is correct.  For example, when using an
+	xterm that supports colors: >
+
+		setenv TERM xterm-color
+<
+	or (depending on your shell): >
+
+		TERM=xterm-color; export TERM
+
+<	The terminal name must match the terminal you are using.  If it
+	still doesn't work, have a look at |xterm-color|, which shows a few
+	ways to make Vim display colors (not only for an xterm).
+
+- The file type is not recognized.
+	Vim doesn't know all file types, and sometimes it's near to impossible
+	to tell what language a file uses.  Try this command: >
+
+		:set filetype
+<
+	If the result is "filetype=" then the problem is indeed that Vim
+	doesn't know what type of file this is.  You can set the type
+	manually: >
+
+		:set filetype=fortran
+
+<	To see which types are available, look in the directory
+	$VIMRUNTIME/syntax.  For the GUI you can use the Syntax menu.
+	Setting the filetype can also be done with a |modeline|, so that the
+	file will be highlighted each time you edit it.  For example, this
+	line can be used in a Makefile (put it near the start or end of the
+	file): >
+
+		# vim: syntax=make
+
+<	You might know how to detect the file type yourself.  Often the file
+	name extension (after the dot) can be used.
+	See |new-filetype| for how to tell Vim to detect that file type.
+
+- There is no highlighting for your file type.
+	You could try using a similar file type by manually setting it as
+	mentioned above.  If that isn't good enough, you can write your own
+	syntax file, see |mysyntaxfile|.
+
+
+Or the colors could be wrong:
+
+- The colored text is very hard to read.
+	Vim guesses the background color that you are using.  If it is black
+	(or another dark color) it will use light colors for text.  If it is
+	white (or another light color) it will use dark colors for text.  If
+	Vim guessed wrong the text will be hard to read.  To solve this, set
+	the 'background' option.  For a dark background: >
+
+		:set background=dark
+
+<	And for a light background: >
+
+		:set background=light
+
+<	Make sure you put this _before_ the ":syntax enable" command,
+	otherwise the colors will already have been set.  You could do
+	":syntax reset" after setting 'background' to make Vim set the default
+	colors again.
+
+- The colors are wrong when scrolling bottom to top.
+	Vim doesn't read the whole file to parse the text.  It starts parsing
+	wherever you are viewing the file.  That saves a lot of time, but
+	sometimes the colors are wrong.  A simple fix is hitting CTRL-L.  Or
+	scroll back a bit and then forward again.
+	For a real fix, see |:syn-sync|.  Some syntax files have a way to make
+	it look further back, see the help for the specific syntax file.  For
+	example, |tex.vim| for the TeX syntax.
+
+==============================================================================
+*06.3*	Different colors				*:syn-default-override*
+
+If you don't like the default colors, you can select another color scheme.  In
+the GUI use the Edit/Color Scheme menu.  You can also type the command: >
+
+	:colorscheme evening
+
+"evening" is the name of the color scheme.  There are several others you might
+want to try out.  Look in the directory $VIMRUNTIME/colors.
+
+When you found the color scheme that you like, add the ":colorscheme" command
+to your |vimrc| file.
+
+You could also write your own color scheme.  This is how you do it:
+
+1. Select a color scheme that comes close.  Copy this file to your own Vim
+   directory.  For Unix, this should work: >
+
+	!mkdir ~/.vim/colors
+	!cp $VIMRUNTIME/colors/morning.vim ~/.vim/colors/mine.vim
+<
+   This is done from Vim, because it knows the value of $VIMRUNTIME.
+
+2. Edit the color scheme file.  These entries are useful:
+
+	term		attributes in a B&W terminal
+	cterm		attributes in a color terminal
+	ctermfg		foreground color in a color terminal
+	ctermbg		background color in a color terminal
+	gui		attributes in the GUI
+	guifg		foreground color in the GUI
+	guibg		background color in the GUI
+
+   For example, to make comments green: >
+
+	:highlight Comment ctermfg=green guifg=green
+<
+   Attributes you can use for "cterm" and "gui" are "bold" and "underline".
+   If you want both, use "bold,underline".  For details see the |:highlight|
+   command.
+
+3. Tell Vim to always use your color scheme.  Put this line in your |vimrc|: >
+
+	colorscheme mine
+
+If you want to see what the most often used color combinations look like, use
+this command: >
+
+	:runtime syntax/colortest.vim
+
+You will see text in various color combinations.  You can check which ones are
+readable and look nice. These aren't the only colors available to you though.
+You can specify #rrggbb hex colors and you can define new names for hex
+colors in |v:colornames| like so: >
+
+	let v:colornames['mine_red'] = '#aa0000'
+
+If you are authoring a color scheme for others to use, it is important
+to define these colors only when they do not exist: >
+
+	call extend(v:colornames, {'mine_red': '#aa0000'}, 'keep')
+
+This allows users of the color scheme to override the precise definition of
+that color prior to loading your color scheme. For example, in a |.vimrc|
+file: >
+
+	runtime colors/lists/css_colors.vim
+	let v:colornames['your_red'] = v:colornames['css_red']
+	colorscheme yourscheme
+
+As a color scheme author, you should be able to rely on some color names for
+GUI colors. These are defined in `colors/lists/default.vim`. All such files
+found on the |'runtimepath'| are loaded each time the colorscheme command is
+run. A canonical list is provided by the vim distribution, which should
+include all X11 colors (previously defined in rgb.txt).
+
+==============================================================================
+*06.4*	With colors or without colors
+
+Displaying text in color takes a lot of effort.  If you find the displaying
+too slow, you might want to disable syntax highlighting for a moment: >
+
+	:syntax clear
+
+When editing another file (or the same one) the colors will come back.
+
+If you want to stop highlighting completely use: >
+
+	:syntax off
+
+This will completely disable syntax highlighting and remove it immediately for
+all buffers.  See |:syntax-off| for more details.
+
+							*:syn-manual*
+If you want syntax highlighting only for specific files, use this: >
+
+	:syntax manual
+
+This will enable the syntax highlighting, but not switch it on automatically
+when starting to edit a buffer.  To switch highlighting on for the current
+buffer, set the 'syntax' option: >
+
+	:set syntax=ON
+<
+==============================================================================
+*06.5*	Printing with colors				*syntax-printing*
+
+In the MS-Windows version you can print the current file with this command: >
+
+	:hardcopy
+
+You will get the usual printer dialog, where you can select the printer and a
+few settings.  If you have a color printer, the paper output should look the
+same as what you see inside Vim.  But when you use a dark background the
+colors will be adjusted to look good on white paper.
+
+There are several options that change the way Vim prints:
+	'printdevice'
+	'printheader'
+	'printfont'
+	'printoptions'
+
+To print only a range of lines,  use Visual mode to select the lines and then
+type the command: >
+
+	v100j:hardcopy
+
+"v" starts Visual mode.  "100j" moves a hundred lines down, they will be
+highlighted.  Then ":hardcopy" will print those lines.  You can use other
+commands to move in Visual mode, of course.
+
+This also works on Unix, if you have a PostScript printer.  Otherwise, you
+will have to do a bit more work.  You need to convert the text to HTML first,
+and then print it from a web browser.
+
+Convert the current file to HTML with this command: >
+
+	:TOhtml
+
+In case that doesn't work: >
+
+	:source $VIMRUNTIME/syntax/2html.vim
+
+You will see it crunching away, this can take quite a while for a large file.
+Some time later another window shows the HTML code.  Now write this somewhere
+(doesn't matter where, you throw it away later):
+>
+	:write main.c.html
+
+Open this file in your favorite browser and print it from there.  If all goes
+well, the output should look exactly as it does in Vim.  See |2html.vim| for
+details.  Don't forget to delete the HTML file when you are done with it.
+
+Instead of printing, you could also put the HTML file on a web server, and let
+others look at the colored text.
+
+==============================================================================
+*06.6*	Further reading
+
+|usr_44.txt|  Your own syntax highlighted.
+|syntax|      All the details.
+
+==============================================================================
+
+Next chapter: |usr_07.txt|  Editing more than one file
+
+Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: