vim: runtime/doc/syntax.txt comparison

comparison runtime/doc/syntax.txt @ 2033:de5a43c5eedc

Update documentation files.

author	Bram Moolenaar <bram@zimbu.org>
date	Wed, 06 Jan 2010 20:52:26 +0100
parents	5232b9862f23
children	b9e314fe473f

comparison

equal deleted inserted replaced

-:592032e9e167
+:de5a43c5eedc
-*syntax.txt*	For Vim version 7.2.  Last change: 2008 Jul 22
+*syntax.txt*	For Vim version 7.2.  Last change: 2009 Dec 19
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 :syntax on		$VIMRUNTIME/syntax/syntax.vim
 :syntax manual	$VIMRUNTIME/syntax/manual.vim
 :syntax off		$VIMRUNTIME/syntax/nosyntax.vim
 Also see |syntax-loading|.
+NOTE: If displaying long lines is slow and switching off syntax highlighting
+makes it fast, consider setting the 'synmaxcol' option to a lower value.
 ==============================================================================
 2. Syntax files						*:syn-files*
 The syntax and highlighting commands for one language are normally stored in
 a syntax file.	The name convention is: "{name}.vim".  Where {name} is the
 version, follow the same steps as for |mysyntaxfile| above.  Just make sure
 that you write the syntax file in a directory that is early in 'runtimepath'.
 Vim will only load the first syntax file found.
-NAMING CONVENTIONS
+NAMING CONVENTIONS		    *group-name* *{group-name}* *E669* *W18*
-				    *group-name* *{group-name}* *E669* *W18*
+A syntax group name is to be used for syntax items that match the same kind of
+thing.  These are then linked to a highlight group that specifies the color.
+A syntax group name doesn't specify any color or attributes itself.
 The name for a highlight or syntax group must consist of ASCII letters, digits
 and the underscore.  As a regexp: "[a-zA-Z0-9_]*"
 To be able to allow each user to pick his favorite set of colors, there must
 be preferred names for highlight groups that are common for many languages.
 Or use the ":TOhtml" user command.  It is defined in a standard plugin.
 ":TOhtml" also works with a range and in a Visual area: >
 	:10,40TOhtml
-After you save the resulting file, you can view it with any HTML viewer, such
+After you save the resulting file, you can view it with any browser.  The
-as Netscape.  The colors should be exactly the same as you see them in Vim.
+colors should be exactly the same as you see them in Vim.
 To restrict the conversion to a range of lines set "html_start_line" and
 "html_end_line" to the first and last line to be converted.  Example, using
 the last set Visual area: >
 Force to omit the line numbers by using a zero value: >
 :let html_number_lines = 0
 Go back to the default to use 'number' by deleting the variable: >
 :unlet html_number_lines
-Closed folds are put in the HTML as they are displayed.  If you don't want
-this, use the |zR| command before invoking 2html, or use: >
-:let html_ignore_folding = 1
 By default, HTML optimized for old browsers is generated.  If you prefer using
 cascading style sheets (CSS1) for the attributes (resulting in considerably
 shorter and valid HTML 4 file), use: >
 :let html_use_css = 1
+Closed folds are put in the HTML as they are displayed.  If you don't want
+this, use the |zR| command before invoking 2html, or use: >
+:let html_ignore_folding = 1
+You may want to generate HTML that includes all the data within the folds, and
+allow the user to view the folded data similar to how they would in Vim. To
+generate this dynamic fold information, use: >
+:let html_dynamic_folds = 1
+Using html_dynamic_folds will imply html_use_css, because it would be far too
+difficult to do it for old browsers. However, html_ignore_folding overrides
+html_dynamic_folds.
+Using html_dynamic_folds will default to generating a foldcolumn in the html
+similar to Vim's foldcolumn, that will use javascript to open and close the
+folds in the HTML document. The width of this foldcolumn starts at the current
+setting of |'foldcolumn'| but grows to fit the greatest foldlevel in your
+document. If you do not want to show a foldcolumn at all, use: >
+:let html_no_foldcolumn = 1
+Using this option, there will be no foldcolumn available to open the folds in
+the HTML. For this reason, another option is provided: html_hover_unfold.
+Enabling this option will use CSS 2.0 to allow a user to open a fold by
+hovering the mouse pointer over it. Note that old browsers (notably Internet
+Explorer 6) will not support this feature.  Browser-specific markup for IE6 is
+included to fall back to the normal CSS1 code so that the folds show up
+correctly for this browser, but they will not be openable without a
+foldcolumn. Note that using html_hover_unfold will allow modern browsers with
+disabled javascript to view closed folds. To use this option, use: >
+:let html_hover_unfold = 1
+Setting html_no_foldcolumn with html_dynamic_folds will automatically set
+html_hover_unfold, because otherwise the folds wouldn't be dynamic.
 By default "<pre>" and "</pre>" is used around the text.  This makes it show
 up as you see it in Vim, but without wrapping.	If you prefer wrapping, at the
 risk of making some things look a bit different, use: >
 :let html_no_pre = 1
 	tasm		Turbo Assembly (with opcodes 80x86 up to Pentium, and
 			MMX)
 	pic		PIC assembly (currently for PIC16F84)
 The most flexible is to add a line in your assembly file containing: >
-	:asmsyntax=nasm
+	asmsyntax=nasm
 Replace "nasm" with the name of the real assembly syntax.  This line must be
-one of the first five lines in the file.
+one of the first five lines in the file.  No non-white text must be
+immediately before or after this text.
 The syntax type can always be overruled for a specific buffer by setting the
 b:asmsyntax variable: >
 	:let b:asmsyntax = "nasm"
 If you notice highlighting errors while scrolling backwards, which are fixed
 when redrawing with CTRL-L, try setting the "tcsh_minlines" internal variable
 to a larger number: >
-	:let tcsh_minlines = 100
+	:let tcsh_minlines = 1000
-This will make the syntax synchronization start 100 lines before the first
+This will make the syntax synchronization start 1000 lines before the first
-displayed line.  The default value is 15.  The disadvantage of using a larger
+displayed line.  If you set "tcsh_minlines" to "fromstart", then
-number is that redrawing can become slow.
+synchronization is done from the start of the file. The default value for
+tcsh_minlines is 100.  The disadvantage of using a larger number is that
+redrawing can become slow.
 TEX						*tex.vim* *ft-tex-syntax*
 								*tex-folding*
 - There must be no white space between the pattern and the character
 offset(s).
 - The highlighted area will never be outside of the matched text.
 - A negative offset for an end pattern may not always work, because the end
 pattern may be detected when the highlighting should already have stopped.
-- Until Vim 7.2 the offsets were counted in bytes instead of characters.  This
+- Before Vim 7.2 the offsets were counted in bytes instead of characters.
-didn't work well for multi-byte characters.
+This didn't work well for multi-byte characters, so it was changed with the
+Vim 7.2 release.
 - The start of a match cannot be in a line other than where the pattern
 matched.  This doesn't work: "a\nb"ms=e.  You can make the highlighting
 start in another line, this does work: "a\nb"hs=e.
 Example (match a comment but don't highlight the /* and */): >
 The patterns can include "\n" to match an end-of-line.	Mostly this works as
 expected, but there are a few exceptions.
 When using a start pattern with an offset, the start of the match is not
 allowed to start in a following line.  The highlighting can start in a
-following line though.
+following line though.  Using the "\zs" item also requires that the start of
+the match doesn't move to another line.
 The skip pattern can include the "\n", but the search for an end pattern will
 continue in the first character of the next line, also when that character is
 matched by the skip pattern.  This is because redrawing may start in any line
 halfway a region and there is no check if the skip pattern started in a
 						*:colo* *:colorscheme* *E185*
 :colo[rscheme] {name}	Load color scheme {name}.  This searches 'runtimepath'
 			for the file "colors/{name}.vim.  The first one that
 			is found is loaded.
-			To see the name of the currently active color scheme
+			To see the name of the currently active color scheme: >
-			(if there is one): >
 				:echo g:colors_name
-<			Doesn't work recursively, thus you can't use
+<			When using the default colors you will get an E121
+			error.
+			Doesn't work recursively, thus you can't use
 			":colorscheme" in a color scheme script.
 			After the color scheme has been loaded the
 			|ColorScheme| autocommand event is triggered.
 			For info about writing a colorscheme file: >
 				:edit $VIMRUNTIME/colors/README.txt
 	highlight groups that depend on 'background' to change!  This means
 	you should set the colors for Normal first, before setting other
 	colors.
 	When a colorscheme is being used, changing 'background' causes it to
 	be reloaded, which may reset all colors (including Normal).  First
-	delete the "colors_name" variable when you don't want this.
+	delete the "g:colors_name" variable when you don't want this.
 	When you have set "ctermfg" or "ctermbg" for the Normal group, Vim
 	needs to reset the color when exiting.	This is done with the "op"
 	termcap entry |t_op|.  If this doesn't work correctly, try setting the
 	't_op' option in your .vimrc.

Mercurial > vim

comparison runtime/doc/syntax.txt @ 2033:de5a43c5eedc