-\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.
-
-\1f
-File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
-
-Automatic Display of Matching Parentheses
-=========================================
-
- The Emacs parenthesis-matching feature shows you automatically how
-parentheses match in the text. Whenever a self-inserting character that
-is a closing delimiter is typed, the cursor moves momentarily to the
-location of the matching opening delimiter, provided that is visible on
-the screen. If it is not on the screen, some text starting with that
-opening delimiter is displayed in the echo area. Either way, you see
-the grouping you are closing off.
-
- In Lisp, automatic matching applies only to parentheses. In C, it
-also applies to braces and brackets. Emacs knows which characters to
-regard as matching delimiters based on the syntax table set by the major
-mode. *Note Syntax::.
-
- If the opening delimiter and closing delimiter are mismatched--as in
-`[x)'--the echo area displays a warning message. The correct matches
-are specified in the syntax table.
-
- Two variables control parenthesis matching displays.
-`blink-matching-paren' turns the feature on or off. The default is `t'
-(match display is on); `nil' turns it off.
-`blink-matching-paren-distance' specifies how many characters back
-Emacs searches to find a matching opening delimiter. If the match is
-not found in the specified region, scanning stops, and nothing is
-displayed. This prevents wasting lots of time scanning when there is no
-match. The default is 4000.
-
-\1f
-File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
-
-Manipulating Comments
-=====================
-
- The comment commands insert, kill and align comments.
-
-`M-;'
- Insert or align comment (`indent-for-comment').
-
-`C-x ;'
- Set comment column (`set-comment-column').
-
-`C-u - C-x ;'
- Kill comment on current line (`kill-comment').
-
-`M-<LFD>'
- Like <RET> followed by inserting and aligning a comment
- (`indent-new-comment-line').
-
- The command that creates a comment is `Meta-;'
-(`indent-for-comment'). If there is no comment already on the line, a
-new comment is created and aligned at a specific column called the
-"comment column". Emacs creates the comment by inserting the string at
-the value of `comment-start'; see below. Point is left after that
-string. If the text of the line extends past the comment column,
-indentation is done to a suitable boundary (usually, at least one space
-is inserted). If the major mode has specified a string to terminate
-comments, that string is inserted after point, to keep the syntax valid.
-
- You can also use `Meta-;' to align an existing comment. If a line
-already contains the string that starts comments, `M-;' just moves
-point after it and re-indents it to the conventional place. Exception:
-comments starting in column 0 are not moved.
-
- Some major modes have special rules for indenting certain kinds of
-comments in certain contexts. For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column. Comments which start with three
-semicolons are supposed to start at the left margin. Emacs understands
-these conventions by indenting a double-semicolon comment using <TAB>
-and by not changing the indentation of a triple-semicolon comment at
-all.
-
- ;; This function is just an example.
- ;;; Here either two or three semicolons are appropriate.
- (defun foo (x)
- ;;; And now, the first part of the function:
- ;; The following line adds one.
- (1+ x)) ; This line adds one.
-
- In C code, a comment preceded on its line by nothing but whitespace
-is indented like a line of code.
-
- Even when an existing comment is properly aligned, `M-;' is still
-useful for moving directly to the start of the comment.
-
- `C-u - C-x ;' (`kill-comment') kills the comment on the current
-line, if there is one. The indentation before the start of the comment
-is killed as well. If there does not appear to be a comment in the
-line, nothing happens. To reinsert the comment on another line, move
-to the end of that line, type first `C-y', and then `M-;' to realign
-the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
-;' (`set-comment-column') with a negative argument. That command is
-programmed to call `kill-comment' when called with a negative argument.
-However, `kill-comment' is a valid command which you could bind
-directly to a key if you wanted to.
-
-Multiple Lines of Comments
---------------------------
-
- If you are typing a comment and want to continue it on another line,
-use the command `Meta-<LFD>' (`indent-new-comment-line'), which
-terminates the comment you are typing, creates a new blank line
-afterward, and begins a new comment indented under the old one. If
-Auto Fill mode is on and you go past the fill column while typing, the
-comment is continued in just this fashion. If point is not at the end
-of the line when you type `M-<LFD>', the text on the rest of the line
-becomes part of the new comment line.
-
-Options Controlling Comments
-----------------------------
-
- The comment column is stored in the variable `comment-column'. You
-can explicitly set it to a number. Alternatively, the command `C-x ;'
-(`set-comment-column') sets the comment column to the column point is
-at. `C-u C-x ;' sets the comment column to match the last comment
-before point in the buffer, and then calls `Meta-;' to align the
-current line's comment under the previous one. Note that `C-u - C-x ;'
-runs the function `kill-comment' as described above.
-
- `comment-column' is a per-buffer variable; altering the variable
-affects only the current buffer. You can also change the default value.
-*Note Locals::. Many major modes initialize this variable for the
-current buffer.
-
- The comment commands recognize comments based on the regular
-expression that is the value of the variable `comment-start-skip'.
-This regexp should not match the null string. It may match more than
-the comment starting delimiter in the strictest sense of the word; for
-example, in C mode the value of the variable is `"/\\*+ *"', which
-matches extra stars and spaces after the `/*' itself. (Note that `\\'
-is needed in Lisp syntax to include a `\' in the string, which is needed
-to deny the first star its special meaning in regexp syntax. *Note
-Regexps::.)
-
- When a comment command makes a new comment, it inserts the value of
-`comment-start' to begin it. The value of `comment-end' is inserted
-after point and will follow the text you will insert into the comment.
-In C mode, `comment-start' has the value `"/* "' and `comment-end' has
-the value `" */"'.
-
- `comment-multi-line' controls how `M-<LFD>'
-(`indent-new-comment-line') behaves when used inside a comment. If
-`comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
-terminates the comment on the starting line and starts a new comment on
-the new following line. If `comment-multi-line' is not `nil', then
-`M-<LFD>' sets up the new following line as part of the same comment
-that was found on the starting line. This is done by not inserting a
-terminator on the old line and not inserting a starter on the new line.
-In languages where multi-line comments are legal, the value you choose
-for this variable is a matter of taste.
-
- The variable `comment-indent-hook' should contain a function that is
-called to compute the indentation for a newly inserted comment or for
-aligning an existing comment. Major modes set this variable
-differently. The function is called with no arguments, but with point
-at the beginning of the comment, or at the end of a line if a new
-comment is to be inserted. The function should return the column in
-which the comment ought to start. For example, in Lisp mode, the
-indent hook function bases its decision on the number of semicolons
-that begin an existing comment and on the code in the preceding lines.
-
-\1f
-File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
-
-Editing Without Unbalanced Parentheses
-======================================
-
-`M-('
- Put parentheses around next sexp(s) (`insert-parentheses').
-
-`M-)'
- Move past next close parenthesis and re-indent
- (`move-over-close-and-reindent').
-
- The commands `M-(' (`insert-parentheses') and `M-)'
-(`move-over-close-and-reindent') are designed to facilitate a style of
-editing which keeps parentheses balanced at all times. `M-(' inserts a
-pair of parentheses, either together as in `()', or, if given an
-argument, around the next several sexps, and leaves point after the open
-parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
-which has the same effect except for leaving the cursor before the
-close parenthesis. You can then type `M-)', which moves past the close
-parenthesis, deletes any indentation preceding it (in this example
-there is none), and indents with <LFD> after it.
-
-\1f
-File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
-
-Completion for Lisp Symbols
-===========================
-
- Completion usually happens in the minibuffer. An exception is
-completion for Lisp symbol names, which is available in all buffers.
-
- The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
-Lisp symbol before point to be an abbreviation, and compares it against
-all non-trivial Lisp symbols currently known to Emacs. Any additional
-characters that they all have in common are inserted at point.
-Non-trivial symbols are those that have function definitions, values, or
-properties.
-
- If there is an open-parenthesis immediately before the beginning of
-the partial symbol, only symbols with function definitions are
-considered as completions.
-
- If the partial name in the buffer has more than one possible
-completion and they have no additional characters in common, a list of
-all possible completions is displayed in another window.
-
-\1f
-File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
-
-Documentation Commands
-======================
-
- As you edit Lisp code to be run in Emacs, you can use the commands
-`C-h f' (`describe-function') and `C-h v' (`describe-variable') to
-print documentation of functions and variables you want to call. These
-commands use the minibuffer to read the name of a function or variable
-to document, and display the documentation in a window.
-
- For extra convenience, these commands provide default arguments
-based on the code in the neighborhood of point. `C-h f' sets the
-default to the function called in the innermost list containing point.
-`C-h v' uses the symbol name around or adjacent to point as its default.
-
- The `M-x manual-entry' command gives you access to documentation on
-Unix commands, system calls, and libraries. The command reads a topic
-as an argument, and displays the Unix manual page for that topic.
-`manual-entry' always searches all 8 sections of the manual and
-concatenates all the entries it finds. For example, the topic
-`termcap' finds the description of the termcap library from section 3,
-followed by the description of the termcap data base from section 5.
-