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

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

1 files changed, 643 insertions, 0 deletions

diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt
new file mode 100644
index 0000000..a23df96
--- /dev/null
+++ b/runtime/doc/usr_30.txt
@@ -0,0 +1,643 @@
+*usr_30.txt*	For Vim version 9.0.  Last change: 2007 Nov 10
+
+		     VIM USER MANUAL - by Bram Moolenaar
+
+			      Editing programs
+
+
+Vim has various commands that aid in writing computer programs.  Compile a
+program and directly jump to reported errors.  Automatically set the indent
+for many languages and format comments.
+
+|30.1|	Compiling
+|30.2|	Indenting C files
+|30.3|	Automatic indenting
+|30.4|	Other indenting
+|30.5|	Tabs and spaces
+|30.6|	Formatting comments
+
+     Next chapter: |usr_31.txt|  Exploiting the GUI
+ Previous chapter: |usr_29.txt|  Moving through programs
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*30.1*	Compiling
+
+Vim has a set of so called "quickfix" commands.  They enable you to compile a
+program from within Vim and then go through the errors generated and fix them
+(hopefully).  You can then recompile and fix any new errors that are found
+until finally your program compiles without any error.
+
+The following command runs the program "make" (supplying it with any argument
+you give) and captures the results: >
+
+	:make {arguments}
+
+If errors were generated, they are captured and the editor positions you where
+the first error occurred.
+   Take a look at an example ":make" session.  (Typical :make sessions generate
+far more errors and fewer stupid ones.)  After typing ":make" the screen looks
+like this:
+
+	:!make | &tee /tmp/vim215953.err ~
+	gcc -g -Wall -o prog main.c sub.c ~
+	main.c: In function 'main': ~
+	main.c:6: too many arguments to function 'do_sub' ~
+	main.c: At top level: ~
+	main.c:10: parse error before '}' ~
+	make: *** [prog] Error 1 ~
+
+	2 returned ~
+	"main.c" 11L, 111C ~
+	(3 of 6): too many arguments to function 'do_sub' ~
+	Press ENTER or type command to continue ~
+
+From this you can see that you have errors in the file "main.c".  When you
+press <Enter>, Vim displays the file "main.c", with the cursor positioned on
+line 6, the first line with an error.  You did not need to specify the file or
+the line number, Vim knew where to go by looking in the error messages.
+
+		+---------------------------------------------------+
+		|int main()					    |
+		|{						    |
+		|	int i=3;				    |
+      cursor -> |	do_sub("foo");				    |
+		|	++i;					    |
+		|	return (0);				    |
+		|}						    |
+		|}						    |
+		| ~						    |
+		|(3 of 12): too many arguments to function 'do_sub' |
+		+---------------------------------------------------+
+
+The following command goes to where the next error occurs: >
+
+	:cnext
+
+Vim jumps to line 10, the last line in the file, where there is an extra '}'.
+   When there is not enough room, Vim will shorten the error message.  To see
+the whole message use: >
+
+	:cc
+
+You can get an overview of all the error messages with the ":clist" command.
+The output looks like this: >
+
+	:clist
+<	3 main.c: 6:too many arguments to function 'do_sub' ~
+	5 main.c: 10:parse error before '}' ~
+
+Only the lines where Vim recognized a file name and line number are listed
+here.  It assumes those are the interesting lines and the rest is just boring
+messages.  However, sometimes unrecognized lines do contain something you want
+to see.  Output from the linker, for example, about an undefined function.
+To see all the messages add a "!" to the command: >
+
+	:clist!
+<	1 gcc -g -Wall -o prog main.c sub.c ~
+	2 main.c: In function 'main': ~
+	3 main.c:6: too many arguments to function 'do_sub' ~
+	4 main.c: At top level: ~
+	5 main.c:10: parse error before '}' ~
+	6 make: *** [prog] Error 1 ~
+
+Vim will highlight the current error.  To go back to the previous error, use:
+>
+	:cprevious
+
+Other commands to move around in the error list:
+
+	:cfirst		to first error
+	:clast		to last error
+	:cc 3		to error nr 3
+
+
+USING ANOTHER COMPILER
+
+The name of the program to run when the ":make" command is executed is defined
+by the 'makeprg' option.  Usually this is set to "make", but Visual C++ users
+should set this to "nmake" by executing the following command: >
+
+	:set makeprg=nmake
+
+You can also include arguments in this option.  Special characters need to
+be escaped with a backslash.  Example: >
+
+	:set makeprg=nmake\ -f\ project.mak
+
+You can include special Vim keywords in the command specification.  The %
+character expands to the name of the current file.  So if you execute the
+command: >
+	:set makeprg=make\ %:S
+
+When you are editing main.c, then ":make" executes the following command: >
+
+	make main.c
+
+This is not too useful, so you will refine the command a little and use the :r
+(root) modifier: >
+
+	:set makeprg=make\ %:r:S.o
+
+Now the command executed is as follows: >
+
+	make main.o
+
+More about these modifiers here: |filename-modifiers|.
+
+
+OLD ERROR LISTS
+
+Suppose you ":make" a program.  There is a warning message in one file and an
+error message in another.  You fix the error and use ":make" again to check if
+it was really fixed.  Now you want to look at the warning message.  It doesn't
+show up in the last error list, since the file with the warning wasn't
+compiled again.  You can go back to the previous error list with: >
+
+	:colder
+
+Then use ":clist" and ":cc {nr}" to jump to the place with the warning.
+   To go forward to the next error list: >
+
+	:cnewer
+
+Vim remembers ten error lists.
+
+
+SWITCHING COMPILERS
+
+You have to tell Vim what format the error messages are that your compiler
+produces.  This is done with the 'errorformat' option.  The syntax of this
+option is quite complicated and it can be made to fit almost any compiler.
+You can find the explanation here: |errorformat|.
+
+You might be using various different compilers.  Setting the 'makeprg' option,
+and especially the 'errorformat' each time is not easy.  Vim offers a simple
+method for this.  For example, to switch to using the Microsoft Visual C++
+compiler: >
+
+	:compiler msvc
+
+This will find the Vim script for the "msvc" compiler and set the appropriate
+options.
+   You can write your own compiler files.  See |write-compiler-plugin|.
+
+
+OUTPUT REDIRECTION
+
+The ":make" command redirects the output of the executed program to an error
+file.  How this works depends on various things, such as the 'shell'.  If your
+":make" command doesn't capture the output, check the 'makeef' and
+'shellpipe' options.  The 'shellquote' and 'shellxquote' options might also
+matter.
+
+In case you can't get ":make" to redirect the file for you, an alternative is
+to compile the program in another window and redirect the output into a file.
+Then have Vim read this file with: >
+
+	:cfile {filename}
+
+Jumping to errors will work like with the ":make" command.
+
+==============================================================================
+*30.2*	Indenting C style text
+
+A program is much easier to understand when the lines have been properly
+indented.  Vim offers various ways to make this less work.  For C or C style
+programs like Java or C++, set the 'cindent' option.  Vim knows a lot about C
+programs and will try very hard to automatically set the indent for you.  Set
+the 'shiftwidth' option to the amount of spaces you want for a deeper level.
+Four spaces will work fine.  One ":set" command will do it: >
+
+	:set cindent shiftwidth=4
+
+With this option enabled, when you type something such as "if (x)", the next
+line will automatically be indented an additional level.
+
+				    if (flag)
+	Automatic indent   --->		do_the_work();
+	Automatic unindent <--	    if (other_flag) {
+	Automatic indent   --->		do_file();
+	keep indent			do_some_more();
+	Automatic unindent <--	    }
+
+When you type something in curly braces ({}), the text will be indented at the
+start and unindented at the end.  The unindenting will happen after typing the
+'}', since Vim can't guess what you are going to type.
+
+One side effect of automatic indentation is that it helps you catch errors in
+your code early.  When you type a } to finish a function, only to find that
+the automatic indentation gives it more indent than what you expected, there
+is probably a } missing.  Use the "%" command to find out which { matches the
+} you typed.
+   A missing ) and ; also cause extra indent.  Thus if you get more white
+space than you would expect, check the preceding lines.
+
+When you have code that is badly formatted, or you inserted and deleted lines,
+you need to re-indent the lines.  The "=" operator does this.  The simplest
+form is: >
+
+	==
+
+This indents the current line.  Like with all operators, there are three ways
+to use it.  In Visual mode "=" indents the selected lines.  A useful text
+object is "a{".  This selects the current {} block.  Thus, to re-indent the
+code block the cursor is in: >
+
+	=a{
+
+I you have really badly indented code, you can re-indent the whole file with:
+>
+	gg=G
+
+However, don't do this in files that have been carefully indented manually.
+The automatic indenting does a good job, but in some situations you might want
+to overrule it.
+
+
+SETTING INDENT STYLE
+
+Different people have different styles of indentation.  By default Vim does a
+pretty good job of indenting in a way that 90% of programmers do.  There are
+different styles, however; so if you want to, you can customize the
+indentation style with the 'cinoptions' option.
+   By default 'cinoptions' is empty and Vim uses the default style.  You can
+add various items where you want something different.  For example, to make
+curly braces be placed like this:
+
+	if (flag) ~
+	  { ~
+	    i = 8; ~
+	    j = 0; ~
+	  } ~
+
+Use this command: >
+
+	:set cinoptions+={2
+
+There are many of these items.  See |cinoptions-values|.
+
+==============================================================================
+*30.3*	Automatic indenting
+
+You don't want to switch on the 'cindent' option manually every time you edit
+a C file.  This is how you make it work automatically: >
+
+	:filetype indent on
+
+Actually, this does a lot more than switching on 'cindent' for C files.  First
+of all, it enables detecting the type of a file.  That's the same as what is
+used for syntax highlighting.
+   When the filetype is known, Vim will search for an indent file for this
+type of file.  The Vim distribution includes a number of these for various
+programming languages.  This indent file will then prepare for automatic
+indenting specifically for this file.
+
+If you don't like the automatic indenting, you can switch it off again: >
+
+	:filetype indent off
+
+If you don't like the indenting for one specific type of file, this is how you
+avoid it.  Create a file with just this one line: >
+
+	:let b:did_indent = 1
+
+Now you need to write this in a file with a specific name:
+
+	{directory}/indent/{filetype}.vim
+
+The {filetype} is the name of the file type, such as "cpp" or "java".  You can
+see the exact name that Vim detected with this command: >
+
+	:set filetype
+
+In this file the output is:
+
+	filetype=help ~
+
+Thus you would use "help" for {filetype}.
+   For the {directory} part you need to use your runtime directory.  Look at
+the output of this command: >
+
+	set runtimepath
+
+Now use the first item, the name before the first comma.  Thus if the output
+looks like this:
+
+	runtimepath=~/.vim,/usr/local/share/vim/vim60/runtime,~/.vim/after ~
+
+You use "~/.vim" for {directory}.  Then the resulting file name is:
+
+	~/.vim/indent/help.vim ~
+
+Instead of switching the indenting off, you could write your own indent file.
+How to do that is explained here: |indent-expression|.
+
+==============================================================================
+*30.4*	Other indenting
+
+The simplest form of automatic indenting is with the 'autoindent' option.
+It uses the indent from the previous line.  A bit smarter is the 'smartindent'
+option.  This is useful for languages where no indent file is available.
+'smartindent' is not as smart as 'cindent', but smarter than 'autoindent'.
+   With 'smartindent' set, an extra level of indentation is added for each {
+and removed for each }.  An extra level of indentation will also be added for
+any of the words in the 'cinwords' option.  Lines that begin with # are
+treated specially: all indentation is removed.  This is done so that
+preprocessor directives will all start in column 1.  The indentation is
+restored for the next line.
+
+
+CORRECTING INDENTS
+
+When you are using 'autoindent' or 'smartindent' to get the indent of the
+previous line, there will be many times when you need to add or remove one
+'shiftwidth' worth of indent.  A quick way to do this is using the CTRL-D and
+CTRL-T commands in Insert mode.
+   For example, you are typing a shell script that is supposed to look like
+this:
+
+	if test -n a; then ~
+	   echo a ~
+	   echo "-------" ~
+	fi ~
+
+Start off by setting these options: >
+
+	:set autoindent shiftwidth=3
+
+You start by typing the first line, <Enter> and the start of the second line:
+
+	if test -n a; then ~
+	echo ~
+
+Now you see that you need an extra indent.  Type CTRL-T.  The result:
+
+	if test -n a; then ~
+	   echo ~
+
+The CTRL-T command, in Insert mode, adds one 'shiftwidth' to the indent, no
+matter where in the line you are.
+   You continue typing the second line, <Enter> and the third line.  This time
+the indent is OK.  Then <Enter> and the last line.  Now you have this:
+
+	if test -n a; then ~
+	   echo a ~
+	   echo "-------" ~
+	   fi ~
+
+To remove the superfluous indent in the last line press CTRL-D.  This deletes
+one 'shiftwidth' worth of indent, no matter where you are in the line.
+   When you are in Normal mode, you can use the ">>" and "<<" commands to
+shift lines.  ">" and "<" are operators, thus you have the usual three ways to
+specify the lines you want to indent.  A useful combination is: >
+
+	>i{
+
+This adds one indent to the current block of lines, inside {}.  The { and }
+lines themselves are left unmodified.  ">a{" includes them.  In this example
+the cursor is on "printf":
+
+	original text		after ">i{"		after ">a{"
+
+	if (flag)		if (flag)		if (flag) ~
+	{			{			    { ~
+	printf("yes");		    printf("yes");	    printf("yes"); ~
+	flag = 0;		    flag = 0;		    flag = 0;  ~
+	}			}			    } ~
+
+==============================================================================
+*30.5*	Tabs and spaces
+
+'tabstop' is set to eight by default.  Although you can change it, you quickly
+run into trouble later.  Other programs won't know what tabstop value you
+used.  They probably use the default value of eight, and your text suddenly
+looks very different.  Also, most printers use a fixed tabstop value of eight.
+Thus it's best to keep 'tabstop' alone.  (If you edit a file which was written
+with a different tabstop setting, see |25.3| for how to fix that.)
+   For indenting lines in a program, using a multiple of eight spaces makes
+you quickly run into the right border of the window.  Using a single space
+doesn't provide enough visual difference.  Many people prefer to use four
+spaces, a good compromise.
+   Since a <Tab> is eight spaces and you want to use an indent of four spaces,
+you can't use a <Tab> character to make your indent.  There are two ways to
+handle this:
+
+1.  Use a mix of <Tab> and space characters.  Since a <Tab> takes the place of
+    eight spaces, you have fewer characters in your file.  Inserting a <Tab>
+    is quicker than eight spaces.  Backspacing works faster as well.
+
+2.  Use spaces only.  This avoids the trouble with programs that use a
+    different tabstop value.
+
+Fortunately, Vim supports both methods quite well.
+
+
+SPACES AND TABS
+
+If you are using a combination of tabs and spaces, you just edit normally.
+The Vim defaults do a fine job of handling things.
+   You can make life a little easier by setting the 'softtabstop' option.
+This option tells Vim to make the <Tab> key look and feel as if tabs were set
+at the value of 'softtabstop', but actually use a combination of tabs and
+spaces.
+   After you execute the following command, every time you press the <Tab> key
+the cursor moves to the next 4-column boundary: >
+
+	:set softtabstop=4
+
+When you start in the first column and press <Tab>, you get 4 spaces inserted
+in your text.  The second time, Vim takes out the 4 spaces and puts in a <Tab>
+(thus taking you to column 8).  Thus Vim uses as many <Tab>s as possible, and
+then fills up with spaces.
+   When backspacing it works the other way around.  A <BS> will always delete
+the amount specified with 'softtabstop'.  Then <Tab>s are used as many as
+possible and spaces to fill the gap.
+   The following shows what happens pressing <Tab> a few times, and then using
+<BS>.  A "." stands for a space and "------->" for a <Tab>.
+
+	type			  result ~
+	<Tab>			  ....
+	<Tab><Tab>		  ------->
+	<Tab><Tab><Tab>		  ------->....
+	<Tab><Tab><Tab><BS>	  ------->
+	<Tab><Tab><Tab><BS><BS>   ....
+
+An alternative is to use the 'smarttab' option.  When it's set, Vim uses
+'shiftwidth' for a <Tab> typed in the indent of a line, and a real <Tab> when
+typed after the first non-blank character.  However, <BS> doesn't work like
+with 'softtabstop'.
+
+
+JUST SPACES
+
+If you want absolutely no tabs in your file, you can set the 'expandtab'
+option: >
+
+	:set expandtab
+
+When this option is set, the <Tab> key inserts a series of spaces.  Thus you
+get the same amount of white space as if a <Tab> character was inserted, but
+there isn't a real <Tab> character in your file.
+   The backspace key will delete each space by itself.  Thus after typing one
+<Tab> you have to press the <BS> key up to eight times to undo it.  If you are
+in the indent, pressing CTRL-D will be a lot quicker.
+
+
+CHANGING TABS IN SPACES (AND BACK)
+
+Setting 'expandtab' does not affect any existing tabs.  In other words, any
+tabs in the document remain tabs.  If you want to convert tabs to spaces, use
+the ":retab" command.  Use these commands: >
+
+	:set expandtab
+	:%retab
+
+Now Vim will have changed all indents to use spaces instead of tabs.  However,
+all tabs that come after a non-blank character are kept.  If you want these to
+be converted as well, add a !: >
+
+	:%retab!
+
+This is a little bit dangerous, because it can also change tabs inside a
+string.  To check if these exist, you could use this: >
+
+	/"[^"\t]*\t[^"]*"
+
+It's recommended not to use hard tabs inside a string.  Replace them with
+"\t" to avoid trouble.
+
+The other way around works just as well: >
+
+	:set noexpandtab
+	:%retab!
+
+==============================================================================
+*30.6*	Formatting comments
+
+One of the great things about Vim is that it understands comments.  You can
+ask Vim to format a comment and it will do the right thing.
+   Suppose, for example, that you have the following comment:
+
+	/* ~
+	 * This is a test ~
+	 * of the text formatting. ~
+	 */ ~
+
+You then ask Vim to format it by positioning the cursor at the start of the
+comment and type: >
+
+	gq]/
+
+"gq" is the operator to format text.  "]/" is the motion that takes you to the
+end of a comment.  The result is:
+
+	/* ~
+	 * This is a test of the text formatting. ~
+	 */ ~
+
+Notice that Vim properly handled the beginning of each line.
+  An alternative is to select the text that is to be formatted in Visual mode
+and type "gq".
+
+To add a new line to the comment, position the cursor on the middle line and
+press "o".  The result looks like this:
+
+	/* ~
+	 * This is a test of the text formatting. ~
+	 * ~
+	 */ ~
+
+Vim has automatically inserted a star and a space for you.  Now you can type
+the comment text.  When it gets longer than 'textwidth', Vim will break the
+line.  Again, the star is inserted automatically:
+
+	/* ~
+	 * This is a test of the text formatting. ~
+	 * Typing a lot of text here will make Vim ~
+	 * break ~
+	 */ ~
+
+For this to work some flags must be present in 'formatoptions':
+
+	r	insert the star when typing <Enter> in Insert mode
+	o	insert the star when using "o" or "O" in Normal mode
+	c	break comment text according to 'textwidth'
+
+See |fo-table| for more flags.
+
+
+DEFINING A COMMENT
+
+The 'comments' option defines what a comment looks like.  Vim distinguishes
+between a single-line comment and a comment that has a different start, end
+and middle part.
+   Many single-line comments start with a specific character.  In C++ // is
+used, in Makefiles #, in Vim scripts ".  For example, to make Vim understand
+C++ comments: >
+
+	:set comments=://
+
+The colon separates the flags of an item from the text by which the comment is
+recognized.  The general form of an item in 'comments' is:
+
+	{flags}:{text}
+
+The {flags} part can be empty, as in this case.
+   Several of these items can be concatenated, separated by commas.  This
+allows recognizing different types of comments at the same time.  For example,
+let's edit an e-mail message.  When replying, the text that others wrote is
+preceded with ">" and "!" characters.  This command would work: >
+
+	:set comments=n:>,n:!
+
+There are two items, one for comments starting with ">" and one for comments
+that start with "!".  Both use the flag "n".  This means that these comments
+nest.  Thus a line starting with ">" may have another comment after the ">".
+This allows formatting a message like this:
+
+	> ! Did you see that site? ~
+	> ! It looks really great. ~
+	> I don't like it.  The ~
+	> colors are terrible. ~
+	What is the URL of that ~
+	site? ~
+
+Try setting 'textwidth' to a different value, e.g., 80, and format the text by
+Visually selecting it and typing "gq".  The result is:
+
+	> ! Did you see that site?  It looks really great. ~
+	> I don't like it.  The colors are terrible. ~
+	What is the URL of that site? ~
+
+You will notice that Vim did not move text from one type of comment to
+another.  The "I" in the second line would have fit at the end of the first
+line, but since that line starts with "> !" and the second line with ">", Vim
+knows that this is a different kind of comment.
+
+
+A THREE PART COMMENT
+
+A C comment starts with "/*", has "*" in the middle and "*/" at the end.  The
+entry in 'comments' for this looks like this: >
+
+	:set comments=s1:/*,mb:*,ex:*/
+
+The start is defined with "s1:/*".  The "s" indicates the start of a
+three-piece comment.  The colon separates the flags from the text by which the
+comment is recognized: "/*".  There is one flag: "1".  This tells Vim that the
+middle part has an offset of one space.
+   The middle part "mb:*" starts with "m", which indicates it is a middle
+part.  The "b" flag means that a blank must follow the text.  Otherwise Vim
+would consider text like "*pointer" also to be the middle of a comment.
+   The end part "ex:*/" has the "e" for identification.  The "x" flag has a
+special meaning.  It means that after Vim automatically inserted a star,
+typing / will remove the extra space.
+
+For more details see |format-comments|.
+
+==============================================================================
+
+Next chapter: |usr_31.txt|  Exploiting the GUI
+
+Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: