-\1f
-File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
-
-Basic Program Indentation Commands
-----------------------------------
-
-`<TAB>'
- Adjust indentation of current line.
-
-`<LFD>'
- Equivalent to <RET> followed by <TAB> (`newline-and-indent').
-
- The basic indentation command is <TAB>, which gives the current line
-the correct indentation as determined from the previous lines. The
-function that <TAB> runs depends on the major mode; it is
-`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
-functions understand different syntaxes for different languages, but
-they all do about the same thing. <TAB> in any programming language
-major mode inserts or deletes whitespace at the beginning of the
-current line, independent of where point is in the line. If point is
-inside the whitespace at the beginning of the line, <TAB> leaves it at
-the end of that whitespace; otherwise, <TAB> leaves point fixed with
-respect to the characters around it.
-
- Use `C-q <TAB>' to insert a tab at point.
-
- When entering a large amount of new code, use <LFD>
-(`newline-and-indent'), which is equivalent to a <RET> followed by a
-<TAB>. <LFD> creates a blank line, then gives it the appropriate
-indentation.
-
- <TAB> indents the second and following lines of the body of a
-parenthetical grouping each under the preceding one; therefore, if you
-alter one line's indentation to be nonstandard, the lines below tend to
-follow it. This is the right behavior in cases where the standard
-result of <TAB> does not look good.
-
- Remember that Emacs assumes that an open-parenthesis, open-brace, or
-other opening delimiter at the left margin (including the indentation
-routines) is the start of a function. You should therefore never have
-an opening delimiter in column zero that is not the beginning of a
-function, not even inside a string. This restriction is vital for
-making the indentation commands fast. *Note Defuns::, for more
-information on this behavior.
-
-\1f
-File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
-
-Indenting Several Lines
------------------------
-
- Several commands are available to re-indent several lines of code
-which have been altered or moved to a different level in a list
-structure.
-
-`C-M-q'
- Re-indent all the lines within one list (`indent-sexp').
-
-`C-u <TAB>'
- Shift an entire list rigidly sideways so that its first line is
- properly indented.
-
-`C-M-\'
- Re-indent all lines in the region (`indent-region').
-
- To re-indent the contents of a single list, position point before the
-beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
-Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
-functions in other modes. The indentation of the line the sexp starts
-on is not changed; therefore, only the relative indentation within the
-list, and not its position, is changed. To correct the position as
-well, type a <TAB> before `C-M-q'.
-
- If the relative indentation within a list is correct but the
-indentation of its beginning is not, go to the line on which the list
-begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
-it moves all the lines in the group, starting on the current line,
-sideways the same amount that the current line moves. The command does
-not move lines that start inside strings, or C preprocessor lines when
-in C mode.
-
- Another way to specify a range to be re-indented is with point and
-mark. The command `C-M-\' (`indent-region') applies <TAB> to every
-line whose first character is between point and mark.
-
-\1f
-File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
-
-Customizing Lisp Indentation
-----------------------------
-
- The indentation pattern for a Lisp expression can depend on the
-function called by the expression. For each Lisp function, you can
-choose among several predefined patterns of indentation, or define an
-arbitrary one with a Lisp program.
-
- The standard pattern of indentation is as follows: the second line
-of the expression is indented under the first argument, if that is on
-the same line as the beginning of the expression; otherwise, the second
-line is indented underneath the function name. Each following line is
-indented under the previous line whose nesting depth is the same.
-
- If the variable `lisp-indent-offset' is non-`nil', it overrides the
-usual indentation pattern for the second line of an expression, so that
-such lines are always indented `lisp-indent-offset' more columns than
-the containing list.
-
- Certain functions override the standard pattern. Functions whose
-names start with `def' always indent the second line by
-`lisp-body-indention' extra columns beyond the open-parenthesis
-starting the expression.
-
- Individual functions can override the standard pattern in various
-ways, according to the `lisp-indent-function' property of the function
-name. (Note: `lisp-indent-function' was formerly called
-`lisp-indent-hook'). There are four possibilities for this property:
-
-`nil'
- This is the same as no property; the standard indentation pattern
- is used.
-
-`defun'
- The pattern used for function names that start with `def' is used
- for this function also.
-
-a number, NUMBER
- The first NUMBER arguments of the function are "distinguished"
- arguments; the rest are considered the "body" of the expression.
- A line in the expression is indented according to whether the
- first argument on it is distinguished or not. If the argument is
- part of the body, the line is indented `lisp-body-indent' more
- columns than the open-parenthesis starting the containing
- expression. If the argument is distinguished and is either the
- first or second argument, it is indented twice that many extra
- columns. If the argument is distinguished and not the first or
- second argument, the standard pattern is followed for that line.
-
-a symbol, SYMBOL
- SYMBOL should be a function name; that function is called to
- calculate the indentation of a line within this expression. The
- function receives two arguments:
- STATE
- The value returned by `parse-partial-sexp' (a Lisp primitive
- for indentation and nesting computation) when it parses up to
- the beginning of this line.
-
- POS
- The position at which the line being indented begins.
-
- It should return either a number, which is the number of columns of
- indentation for that line, or a list whose first element is such a
- number. The difference between returning a number and returning a
- list is that a number says that all following lines at the same
- nesting level should be indented just like this one; a list says
- that following lines might call for different indentations. This
- makes a difference when the indentation is computed by `C-M-q'; if
- the value is a number, `C-M-q' need not recalculate indentation
- for the following lines until the end of the list.
-
-\1f
-File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
-
-Customizing C Indentation
--------------------------
-
- Two variables control which commands perform C indentation and when.
-
- If `c-auto-newline' is non-`nil', newlines are inserted both before
-and after braces that you insert and after colons and semicolons.
-Correct C indentation is done on all the lines that are made this way.
-
- If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
-does indentation only if point is at the left margin or within the
-line's indentation. If there is non-whitespace to the left of point,
-<TAB> just inserts a tab character in the buffer. Normally, this
-variable is `nil', and <TAB> always reindents the current line.
-
- C does not have anything analogous to particular function names for
-which special forms of indentation are desirable. However, it has a
-different need for customization facilities: many different styles of C
-indentation are in common use.
-
- There are six variables you can set to control the style that Emacs C
-mode will use.
-
-`c-indent-level'
- Indentation of C statements within surrounding block. The
- surrounding block's indentation is the indentation of the line on
- which the open-brace appears.
-
-`c-continued-statement-offset'
- Extra indentation given to a substatement, such as the then-clause
- of an `if' or body of a `while'.
-
-`c-brace-offset'
- Extra indentation for lines that start with an open brace.
-
-`c-brace-imaginary-offset'
- An open brace following other text is treated as if it were this
- far to the right of the start of its line.
-
-`c-argdecl-indent'
- Indentation level of declarations of C function arguments.
-
-`c-label-offset'
- Extra indentation for a line that is a label, case, or default.
-
- The variable `c-indent-level' controls the indentation for C
-statements with respect to the surrounding block. In the example:
-
- {
- foo ();
-
-the difference in indentation between the lines is `c-indent-level'.
-Its standard value is 2.
-
- If the open-brace beginning the compound statement is not at the
-beginning of its line, the `c-indent-level' is added to the indentation
-of the line, not the column of the open-brace. For example,
-
- if (losing) {
- do_this ();
-
-One popular indentation style is that which results from setting
-`c-indent-level' to 8 and putting open-braces at the end of a line in
-this way. Another popular style prefers to put the open-brace on a
-separate line.
-
- In fact, the value of the variable `c-brace-imaginary-offset' is
-also added to the indentation of such a statement. Normally this
-variable is zero. Think of this variable as the imaginary position of
-the open brace, relative to the first non-blank character on the line.
-By setting the variable to 4 and `c-indent-level' to 0, you can get
-this style:
-
- if (x == y) {
- do_it ();
- }
-
- When `c-indent-level' is zero, the statements inside most braces
-line up exactly under the open brace. An exception are braces in column
-zero, like those surrounding a function's body. The statements inside
-those braces are not placed at column zero. Instead, `c-brace-offset'
-and `c-continued-statement-offset' (see below) are added to produce a
-typical offset between brace levels, and the statements are indented
-that far.
-
- `c-continued-statement-offset' controls the extra indentation for a
-line that starts within a statement (but not within parentheses or
-brackets). These lines are usually statements inside other statements,
-like the then-clauses of `if' statements and the bodies of `while'
-statements. The `c-continued-statement-offset' parameter determines
-the difference in indentation between the two lines in:
-
- if (x == y)
- do_it ();
-
-The default value for `c-continued-statement-offset' is 2. Some
-popular indentation styles correspond to a value of zero for
-`c-continued-statement-offset'.
-
- `c-brace-offset' is the extra indentation given to a line that
-starts with an open-brace. Its standard value is zero; compare:
-
- if (x == y)
- {
-
-with:
-
- if (x == y)
- do_it ();
-
-If you set `c-brace-offset' to 4, the first example becomes:
-
- if (x == y)
- {
-
- `c-argdecl-indent' controls the indentation of declarations of the
-arguments of a C function. It is absolute: argument declarations
-receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
-results in code like this:
-
- char *
- index (string, char)
- char *string;
- int char;
-
- `c-label-offset' is the extra indentation given to a line that
-contains a label, a case statement, or a `default:' statement. Its
-standard value is -2 and results in code like this:
-
- switch (c)
- {
- case 'x':
-
-If `c-label-offset' were zero, the same code would be indented as:
-
- switch (c)
- {
- case 'x':
-
-This example assumes that the other variables above also have their
-default values.
-
- Using the indentation style produced by the default settings of the
-variables just discussed and putting open braces on separate lines
-produces clear and readable files. For an example, look at any of the C
-source files of XEmacs.
-