share/vim/vim73/doc/usr_06.txt

   1 *usr_06.txt*    For Vim version 7.3.  Last change: 2009 Oct 28
   2
   3                      VIM USER MANUAL - by Bram Moolenaar
   4
   5                           Using syntax highlighting
   6
   7
   8 Black and white text is boring.  With colors your file comes to life.  This
   9 not only looks nice, it also speeds up your work.  Change the colors used for
  10 the different sorts of text.  Print your text, with the colors you see on the
  11 screen.
  12
  13 |06.1|  Switching it on
  14 |06.2|  No or wrong colors?
  15 |06.3|  Different colors
  16 |06.4|  With colors or without colors
  17 |06.5|  Printing with colors
  18 |06.6|  Further reading
  19
  20      Next chapter: |usr_07.txt|  Editing more than one file
  21  Previous chapter: |usr_05.txt|  Set your settings
  22 Table of contents: |usr_toc.txt|
  23
  24 ==============================================================================
  25 *06.1*  Switching it on
  26
  27 It all starts with one simple command: >
  28
  29         :syntax enable
  30
  31 That should work in most situations to get color in your files.  Vim will
  32 automagically detect the type of file and load the right syntax highlighting.
  33 Suddenly comments are blue, keywords brown and strings red.  This makes it
  34 easy to overview the file.  After a while you will find that black&white text
  35 slows you down!
  36
  37 If you always want to use syntax highlighting, put the ":syntax enable"
  38 command in your |vimrc| file.
  39
  40 If you want syntax highlighting only when the terminal supports colors, you
  41 can put this in your |vimrc| file: >
  42
  43         if &t_Co > 1
  44            syntax enable
  45         endif
  46
  47 If you want syntax highlighting only in the GUI version, put the ":syntax
  48 enable" command in your |gvimrc| file.
  49
  50 ==============================================================================
  51 *06.2*  No or wrong colors?
  52
  53 There can be a number of reasons why you don't see colors:
  54
  55 - Your terminal does not support colors.
  56         Vim will use bold, italic and underlined text, but this doesn't look
  57         very nice.  You probably will want to try to get a terminal with
  58         colors.  For Unix, I recommend the xterm from the XFree86 project:
  59         |xfree-xterm|.
  60
  61 - Your terminal does support colors, but Vim doesn't know this.
  62         Make sure your $TERM setting is correct.  For example, when using an
  63         xterm that supports colors: >
  64
  65                 setenv TERM xterm-color
  66 <
  67         or (depending on your shell): >
  68
  69                 TERM=xterm-color; export TERM
  70
  71 <       The terminal name must match the terminal you are using.  If it
  72         still doesn't work, have a look at |xterm-color|, which shows a few
  73         ways to make Vim display colors (not only for an xterm).
  74
  75 - The file type is not recognized.
  76         Vim doesn't know all file types, and sometimes it's near to impossible
  77         to tell what language a file uses.  Try this command: >
  78
  79                 :set filetype
  80 <
  81         If the result is "filetype=" then the problem is indeed that Vim
  82         doesn't know what type of file this is.  You can set the type
  83         manually: >
  84
  85                 :set filetype=fortran
  86
  87 <       To see which types are available, look in the directory
  88         $VIMRUNTIME/syntax.  For the GUI you can use the Syntax menu.
  89         Setting the filetype can also be done with a |modeline|, so that the
  90         file will be highlighted each time you edit it.  For example, this
  91         line can be used in a Makefile (put it near the start or end of the
  92         file): >
  93
  94                 # vim: syntax=make
  95
  96 <       You might know how to detect the file type yourself.  Often the file
  97         name extension (after the dot) can be used.
  98         See |new-filetype| for how to tell Vim to detect that file type.
  99
 100 - There is no highlighting for your file type.
 101         You could try using a similar file type by manually setting it as
 102         mentioned above.  If that isn't good enough, you can write your own
 103         syntax file, see |mysyntaxfile|.
 104
 105
 106 Or the colors could be wrong:
 107
 108 - The colored text is very hard to read.
 109         Vim guesses the background color that you are using.  If it is black
 110         (or another dark color) it will use light colors for text.  If it is
 111         white (or another light color) it will use dark colors for text.  If
 112         Vim guessed wrong the text will be hard to read.  To solve this, set
 113         the 'background' option.  For a dark background: >
 114
 115                 :set background=dark
 116
 117 <       And for a light background: >
 118
 119                 :set background=light
 120
 121 <       Make sure you put this _before_ the ":syntax enable" command,
 122         otherwise the colors will already have been set.  You could do
 123         ":syntax reset" after setting 'background' to make Vim set the default
 124         colors again.
 125
 126 - The colors are wrong when scrolling bottom to top.
 127         Vim doesn't read the whole file to parse the text.  It starts parsing
 128         wherever you are viewing the file.  That saves a lot of time, but
 129         sometimes the colors are wrong.  A simple fix is hitting CTRL-L.  Or
 130         scroll back a bit and then forward again.
 131         For a real fix, see |:syn-sync|.  Some syntax files have a way to make
 132         it look further back, see the help for the specific syntax file.  For
 133         example, |tex.vim| for the TeX syntax.
 134
 135 ==============================================================================
 136 *06.3*  Different colors                                *:syn-default-override*
 137
 138 If you don't like the default colors, you can select another color scheme.  In
 139 the GUI use the Edit/Color Scheme menu.  You can also type the command: >
 140
 141         :colorscheme evening
 142
 143 "evening" is the name of the color scheme.  There are several others you might
 144 want to try out.  Look in the directory $VIMRUNTIME/colors.
 145
 146 When you found the color scheme that you like, add the ":colorscheme" command
 147 to your |vimrc| file.
 148
 149 You could also write your own color scheme.  This is how you do it:
 150
 151 1. Select a color scheme that comes close.  Copy this file to your own Vim
 152    directory.  For Unix, this should work: >
 153
 154         !mkdir ~/.vim/colors
 155         !cp $VIMRUNTIME/colors/morning.vim ~/.vim/colors/mine.vim
 156 <
 157    This is done from Vim, because it knows the value of $VIMRUNTIME.
 158
 159 2. Edit the color scheme file.  These entries are useful:
 160
 161         term            attributes in a B&W terminal
 162         cterm           attributes in a color terminal
 163         ctermfg         foreground color in a color terminal
 164         ctermbg         background color in a color terminal
 165         gui             attributes in the GUI
 166         guifg           foreground color in the GUI
 167         guibg           background color in the GUI
 168
 169    For example, to make comments green: >
 170
 171         :highlight Comment ctermfg=green guifg=green
 172 <
 173    Attributes you can use for "cterm" and "gui" are "bold" and "underline".
 174    If you want both, use "bold,underline".  For details see the |:highlight|
 175    command.
 176
 177 3. Tell Vim to always use your color scheme.  Put this line in your |vimrc|: >
 178
 179         colorscheme mine
 180
 181 If you want to see what the most often used color combinations look like, use
 182 this command: >
 183
 184         :runtime syntax/colortest.vim
 185
 186 You will see text in various color combinations.  You can check which ones are
 187 readable and look nice.
 188
 189 ==============================================================================
 190 *06.4*  With colors or without colors
 191
 192 Displaying text in color takes a lot of effort.  If you find the displaying
 193 too slow, you might want to disable syntax highlighting for a moment: >
 194
 195         :syntax clear
 196
 197 When editing another file (or the same one) the colors will come back.
 198
 199                                                         *:syn-off*
 200 If you want to stop highlighting completely use: >
 201
 202         :syntax off
 203
 204 This will completely disable syntax highlighting and remove it immediately for
 205 all buffers.
 206
 207                                                         *:syn-manual*
 208 If you want syntax highlighting only for specific files, use this: >
 209
 210         :syntax manual
 211
 212 This will enable the syntax highlighting, but not switch it on automatically
 213 when starting to edit a buffer.  To switch highlighting on for the current
 214 buffer, set the 'syntax' option: >
 215
 216         :set syntax=ON
 217 <
 218 ==============================================================================
 219 *06.5*  Printing with colors                            *syntax-printing*
 220
 221 In the MS-Windows version you can print the current file with this command: >
 222
 223         :hardcopy
 224
 225 You will get the usual printer dialog, where you can select the printer and a
 226 few settings.  If you have a color printer, the paper output should look the
 227 same as what you see inside Vim.  But when you use a dark background the
 228 colors will be adjusted to look good on white paper.
 229
 230 There are several options that change the way Vim prints:
 231         'printdevice'
 232         'printheader'
 233         'printfont'
 234         'printoptions'
 235
 236 To print only a range of lines,  use Visual mode to select the lines and then
 237 type the command: >
 238
 239         v100j:hardcopy
 240
 241 "v" starts Visual mode.  "100j" moves a hundred lines down, they will be
 242 highlighted.  Then ":hardcopy" will print those lines.  You can use other
 243 commands to move in Visual mode, of course.
 244
 245 This also works on Unix, if you have a PostScript printer.  Otherwise, you
 246 will have to do a bit more work.  You need to convert the text to HTML first,
 247 and then print it from a web browser.
 248
 249 Convert the current file to HTML with this command: >
 250
 251         :TOhtml
 252
 253 In case that doesn't work: >
 254
 255         :source $VIMRUNTIME/syntax/2html.vim
 256
 257 You will see it crunching away, this can take quite a while for a large file.
 258 Some time later another window shows the HTML code.  Now write this somewhere
 259 (doesn't matter where, you throw it away later):
 260 >
 261         :write main.c.html
 262
 263 Open this file in your favorite browser and print it from there.  If all goes
 264 well, the output should look exactly as it does in Vim.  See |2html.vim| for
 265 details.  Don't forget to delete the HTML file when you are done with it.
 266
 267 Instead of printing, you could also put the HTML file on a web server, and let
 268 others look at the colored text.
 269
 270 ==============================================================================
 271 *06.6*  Further reading
 272
 273 |usr_44.txt|  Your own syntax highlighted.
 274 |syntax|      All the details.
 275
 276 ==============================================================================
 277
 278 Next chapter: |usr_07.txt|  Editing more than one file
 279
 280 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: