--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 7.2.  Last change: 2008 Nov 27
+*eval.txt*	For Vim version 7.2.  Last change: 2010 Jan 05
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -853,7 +853,8 @@ expr8[expr1]		item of String or |List|	*
 
 If expr8 is a Number or String this results in a String that contains the
 expr1'th single byte from expr8.  expr8 is used as a String, expr1 as a
-Number.  Note that this doesn't recognize multi-byte encodings.
+Number.  This doesn't recognize multi-byte encodings, see |byteidx()| for
+an alternative.
 
 Index zero gives the first character.  This is like it works in C.  Careful:
 text column numbers start with one!  Example, to get the character under the
@@ -878,8 +879,8 @@ expr8[expr1a : expr1b]	substring or subl
 
 If expr8 is a Number or String this results in the substring with the bytes
 from expr1a to and including expr1b.  expr8 is used as a String, expr1a and
-expr1b are used as a Number.  Note that this doesn't recognize multi-byte
-encodings.
+expr1b are used as a Number.  This doesn't recognize multi-byte encodings, see
+|byteidx()| for computing the indexes.
 
 If expr1a is omitted zero is used.  If expr1b is omitted the length of the
 string minus one is used.
@@ -895,7 +896,8 @@ Examples: >
 	:let c = name[-2:-2]		" last but one byte of a string
 	:let s = line(".")[4:]		" from the fifth byte to the end
 	:let s = s[:-3]			" remove last two bytes
-
+<
+							*sublist* *slice*
 If expr8 is a |List| this results in a new |List| with the items indicated by
 the indexes expr1a and expr1b.	This works like with a String, as explained
 just above, except that indexes out of range cause an error.  Examples: >
@@ -1190,6 +1192,7 @@ They can be used in:
 Thus not in:
 - other scripts sourced from this one
 - mappings
+- menus
 - etc.
 
 Script variables can be used to avoid conflicts with global variable names.
@@ -1280,7 +1283,8 @@ v:beval_winnr	The number of the window, 
 		valid while evaluating the 'balloonexpr' option.
 
 					*v:char* *char-variable*
-v:char		Argument for evaluating 'formatexpr'.
+v:char		Argument for evaluating 'formatexpr' and used for the typed
+		character when using <expr> in an abbreviation |map-<expr>|.
 
 			*v:charconvert_from* *charconvert_from-variable*
 v:charconvert_from
@@ -1317,6 +1321,8 @@ v:count		The count given for the last No
 	:map _x :<C-U>echo "the count is " . v:count<CR>
 <		Note: The <C-U> is required to remove the line range that you
 		get when typing ':' after a count.
+		When there are two counts, as in "3d2w", they are multiplied,
+		just like what happens in the command, "d6w" for the example.
 		Also used for evaluating the 'formatexpr' option.
 		"count" also works, for backwards compatibility.
 
@@ -1677,9 +1683,9 @@ ceil( {expr})			Float	round {expr} up
 changenr()			Number	current change number
 char2nr( {expr})		Number	ASCII value of first char in {expr}
 cindent( {lnum})		Number	C indent for line {lnum}
-clearmatches()			None	clear all matches
+clearmatches()			none	clear all matches
 col( {expr})			Number	column nr of cursor or mark
-complete({startcol}, {matches})	String	set Insert mode completion
+complete( {startcol}, {matches}) none	set Insert mode completion
 complete_add( {expr})		Number	add completion match
 complete_check()		Number	check for key typed during completion
 confirm( {msg} [, {choices} [, {default} [, {type}]]])
@@ -1704,7 +1710,7 @@ eval( {string})			any	evaluate {string} 
 eventhandler( )			Number	TRUE if inside an event handler
 executable( {expr})		Number	1 if executable {expr} exists
 exists( {expr})			Number	TRUE if {expr} exists
-extend({expr1}, {expr2} [, {expr3}])
+extend( {expr1}, {expr2} [, {expr3}])
 				List/Dict insert items of {expr2} into {expr1}
 expand( {expr} [, {flag}])	String	expand special keywords in {expr}
 feedkeys( {string} [, {mode}])	Number	add key sequence to typeahead buffer
@@ -1746,7 +1752,7 @@ getftime( {fname})		Number	last modifica
 getftype( {fname})		String	description of type of file {fname}
 getline( {lnum})		String	line {lnum} of current buffer
 getline( {lnum}, {end})		List	lines {lnum} to {end} of current buffer
-getloclist({nr})		List	list of location list items
+getloclist( {nr})		List	list of location list items
 getmatches()			List	list of current matches
 getpid()			Number	process ID of Vim
 getpos( {expr})			List	position of cursor, mark, etc.
@@ -1815,9 +1821,9 @@ matchlist( {expr}, {pat}[, {start}[, {co
 				List	match and submatches of {pat} in {expr}
 matchstr( {expr}, {pat}[, {start}[, {count}]])
 				String	{count}'th match of {pat} in {expr}
-max({list})			Number	maximum value of items in {list}
-min({list})			Number	minimum value of items in {list}
-mkdir({name} [, {path} [, {prot}]])
+max( {list})			Number	maximum value of items in {list}
+min( {list})			Number	minimum value of items in {list}
+mkdir( {name} [, {path} [, {prot}]])
 				Number	create directory {name}
 mode( [expr])			String	current editing mode
 nextnonblank( {lnum})		Number	line nr of non-blank line >= {lnum}
@@ -1829,7 +1835,7 @@ printf( {fmt}, {expr1}...)	String	format
 pumvisible()			Number	whether popup menu is visible
 range( {expr} [, {max} [, {stride}]])
 				List	items from {expr} to {max}
-readfile({fname} [, {binary} [, {max}]])
+readfile( {fname} [, {binary} [, {max}]])
 				List	get list of lines from file {fname}
 reltime( [{start} [, {end}]])	List	get time value
 reltimestr( {time})		String	turn time value into a String
@@ -1850,7 +1856,7 @@ reverse( {list})		List	reverse {list} in
 round( {expr})			Float	round off {expr}
 search( {pattern} [, {flags} [, {stopline} [, {timeout}]]])
 				Number	search for {pattern}
-searchdecl({name} [, {global} [, {thisblock}]])
+searchdecl( {name} [, {global} [, {thisblock}]])
 				Number	search for variable declaration
 searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]])
 				Number	search for other end of start/end pair
@@ -1867,7 +1873,7 @@ setline( {lnum}, {line})	Number	set line
 setloclist( {nr}, {list}[, {action}])
 				Number	modify location list using {list}
 setmatches( {list})		Number	restore a list of matches
-setpos( {expr}, {list})		none	set the {expr} position to {list}
+setpos( {expr}, {list})		Number	set the {expr} position to {list}
 setqflist( {list}[, {action}])	Number	modify quickfix list using {list}
 setreg( {n}, {v}[, {opt}])	Number	set register to value and type
 settabwinvar( {tabnr}, {winnr}, {varname}, {val})    set {varname} in window
@@ -1905,7 +1911,7 @@ synID( {lnum}, {col}, {trans})	Number	sy
 synIDattr( {synID}, {what} [, {mode}])
 				String	attribute {what} of syntax ID {synID}
 synIDtrans( {synID})		Number	translated syntax ID of {synID}
-synstack({lnum}, {col})		List	stack of syntax IDs at {lnum} and {col}
+synstack( {lnum}, {col})	List	stack of syntax IDs at {lnum} and {col}
 system( {expr} [, {input}])	String	output of shell command/filter {expr}
 tabpagebuflist( [{arg}])	List	list of buffer numbers in tab page
 tabpagenr( [{arg}])		Number	number of current or last tab page
@@ -1929,10 +1935,10 @@ winheight( {nr})		Number	height of windo
 winline()			Number	window line of the cursor
 winnr( [{expr}])		Number	number of current window
 winrestcmd()			String	returns command to restore window sizes
-winrestview({dict})		None	restore view of current window
+winrestview( {dict})		none	restore view of current window
 winsaveview()			Dict	save view of current window
 winwidth( {nr})			Number	width of window {nr}
-writefile({list}, {fname} [, {binary}])
+writefile( {list}, {fname} [, {binary}])
 				Number	write list of lines to file {fname}
 
 abs({expr})							*abs()*
@@ -2245,7 +2251,7 @@ complete({startcol}, {matches})			*compl
 		{matches} must be a |List|.  Each |List| item is one match.
 		See |complete-items| for the kind of items that are possible.
 		Note that the after calling this function you need to avoid
-		inserting anything that would completion to stop.
+		inserting anything that would cause completion to stop.
 		The match can be selected with CTRL-N and CTRL-P as usual with
 		Insert mode completion.  The popup menu will appear if
 		specified, see |ins-completion-menu|.
@@ -2477,7 +2483,7 @@ empty({expr})						*empty()*
 		Return the Number 1 if {expr} is empty, zero otherwise.
 		A |List| or |Dictionary| is empty when it does not have any
 		items.	A Number is empty when its value is zero.
-		For a long |List| this is much faster then comparing the
+		For a long |List| this is much faster than comparing the
 		length with zero.
 
 escape({string}, {chars})				*escape()*
@@ -3053,7 +3059,7 @@ getcharmod()						*getcharmod()*
 			128	Macintosh only: command
 		Only the modifiers that have not been included in the
 		character itself are obtained.	Thus Shift-a results in "A"
-		with no modifier.
+		without a modifier.
 
 getcmdline()						*getcmdline()*
 		Return the current command-line.  Only works when the command
@@ -3181,7 +3187,7 @@ getloclist({nr})					*getloclist()*
 		window {nr}. When {nr} is zero the current window is used.
 		For a location list window, the displayed location list is
 		returned.  For an invalid window number {nr}, an empty list is
-		returned. Otherwise, same as getqflist().
+		returned. Otherwise, same as |getqflist()|.
 
 getmatches()						*getmatches()*
 		Returns a |List| with all matches previously defined by
@@ -3478,7 +3484,9 @@ hostname()						*hostname()*
 iconv({expr}, {from}, {to})				*iconv()*
 		The result is a String, which is the text {expr} converted
 		from encoding {from} to encoding {to}.
-		When the conversion fails an empty string is returned.
+		When the conversion completely fails an empty string is
+		returned.  When some characters could not be converted they
+		are replaced with "?".
 		The encoding names are whatever the iconv() library function
 		can accept, see ":!man 3 iconv".
 		Most conversions require Vim to be compiled with the |+iconv|
@@ -3503,7 +3511,10 @@ indent({lnum})	The result is a Number, w
 
 index({list}, {expr} [, {start} [, {ic}]])			*index()*
 		Return the lowest index in |List| {list} where the item has a
-		value equal to {expr}.
+		value equal to {expr}.  There is no automatic conversion, so
+		the String "4" is different from the Number 4.  And the number
+		4 is different from the Float 4.0.  The value of 'ignorecase'
+		is not used here, case always matters.
 		If {start} is given then start looking at the item with index
 		{start} (may be negative for an item relative to the end).
 		When {ic} is given and it is non-zero, ignore case.  Otherwise
@@ -3516,9 +3527,9 @@ index({list}, {expr} [, {start} [, {ic}]
 
 input({prompt} [, {text} [, {completion}]])		*input()*
 		The result is a String, which is whatever the user typed on
-		the command-line.  The parameter is either a prompt string, or
-		a blank string (for no prompt).  A '\n' can be used in the
-		prompt to start a new line.
+		the command-line.  The {prompt} argument is either a prompt
+		string, or a blank string (for no prompt).  A '\n' can be used
+		in the prompt to start a new line.
 		The highlighting set with |:echohl| is used for the prompt.
 		The input is entered just like a command-line, with the same
 		editing commands and mappings.	There is a separate history
@@ -3528,8 +3539,9 @@ input({prompt} [, {text} [, {completion}
 			:  echo "Cheers!"
 			:endif
 <
-		If the optional {text} is present and not empty, this is used
-		for the default reply, as if the user typed this.  Example: >
+		If the optional {text} argument is present and not empty, this
+		is used for the default reply, as if the user typed this.
+		Example: >
 			:let color = input("Color? ", "white")
 
 <		The optional {completion} argument specifies the type of
@@ -3559,8 +3571,8 @@ input({prompt} [, {text} [, {completion}
 			:endfunction
 
 inputdialog({prompt} [, {text} [, {cancelreturn}]])		*inputdialog()*
-		Like input(), but when the GUI is running and text dialogs are
-		supported, a dialog window pops up to input the text.
+		Like |input()|, but when the GUI is running and text dialogs
+		are supported, a dialog window pops up to input the text.
 		Example: >
 			:let n = inputdialog("value for shiftwidth", &sw)
 			:if n != ""
@@ -3581,7 +3593,7 @@ inputlist({textlist})					*inputlist()*
 		above the first item a negative number is returned.  When
 		clicking on the prompt one more than the length of {textlist}
 		is returned.
-		Make sure {textlist} has less then 'lines' entries, otherwise
+		Make sure {textlist} has less than 'lines' entries, otherwise
 		it won't work.	It's a good idea to put the entry number at
 		the start of the string.  And put a prompt in the first item.
 		Example: >
@@ -3589,7 +3601,7 @@ inputlist({textlist})					*inputlist()*
 				\ '2. green', '3. blue'])
 
 inputrestore()						*inputrestore()*
-		Restore typeahead that was saved with a previous inputsave().
+		Restore typeahead that was saved with a previous |inputsave()|.
 		Should be called the same number of times inputsave() is
 		called.  Calling it more often is harmless though.
 		Returns 1 when there is nothing to restore, 0 otherwise.
@@ -3719,14 +3731,14 @@ libcall({libname}, {funcname}, {argument
 		the DLL is not in the usual places.
 		For Unix: When compiling your own plugins, remember that the
 		object code must be compiled as position-independent ('PIC').
-		{only in Win32 on some Unix versions, when the |+libcall|
+		{only in Win32 and some Unix versions, when the |+libcall|
 		feature is present}
 		Examples: >
 			:echo libcall("libc.so", "getenv", "HOME")
 <
 							*libcallnr()*
 libcallnr({libname}, {funcname}, {argument})
-		Just like libcall(), but used for a function that returns an
+		Just like |libcall()|, but used for a function that returns an
 		int instead of a string.
 		{only in Win32 on some Unix versions, when the |+libcall|
 		feature is present}
@@ -3759,7 +3771,7 @@ line({expr})	The result is a Number, whi
 <							*last-position-jump*
 		This autocommand jumps to the last known position in a file
 		just after opening it, if the '" mark is set: >
-	:au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif
+	:au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif
 
 line2byte({lnum})					*line2byte()*
 		Return the byte count from the start of the buffer for line
@@ -3990,8 +4002,8 @@ matchdelete({id})			       *matchdelete(
 		be deleted in one operation by |clearmatches()|.
 
 matchend({expr}, {pat}[, {start}[, {count}]])			*matchend()*
-		Same as match(), but return the index of first character after
-		the match.  Example: >
+		Same as |match()|, but return the index of first character
+		after the match.  Example: >
 			:echo matchend("testing", "ing")
 <		results in "7".
 							*strspn()* *strcspn()*
@@ -4001,15 +4013,15 @@ matchend({expr}, {pat}[, {start}[, {coun
 			:let span = matchend(line, '[^a-zA-Z]')
 <		Except that -1 is returned when there are no matches.
 
-		The {start}, if given, has the same meaning as for match(). >
+		The {start}, if given, has the same meaning as for |match()|. >
 			:echo matchend("testing", "ing", 2)
 <		results in "7". >
 			:echo matchend("testing", "ing", 5)
 <		result is "-1".
-		When {expr} is a |List| the result is equal to match().
+		When {expr} is a |List| the result is equal to |match()|.
 
 matchlist({expr}, {pat}[, {start}[, {count}]])			*matchlist()*
-		Same as match(), but return a |List|.  The first item in the
+		Same as |match()|, but return a |List|.  The first item in the
 		list is the matched string, same as what matchstr() would
 		return.  Following items are submatches, like "\1", "\2", etc.
 		in |:substitute|.  When an optional submatch didn't match an
@@ -4023,7 +4035,7 @@ matchstr({expr}, {pat}[, {start}[, {coun
 			:echo matchstr("testing", "ing")
 <		results in "ing".
 		When there is no match "" is returned.
-		The {start}, if given, has the same meaning as for match(). >
+		The {start}, if given, has the same meaning as for |match()|. >
 			:echo matchstr("testing", "ing", 2)
 <		results in "ing". >
 			:echo matchstr("testing", "ing", 5)
@@ -4497,9 +4509,9 @@ remote_send({server}, {string} [, {idvar
 <
 remove({list}, {idx} [, {end}])				*remove()*
 		Without {end}: Remove the item at {idx} from |List| {list} and
-		return it.
+		return the item.
 		With {end}: Remove items from {idx} to {end} (inclusive) and
-		return a list with these items.  When {idx} points to the same
+		return a List with these items.  When {idx} points to the same
 		item as {end} a list with one item is returned.  When {end}
 		points to an item before {idx} this is an error.
 		See |list-index| for possible values of {idx} and {end}.
@@ -4750,7 +4762,7 @@ searchpair({start}, {middle}, {end} [, {
 							*searchpairpos()*
 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
 				[, {stopline} [, {timeout}]]]])
-		Same as searchpair(), but returns a |List| with the line and
+		Same as |searchpair()|, but returns a |List| with the line and
 		column position of the match. The first element of the |List|
 		is the line number and the second element is the byte index of
 		the column position of the match.  If no match is found,
@@ -4870,7 +4882,8 @@ setpos({expr}, {list})
 		Does not change the jumplist.
 
 		"lnum" and "col" are the position in the buffer.  The first
-		column is 1.  Use a zero "lnum" to delete a mark.
+		column is 1.  Use a zero "lnum" to delete a mark.  If "col" is
+		smaller than 1 then 1 is used.
 
 		The "off" number is only used when 'virtualedit' is set. Then
 		it is the offset in screen columns from the start of the
@@ -4989,7 +5002,7 @@ setwinvar({nr}, {varname}, {val})			*set
 			:call setwinvar(2, "myvar", "foobar")
 
 shellescape({string} [, {special}])			*shellescape()*
-		Escape {string} for use as shell command argument.
+		Escape {string} for use as a shell command argument.
 		On MS-Windows and MS-DOS, when 'shellslash' is not set, it
 		will enclose {string} in double quotes and double all double
 		quotes within {string}.
@@ -5051,15 +5064,20 @@ sort({list} [, {func}])					*sort()* *E7
 		When {func} is given and it is one then case is ignored.
 		When {func} is a |Funcref| or a function name, this function
 		is called to compare items.  The function is invoked with two
-		items as argument and must return zero if they are equal, 1 if
-		the first one sorts after the second one, -1 if the first one
-		sorts before the second one.  Example: >
+		items as argument and must return zero if they are equal, 1 or
+		bigger if the first one sorts after the second one, -1 or
+		smaller if the first one sorts before the second one.
+		Example: >
 			func MyCompare(i1, i2)
 			   return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
 			endfunc
 			let sortedlist = sort(mylist, "MyCompare")
+<		A shorter compare version for this specific simple case, which
+		ignores overflow: >
+			func MyCompare(i1, i2)
+			   return a:i1 - a:i2
+			endfunc
 <
-
 							*soundfold()*
 soundfold({word})
 		Return the sound-folded equivalent of {word}.  Uses the first
@@ -5508,10 +5526,7 @@ tempname()					*tempname()* *temp-file-n
 		is different for at least 26 consecutive calls.  Example: >
 			:let tmpfile = tempname()
 			:exe "redir > " . tmpfile
-<		For Unix, the file will be in a private directory (only
-		accessible by the current user) to avoid security problems
-		(e.g., a symlink attack or other people reading your file).
-		When Vim exits the directory and all files in it are deleted.
+<		For Unix, the file will be in a private directory |tempfile|.
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 
@@ -6575,15 +6590,19 @@ 7. Commands						*expression-commands*
 			removed without effect.  Removing any later item means
 			it will not be found.  Thus the following example
 			works (an inefficient way to make a list empty): >
-				:for item in mylist
-				   :call remove(mylist, 0)
-				:endfor
+				for item in mylist
+				   call remove(mylist, 0)
+				endfor
 <			Note that reordering the list (e.g., with sort() or
 			reverse()) may have unexpected effects.
 			Note that the type of each list item should be
 			identical to avoid errors for the type of {var}
 			changing.  Unlet the variable at the end of the loop
-			to allow multiple item types.
+			to allow multiple item types: >
+				for item in ["foo", ["bar"]]
+				   echo item
+				   unlet item  " E706 without this
+				endfor
 
 :for [{var1}, {var2}, ...] in {listlist}
 :endfo[r]
@@ -6652,7 +6671,7 @@ 7. Commands						*expression-commands*
 		:try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
 <
 					*:cat* *:catch* *E603* *E604* *E605*
-:cat[ch] /{pattern}/	The following commands until the next ":catch",
+:cat[ch] /{pattern}/	The following commands until the next |:catch|,
 			|:finally|, or |:endtry| that belongs to the same
 			|:try| as the ":catch" are executed when an exception
 			matching {pattern} is being thrown and has not yet
@@ -6825,7 +6844,7 @@ 7. Commands						*expression-commands*
 		:execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
 <
 
-							*:comment*
+							*:exe-comment*
 			":execute", ":echo" and ":echon" cannot be followed by
 			a comment directly, because they see the '"' as the
 			start of a string.  But, you can use '|' followed by a
@@ -7831,7 +7850,7 @@ 9. Examples						*eval-examples*
 
 Printing in Binary ~
 >
-  :" The function Nr2Bin() returns the Hex string of a number.
+  :" The function Nr2Bin() returns the binary string representation of a number.
   :func Nr2Bin(nr)
   :  let n = a:nr
   :  let r = ""