summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_06.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--runtime/doc/usr_06.txt302
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..2b6fa51
--- /dev/null
+++ b/runtime/doc/usr_06.txt
@@ -0,0 +1,302 @@
+*usr_06.txt* For Vim version 9.0. 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: