summaryrefslogtreecommitdiff
path: root/runtime/doc/indent.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/indent.txt')
-rw-r--r--runtime/doc/indent.txt522
1 files changed, 522 insertions, 0 deletions
diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt
new file mode 100644
index 000000000..a35ce54ce
--- /dev/null
+++ b/runtime/doc/indent.txt
@@ -0,0 +1,522 @@
+*indent.txt* For Vim version 7.0aa. Last change: 2004 Apr 25
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+This file is about indenting C programs and other files.
+
+1. Indenting C programs |C-indenting|
+2. Indenting by expression |indent-expression|
+
+==============================================================================
+1. Indenting C programs *C-indenting*
+
+The basics for C indenting are explained in section |30.2| of the user manual.
+
+Vim has options for automatically indenting C program files. These options
+affect only the indent and do not perform other formatting. For comment
+formatting, see |format-comments|.
+
+Note that this will not work when the |+smartindent| or |+cindent| features
+have been disabled at compile time.
+
+There are in fact four methods available for indentation:
+'autoindent' uses the indent from the previous line.
+'smartindent' is like 'autoindent' but also recognizes some C syntax to
+ increase/reduce the indent where appropriate.
+'cindent' Works more cleverly than the other two and is configurable to
+ different indenting styles.
+'indentexpr' The most flexible of all: Evaluates an expression to compute
+ the indent of a line. When non-empty this method overrides
+ the other ones. See |indent-expression|.
+The rest of this section describes the 'cindent' option.
+
+Note that 'cindent' indenting does not work for every code scenario. Vim
+is not a C compiler: it does not recognize all syntax.
+
+These four options control C program indenting:
+'cindent' Enables Vim to perform C program indenting automatically.
+'cinkeys' Specifies which keys trigger reindenting in insert mode.
+'cinoptions' Sets your preferred indent style.
+'cinwords' Defines keywords that start an extra indent in the next line.
+
+If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using
+Vim's built-in algorithm rather than calling an external program.
+
+See |autocommand| for how to set the 'cindent' option automatically for C code
+files and reset it for others.
+
+ *cinkeys-format* *indentkeys-format*
+The 'cinkeys' option is a string that controls Vim's indenting in response to
+typing certain characters or commands in certain contexts. Note that this not
+only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is
+used instead. The format of 'cinkeys' and 'indentkeys' is equal.
+
+The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs
+as follows:
+
+ "0{" if you type '{' as the first character in a line
+ "0}" if you type '}' as the first character in a line
+ "0)" if you type ')' as the first character in a line
+ ":" if you type ':' after a label or case statement
+ "0#" if you type '#' as the first character in a line
+ "!^F" if you type CTRL-F (which is not inserted)
+ "o" if you type a <CR> anywhere or use the "o" command (not in
+ insert mode!)
+ "O" if you use the "O" command (not in insert mode!)
+ "e" if you type the second 'e' for an "else" at the start of a
+ line
+
+Characters that can precede each key:
+! When a '!' precedes the key, Vim will not insert the key but will
+ instead reindent the current line. This allows you to define a
+ command key for reindenting the current line. CTRL-F is the default
+ key for this. Be careful if you define CTRL-I for this because CTRL-I
+ is the ASCII code for <Tab>.
+* When a '*' precedes the key, Vim will reindent the line before
+ inserting the key. If 'cinkeys' contains "*<Return>", Vim reindents
+ the current line before opening a new line.
+0 When a zero precedes the key (but appears after '!' or '*') Vim will
+ reindent the line only if the key is the first character you type in
+ the line. When used before "=" Vim will only reindent the line if
+ there is only white space before the word.
+
+When neither '!' nor '*' precedes the key, Vim reindents the line after you
+type the key. So ';' sets the indentation of a line which includes the ';'.
+
+Special key names:
+<> Angle brackets mean spelled-out names of keys. For example: "<Up>",
+ "<Ins>" (see |key-notation|).
+^ Letters preceded by a caret (^) are control characters. For example:
+ "^F" is CTRL-F.
+o Reindent a line when you use the "o" command or when Vim opens a new
+ line below the current one (e.g., when you type <Enter> in insert
+ mode).
+O Reindent a line when you use the "O" command.
+e Reindent a line that starts with "else" when you type the second 'e'.
+: Reindent a line when a ':' is typed which is after a label or case
+ statement. Don't reindent for a ":" in "class::method" for C++. To
+ Reindent for any ":", use "<:>".
+=word Reindent when typing the last character of "word". "word" may
+ actually be part of another word. Thus "=end" would cause reindenting
+ when typing the "d" in "endif" or "endwhile". But not when typing
+ "bend". Also reindent when completion produces a word that starts
+ with "word". "0=word" reindents when there is only white space before
+ the word.
+=~word Like =word, but ignore case.
+
+If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>',
+'*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or
+"<!>", respectively, for those keys.
+
+For an emacs-style indent mode where lines aren't indented every time you
+press Enter but only if you press Tab, I suggest:
+ :set cinkeys=0{,0},:,0#,!<Tab>,!^F
+You might also want to switch off 'autoindent' then.
+
+Note: If you change the current line's indentation manually, Vim ignores the
+cindent settings for that line. This prevents vim from reindenting after you
+have changed the indent by typing <BS>, <Tab>, or <Space> in the indent or
+used CTRL-T or CTRL-D.
+
+ *cinoptions-values*
+The 'cinoptions' option sets how Vim performs indentation. In the list below,
+"N" represents a number of your choice (the number can be negative). When
+there is an 's' after the number, Vim multiplies the number by 'shiftwidth':
+"1s" is 'shiftwidth', "2s" is two times 'shiftwidth', etc. You can use a
+decimal point, too: "-0.5s" is minus half a 'shiftwidth'. The examples below
+assume a 'shiftwidth' of 4.
+
+ >N Amount added for "normal" indent. Used after a line that should
+ increase the indent (lines starting with "if", an opening brace,
+ etc.). (default 'shiftwidth').
+
+ cino= cino=>2 cino=>2s >
+ if (cond) if (cond) if (cond)
+ { { {
+ foo; foo; foo;
+ } } }
+<
+ eN Add N to the prevailing indent inside a set of braces if the
+ opening brace at the End of the line (more precise: is not the
+ first character in a line). This is useful if you want a
+ different indent when the '{' is at the start of the line from
+ when '{' is at the end of the line. (default 0).
+
+ cino= cino=e2 cino=e-2 >
+ if (cond) { if (cond) { if (cond) {
+ foo; foo; foo;
+ } } }
+ else else else
+ { { {
+ bar; bar; bar;
+ } } }
+<
+ nN Add N to the prevailing indent for a statement after an "if",
+ "while", etc., if it is NOT inside a set of braces. This is
+ useful if you want a different indent when there is no '{'
+ before the statement from when there is a '{' before it.
+ (default 0).
+
+ cino= cino=n2 cino=n-2 >
+ if (cond) if (cond) if (cond)
+ foo; foo; foo;
+ else else else
+ { { {
+ bar; bar; bar;
+ } } }
+<
+ fN Place the first opening brace of a function or other block in
+ column N. This applies only for an opening brace that is not
+ inside other braces and is at the start of the line. What comes
+ after the brace is put relative to this brace. (default 0).
+
+ cino= cino=f.5s cino=f1s >
+ func() func() func()
+ { { {
+ int foo; int foo; int foo;
+<
+ {N Place opening braces N characters from the prevailing indent.
+ This applies only for opening braces that are inside other
+ braces. (default 0).
+
+ cino= cino={.5s cino={1s >
+ if (cond) if (cond) if (cond)
+ { { {
+ foo; foo; foo;
+<
+ }N Place closing braces N characters from the matching opening
+ brace. (default 0).
+
+ cino= cino={2,}-0.5s cino=}2 >
+ if (cond) if (cond) if (cond)
+ { { {
+ foo; foo; foo;
+ } } }
+<
+ ^N Add N to the prevailing indent inside a set of braces if the
+ opening brace is in column 0. This can specify a different
+ indent for whole of a function (some may like to set it to a
+ negative number). (default 0).
+
+ cino= cino=^-2 cino=^-s >
+ func() func() func()
+ { { {
+ if (cond) if (cond) if (cond)
+ { { {
+ a = b; a = b; a = b;
+ } } }
+ } } }
+<
+ :N Place case labels N characters from the indent of the switch().
+ (default 'shiftwidth').
+
+ cino= cino=:0 >
+ switch (x) switch(x)
+ { {
+ case 1: case 1:
+ a = b; a = b;
+ default: default:
+ } }
+<
+ =N Place statements occurring after a case label N characters from
+ the indent of the label. (default 'shiftwidth').
+
+ cino= cino==10 >
+ case 11: case 11: a = a + 1;
+ a = a + 1; b = b + 1;
+<
+ lN If N != 0 Vim will align with a case label instead of the
+ statement after it in the same line.
+
+ cino= cino=l1 >
+ switch (a) { switch (a) {
+ case 1: { case 1: {
+ break; break;
+ } }
+<
+ bN If N != 0 Vim will align a final "break" with the case label,
+ so that case..break looks like a sort of block. (default: 0).
+
+ cino= cino=b1 >
+ switch (x) switch(x)
+ { {
+ case 1: case 1:
+ a = b; a = b;
+ break; break;
+
+ default: default:
+ a = 0; a = 0;
+ break; break;
+ } }
+<
+ gN Place C++ scope declarations N characters from the indent of the
+ block they are in. (default 'shiftwidth'). A scope declaration
+ can be "public:", "protected:" or "private:".
+
+ cino= cino=g0 >
+ { {
+ public: public:
+ a = b; a = b;
+ private: private:
+ } }
+<
+ hN Place statements occurring after a C++ scope declaration N
+ characters from the indent of the label. (default
+ 'shiftwidth').
+
+ cino= cino=h10 >
+ public: public: a = a + 1;
+ a = a + 1; b = b + 1;
+<
+ pN Parameter declarations for K&R-style function declarations will
+ be indented N characters from the margin. (default
+ 'shiftwidth').
+
+ cino= cino=p0 cino=p2s >
+ func(a, b) func(a, b) func(a, b)
+ int a; int a; int a;
+ char b; char b; char b;
+<
+ tN Indent a function return type declaration N characters from the
+ margin. (default 'shiftwidth').
+
+ cino= cino=t0 cino=t7 >
+ int int int
+ func() func() func()
+<
+ iN Indent C++ base class declarations and contructor
+ initializations, if they start in a new line (otherwise they
+ are aligned at the right side of the ':').
+ (default 'shiftwidth').
+
+ cino= cino=i0 >
+ class MyClass : class MyClass :
+ public BaseClass public BaseClass
+ {} {}
+ MyClass::MyClass() : MyClass::MyClass() :
+ BaseClass(3) BaseClass(3)
+ {} {}
+<
+ +N Indent a continuation line (a line that spills onto the next) N
+ additional characters. (default 'shiftwidth').
+
+ cino= cino=+10 >
+ a = b + 9 * a = b + 9 *
+ c; c;
+<
+ cN Indent comment lines after the comment opener, when there is no
+ other text with which to align, N characters from the comment
+ opener. (default 3). See also |format-comments|.
+
+ cino= cino=c5 >
+ /* /*
+ text. text.
+ */ */
+<
+ CN When N is non-zero, indent comment lines by the amount specified
+ with the c flag above even if there is other text behind the
+ comment opener. (default 0).
+
+ cino=c0 cino=c0,C1 >
+ /******** /********
+ text. text.
+ ********/ ********/
+< (Example uses ":set comments& comments-=s1:/* comments^=s0:/*")
+
+ /N Indent comment lines N characters extra. (default 0).
+ cino= cino=/4 >
+ a = b; a = b;
+ /* comment */ /* comment */
+ c = d; c = d;
+<
+ (N When in unclosed parentheses, indent N characters from the line
+ with the unclosed parentheses. Add a 'shiftwidth' for every
+ unclosed parentheses. When N is 0 or the unclosed parentheses
+ is the first non-white character in its line, line up with the
+ next non-white character after the unclosed parentheses.
+ (default 'shiftwidth' * 2).
+
+ cino= cino=(0 >
+ if (c1 && (c2 || if (c1 && (c2 ||
+ c3)) c3))
+ foo; foo;
+ if (c1 && if (c1 &&
+ (c2 || c3)) (c2 || c3))
+ { {
+<
+ uN Same as (N, but for one level deeper. (default 'shiftwidth').
+
+ cino= cino=u2 >
+ if (c123456789 if (c123456789
+ && (c22345 && (c22345
+ || c3)) || c3))
+<
+ UN When N is non-zero, do not ignore the indenting specified by
+ ( or u in case that the unclosed parentheses is the first
+ non-white character in its line. (default 0).
+
+ cino= or cino=(s cino=(s,U1 >
+ c = c1 && c = c1 &&
+ ( (
+ c2 || c2 ||
+ c3 c3
+ ) && c4; ) && c4;
+<
+ wN When in unclosed parentheses and N is non-zero and either
+ using "(0" or "u0", respectively, or using "U0" and the unclosed
+ parentheses is the first non-white character in its line, line
+ up with the character immediately after the unclosed parentheses
+ rather than the first non-white character. (default 0).
+
+ cino=(0 cino=(0,w1 >
+ if ( c1 if ( c1
+ && ( c2 && ( c2
+ || c3)) || c3))
+ foo; foo;
+<
+ WN When in unclosed parentheses and N is non-zero and either
+ using "(0" or "u0", respectively and the unclosed parentheses is
+ the last non-white character in its line and it is not the
+ closing parentheses, indent the following line N characters
+ relative to the outer context (i.e. start of the line or the
+ next unclosed parentheses). (default: 0).
+
+ cino=(0 cino=(0,W4 >
+ a_long_line( a_long_line(
+ argument, argument,
+ argument); argument);
+ a_short_line(argument, a_short_line(argument,
+ argument); argument);
+<
+ mN When N is non-zero, line up a line starting with a closing
+ parentheses with the first character of the line with the
+ matching opening parentheses. (default 0).
+
+ cino=(s cino=(s,m1 >
+ c = c1 && ( c = c1 && (
+ c2 || c2 ||
+ c3 c3
+ ) && c4; ) && c4;
+ if ( if (
+ c1 && c2 c1 && c2
+ ) )
+ foo; foo;
+<
+ *java-cinoptions* *java-indenting*
+ jN Indent java anonymous classes correctly. The value 'N' is
+ currently unused but must be non-zero (e.g. 'j1'). 'j1' will
+ indent for example the following code snippet correctly: >
+
+ object.add(new ChangeListener() {
+ public void stateChanged(ChangeEvent e) {
+ do_something();
+ }
+ });
+<
+ )N Vim searches for unclosed parentheses at most N lines away.
+ This limits the time needed to search for parentheses. (default
+ 20 lines).
+
+ *N Vim searches for unclosed comments at most N lines away. This
+ limits the time needed to search for the start of a comment.
+ (default 30 lines).
+
+
+The defaults, spelled out in full, are:
+ cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,l0,gs,hs,ps,ts,+s,c3,C0,(2s,us,
+ \U0,w0,m0,j0,)20,*30
+
+Vim puts a line in column 1 if:
+- It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'.
+- It starts with a label (a keyword followed by ':', other than "case" and
+ "default").
+- Any combination of indentations causes the line to have less than 0
+ indentation.
+
+==============================================================================
+2. Indenting by expression *indent-expression*
+
+The basics for using flexible indenting are explained in section |30.3| of the
+user manual.
+
+If you want to write your own indent file, it must set the 'indentexpr'
+option. Setting the 'indentkeys' option is often useful. See the
+$VIMRUNTIME/indent directory for examples.
+
+
+REMARKS ABOUT SPECIFIC INDENT FILES ~
+
+
+FORTRAN *fortran-indent*
+
+Block if, select case, and where constructs are indented. Comments, labelled
+statements and continuation lines are indented if the Fortran is in free
+source form, whereas they are not indented if the Fortran is in fixed source
+form because of the left margin requirements. Hence manual indent corrections
+will be necessary for labelled statements and continuation lines when fixed
+source form is being used. For further discussion of the method used for the
+detection of source format see |fortran-syntax|.
+
+Do loops ~
+All do loops are left unindented by default. Do loops can be unstructured in
+Fortran with (possibly multiple) loops ending on a labelled executable
+statement of almost arbitrary type. Correct indentation requires
+compiler-quality parsing. Old code with do loops ending on labelled statements
+of arbitrary type can be indented with elaborate programs such as Tidy
+(http://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are
+also left unindented because continue statements are also used for purposes
+other than ending a do loop. Programs such as Tidy can convert structured
+do/continue loops to the do/enddo form. Do loops of the do/enddo variety can
+be indented. If you use only structured loops of the do/enddo form, you should
+declare this by setting the fortran_do_enddo variable in your .vimrc as
+follows >
+
+ let fortran_do_enddo=1
+
+in which case do loops will be indented. If all your loops are of do/enddo
+type only in, say, .f90 files, then you should set a buffer flag with an
+autocommand such as >
+
+ au! BufRead,BufNewFile *.f90 let b:fortran_do_enddo=1
+
+to get do loops indented in .f90 files and left alone in Fortran files with
+other extensions such as .for.
+
+
+VERILOG *verilog-indent*
+
+General block statements such as if, for, case, always, initial, function,
+specify and begin, etc., are indented. The module block statements (first
+level blocks) are not indented by default. you can turn on the indent with
+setting a variable in the .vimrc as follows: >
+
+ let b:verilog_indent_modules = 1
+
+then the module blocks will be indented. To stop this, remove the variable: >
+
+ :unlet b:verilog_indent_modules
+
+To set the variable only for Verilog file. The following statements can be
+used: >
+
+ au BufReadPost * if exists("b:current_syntax")
+ au BufReadPost * if b:current_syntax == "verilog"
+ au BufReadPost * let b:verilog_indent_modules = 1
+ au BufReadPost * endif
+ au BufReadPost * endif
+
+Furthermore, setting the variable b:verilog_indent_width to change the
+indenting width (default is 'shiftwidth'): >
+
+ let b:verilog_indent_width = 4
+ let b:verilog_indent_width = &sw * 2
+
+In addition, you can turn the verbose mode for debug issue: >
+
+ let b:verilog_indent_verbose = 1
+
+Make sure to do ":set cmdheight=2" first to allow the display of the message.
+
+ vim:tw=78:ts=8:ft=help:norl: