![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs-7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info|
Return to emacs-7 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info |
1.1 root 1: Info file emacs, produced by texinfo-format-buffer -*-Text-*-
2: from file emacs.tex
3:
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985, 1986 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of this
13: manual under the conditions for verbatim copying, provided also that the
14: sections entitled "The GNU Manifesto", "Distribution" and "GNU Emacs
15: General Public License" are included exactly as in the original, and
16: provided that the entire resulting derived work is distributed under the
17: terms of a permission notice identical to this one.
18:
19: Permission is granted to copy and distribute translations of this manual
20: into another language, under the above conditions for modified versions,
21: except that the sections entitled "The GNU Manifesto", "Distribution"
22: and "GNU Emacs General Public License" may be included in a translation
23: approved by the author instead of in the original English.
24:
25:
26: File: emacs Node: Defuns, Prev: Lists, Up: Programs, Next: Grinding
27:
28: Defuns
29: ======
30:
31: In Emacs, a parenthetical grouping at the top level in the buffer is
32: called a "defun". The name derives from the fact that most top-level
33: lists in a Lisp file are instances of the special form `defun', but
34: any top-level parenthetical grouping counts as a defun in Emacs parlance
35: regardless of what its contents are, and regardless of the programming
36: language in use. For example, in C, the body of a function definition is a
37: defun.
38:
39: `C-M-a'
40: Move to beginning of current or preceding defun
41: (`beginning-of-defun').
42: `C-M-e'
43: Move to end of current or following defun (`end-of-defun').
44: `C-M-h'
45: Put region around whole current or following defun (`mark-defun').
46:
47: The commands to move to the beginning and end of the current defun are
48: `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
49:
50: If you wish to operate on the current defun, use `C-M-h'
51: (`mark-defun') which puts point at the beginning and mark at the end
52: of the current or next defun. For example, this is the easiest way to get
53: ready to move the defun to a different place in the text. In C mode,
54: `C-M-h' runs the function `mark-c-function', which is almost the
55: same as `mark-defun'; the difference is that it backs up over the
56: argument declarations, function name and returned data type so that the
57: entire C function is inside the region.
58:
59: Emacs assumes that any open-parenthesis found in the leftmost column is
60: the start of a defun. Therefore, never put an open-parenthesis at the
61: left margin in a Lisp file unless it is the start of a top level list.
62: Never put an open-brace or other opening delimiter at the beginning of a
63: line of C code unless it starts the body of a function. The most likely
64: problem case is when you want an opening delimiter at the start of a line
65: inside a string. To avoid trouble, put an escape character (`\', in C
66: and Emacs Lisp, `/' in some other Lisp dialects) before the opening
67: delimiter. It will not affect the contents of the string.
68:
69: In the remotest past, the original Emacs found defuns by moving upward a
70: level of parentheses until there were no more levels to go up. This always
71: required scanning all the way back to the beginning of the buffer, even for
72: a small function. To speed up the operation, Emacs was changed to assume
73: that any `(' (or other character assigned the syntactic class of
74: opening-delimiter) at the left margin is the start of a defun. This
75: heuristic was nearly always right and avoided the costly scan; however,
76: it mandated the convention described above.
77:
78:
79: File: emacs Node: Grinding, Prev: Defuns, Up: Programs, Next: Matching
80:
81: Indentation for Programs
82: ========================
83:
84: The best way to keep a program properly indented ("ground") is to use
85: Emacs to re-indent it as you change it. Emacs has commands to indent
86: properly either a single line, a specified number of lines, or all of the
87: lines inside a single parenthetical grouping.
88:
89: * Menu:
90:
91: * Basic Indent::
92: * Multi-line Indent:: Commands to reindent many lines at once.
93: * Lisp Indent:: Specifying how each Lisp function should be indented.
94: * C Indent:: Choosing an indentation style for C code.
95:
96:
97: File: emacs Node: Basic Indent, Prev: Grinding, Up: Grinding, Next: Multi-line Indent
98:
99: Basic Program Indentation Commands
100: ----------------------------------
101:
102: `TAB'
103: Adjust indentation of current line.
104: `LFD'
105: Equivalent to RET followed by TAB (`newline-and-indent').
106:
107: The basic indentation command is TAB, which gives the current line
108: the correct indentation as determined from the previous lines. The
109: function that TAB runs depends on the major mode; it is `lisp-indent-line'
110: in Lisp mode, `c-indent-line' in C mode, etc. These functions
111: understand different syntaxes for different languages, but they all do
112: about the same thing. TAB in any programming language major mode
113: inserts or deletes whitespace at the beginning of the current line,
114: independent of where point is in the line. If point is inside the
115: whitespace at the beginning of the line, TAB leaves it at the end of
116: that whitespace; otherwise, TAB leaves point fixed with respect to
117: the characters around it.
118:
119: Use `C-q TAB' to insert a tab at point.
120:
121: When entering a large amount of new code, use LFD (`newline-and-indent'),
122: which is equivalent to a RET followed by a TAB. LFD creates
123: a blank line, and then gives it the appropriate indentation.
124:
125: TAB indents the second and following lines of the body of an
126: parenthetical grouping each under the preceding one; therefore, if you
127: alter one line's indentation to be nonstandard, the lines below will tend
128: to follow it. This is the right behavior in cases where the standard
129: result of TAB is unaesthetic.
130:
131: Remember that an open-parenthesis, open-brace or other opening delimiter
132: at the left margin is assumed by Emacs (including the indentation routines)
133: to be the start of a function. Therefore, you must never have an opening
134: delimiter in column zero that is not the beginning of a function, not even
135: inside a string. This restriction is vital for making the indentation
136: commands fast; you must simply accept it. *Note Defuns::, for more
137: information on this.
138:
139:
140: File: emacs Node: Multi-line Indent, Prev: Basic Indent, Up: Grinding, Next: Lisp Indent
141:
142: Indenting Several Lines
143: -----------------------
144:
145: When you wish to re-indent several lines of code which have been altered
146: or moved to a different level in the list structure, you have several
147: commands available.
148:
149: `C-M-q'
150: Re-indent all the lines within one list (`indent-sexp').
151: `C-u TAB'
152: Shift an entire list rigidly sideways so that its first line
153: is properly indented.
154: `C-M-\'
155: Re-indent all lines in the region (`indent-region').
156:
157: You can re-indent the contents of a single list by positioning point
158: before the beginning of it and typing `C-M-q' (`indent-sexp' in
159: Lisp mode, `indent-c-exp' in C mode; also bound to other suitable
160: functions in other modes). The indentation of the line the sexp starts on
161: is not changed; therefore, only the relative indentation within the list,
162: and not its position, is changed. To correct the position as well, type a
163: TAB before the `C-M-q'.
164:
165: If the relative indentation within a list is correct but the indentation
166: of its beginning is not, go to the line the list begins on and type
167: `C-u TAB'. When TAB is given a numeric argument, it moves all the
168: lines in the grouping starting on the current line sideways the same amount
169: that the current line moves. It is clever, though, and does not move lines
170: that start inside strings, or C preprocessor lines when in C mode.
171:
172: Another way to specify the range to be re-indented is with point and
173: mark. The command `C-M-\' (`indent-region') applies TAB to every line
174: whose first character is between point and mark.
175:
176:
177: File: emacs Node: Lisp Indent, Prev: Multi-line Indent, Up: Grinding, Next: C Indent
178:
179: Customizing Lisp Indentation
180: ----------------------------
181:
182: The indentation pattern for a Lisp expression can depend on the function
183: called by the expression. For each Lisp function, you can choose among
184: several predefined patterns of indentation, or define an arbitrary one with
185: a Lisp program.
186:
187: The standard pattern of indentation is as follows: the second line of the
188: expression is indented under the first argument, if that is on the same
189: line as the beginning of the expression; otherwise, the second line is
190: indented underneath the function name. Each following line is indented
191: under the previous line whose nesting depth is the same.
192:
193: If the variable `lisp-indent-offset' is non-`nil', it overrides
194: the usual indentation pattern for the second line of an expression, so that
195: such lines are always indented `lisp-indent-offset' more columns than
196: the containing list.
197:
198: The standard pattern is overridded for certain functions. Functions
199: whose names start with `def' always indent the second line by
200: `lisp-body-indention' extra columns beyond the open-parenthesis
201: starting the expression.
202:
203: The standard pattern can be overridden in various ways for individual
204: functions, according to the `lisp-indent-hook' property of the
205: function name. There are four possibilities for this property:
206:
207: `nil'
208: This is the same as no property; the standard indentation pattern is used.
209: `defun'
210: The pattern used for function names that start with `def' is used for
211: this function also.
212: a number, NUMBER
213: The first NUMBER arguments of the function are
214: "distinguished" arguments; the rest are considered the "body"
215: of the expression. A line in the expression is indented according to
216: whether the first argument on it is distinguished or not. If the
217: argument is part of the body, the line is indented `lisp-body-indent'
218: more columns than the open-parenthesis starting the containing
219: expression. If the argument is distinguished and is either the first
220: or second argument, it is indented twice that many extra columns.
221: If the argument is distinguished and not the first or second argument,
222: the standard pattern is followed for that line.
223: a symbol, SYMBOL
224: SYMBOL should be a function name; that function is called to
225: calculate the indentation of a line within this expression. The
226: function receives two arguments:
227: STATE
228: The value returned by `parse-partial-sexp' (a Lisp primitive for
229: indentation and nesting computation) when it parses up to the
230: beginning of this line.
231: POS
232: The position at which the line being indented begins.
233: It should return either a number, which is the number of columns of
234: indentation for that line, or a list whose car is such a number. The
235: difference between returning a number and returning a list is that a
236: number says that all following lines at the same nesting level should
237: be indented just like this one; a list says that following lines might
238: call for different indentations. This makes a difference when the
239: indentation is being computed by `C-M-q'; if the value is a
240: number, `C-M-q' need not recalculate indentation for the following
241: lines until the end of the list.
242:
243:
244: File: emacs Node: C Indent, Prev: Lisp Indent, Up: Grinding
245:
246: Customizing C Indentation
247: -------------------------
248:
249: Two variables control which commands perform C indentation and when.
250:
251: If `c-auto-newline' is non-`nil', newlines are inserted both
252: before and after braces that you insert, and after colons and semicolons.
253: Correct C indentation is done on all the lines that are made this way.
254:
255: If `c-tab-always-indent' is non-`nil', the TAB command
256: in C mode does indentation only if point is at the left margin or within
257: the line's indentation. If there is non-whitespace to the left of point,
258: then TAB just inserts a tab character in the buffer. Normally,
259: this variable is `nil', and TAB always reindents the current line.
260:
261: C does not have anything analogous to particular function names for which
262: special forms of indentation are desirable. However, it has a different
263: need for customization facilities: many different styles of C indentation
264: are in common use.
265:
266: There are six variables you can set to control the style that Emacs C
267: mode will use.
268:
269: `c-indent-level'
270: Indentation of C statements within surrounding block. The surrounding
271: block's indentation is the indentation of the line on which the
272: open-brace appears.
273: `c-continued-statement-offset'
274: Extra indentation given to a substatement, such as the then-clause of
275: an if or body of a while.
276: `c-brace-offset'
277: Extra indentation for line if it starts with an open brace.
278: `c-brace-imaginary-offset'
279: An open brace following other text is treated as if it were this far
280: to the right of the start of its line.
281: `c-argdecl-indent'
282: Indentation level of declarations of C function arguments.
283: `c-label-offset'
284: Extra indentation for line that is a label, or case or default.
285:
286: The variable `c-indent-level' controls the indentation for C
287: statements with respect to the surrounding block. In the example
288:
289: {
290: foo ();
291:
292: the difference in indentation between the lines is `c-indent-level'.
293: Its standard value is 2.
294:
295: If the open-brace beginning the compound statement is not at the beginning
296: of its line, the `c-indent-level' is added to the indentation of the
297: line, not the column of the open-brace. For example,
298:
299: if (losing) {
300: do_this ();
301:
302: One popular indentation style is that which results from setting
303: `c-indent-level' to 8 and putting open-braces at the end of a line in
304: this way. I prefer to put the open-brace on a separate line.
305:
306: In fact, the value of the variable `c-brace-imaginary-offset' is
307: also added to the indentation of such a statement. Normally this variable
308: is zero. Think of this variable as the imaginary position of the open
309: brace, relative to the first nonblank character on the line. By setting
310: this variable to 4 and `c-indent-level' to 0, you can get this style:
311:
312: if (x == y) {
313: do_it ();
314: }
315:
316: When `c-indent-level' is zero, the statements inside most braces
317: will line up right under the open brace. But there is an exception made
318: for braces in column zero, such as surrounding a function's body. The
319: statements just inside it do not go at column zero. Instead,
320: `c-brace-offset' and `c-continued-statement-offset' (see below)
321: are added to produce a typical offset between brace levels, and the
322: statements are indented that far.
323:
324: `c-continued-statement-offset' controls the extra indentation for a
325: line that starts within a statement (but not within parentheses or
326: brackets). These lines are usually statements that are within other
327: statements, such as the then-clauses of `if' statements and the bodies
328: of `while' statements. This parameter is the difference in
329: indentation between the two lines in
330:
331: if (x == y)
332: do_it ();
333:
334: Its standard value is 2. Some popular indentation styles correspond to a
335: value of zero for `c-continued-statement-offset'.
336:
337: `c-brace-offset' is the extra indentation given to a line that
338: starts with an open-brace. Its standard value is zero;
339: compare
340:
341: if (x == y)
342: {
343:
344: with
345:
346: if (x == y)
347: do_it ();
348:
349: if `c-brace-offset' were set to 4, the first example would become
350:
351: if (x == y)
352: {
353:
354: `c-argdecl-indent' controls the indentation of declarations of the
355: arguments of a C function. It is absolute: argument declarations receive
356: exactly `c-argdecl-indent' spaces. The standard value is 5, resulting
357: in code like this:
358:
359: char *
360: index (string, char)
361: char *string;
362: int char;
363:
364: `c-label-offset' is the extra indentation given to a line that
365: contains a label, a case statement, or a `default:' statement. Its
366: standard value is -2, resulting in code like this
367:
368: switch (c)
369: {
370: case 'x':
371:
372: If `c-label-offset' were zero, the same code would be indented as
373:
374: switch (c)
375: {
376: case 'x':
377:
378: This example assumes that the other variables above also have their
379: standard values.
380:
381: I strongly recommend that you try out the indentation style produced by
382: the standard settings of these variables, together with putting open braces
383: on separate lines. You can see how it looks in all the C source files of
384: GNU Emacs.
385:
386:
387: File: emacs Node: Matching, Prev: Grinding, Up: Programs, Next: Comments
388:
389: Automatic Display Of Matching Parentheses
390: =========================================
391:
392: The Emacs parenthesis-matching feature is designed to show automatically
393: how parentheses match in the text. Whenever a self-inserting character
394: that is a closing delimiter is typed, the cursor moves momentarily to the
395: location of the matching opening delimiter, provided that is on the screen.
396: If it is not on the screen, some text starting with that opening delimiter
397: is displayed in the echo area. Either way, you can tell what grouping is
398: being closed off.
399:
400: In Lisp, automatic matching applies only to parentheses. In C, it
401: applies to braces and brackets too. Emacs knows which characters to regard
402: as matching delimiters based on the syntax table, which is set by the major
403: mode. *Note Syntax::.
404:
405: If the opening delimiter and closing delimiter are mismatched---such as
406: in `[x)'---a warning message is displayed in the echo area. The
407: correct matches are specified in the syntax table.
408:
409: Two variables control parenthesis match display. `blink-matching-paren'
410: turns the feature on or off; `nil' turns it off, but the default is
411: `t' to turn match display on. `blink-matching-paren-distance'
412: specifies how many characters back to search to find the matching opening
413: delimiter. If the match is not found in that far, scanning stops, and
414: nothing is displayed. This is to prevent scanning for the matching
415: delimiter from wasting lots of time when there is no match. The default
416: is 4000.
417:
418:
419: File: emacs Node: Comments, Prev: Matching, Up: Programs, Next: Balanced Editing
420:
421: Manipulating Comments
422: =====================
423:
424: The comment commands insert, kill and align comments.
425:
426: `M-;'
427: Insert or align comment (`indent-for-comment').
428: `C-x ;'
429: Set comment column (`set-comment-column').
430: `C-u - C-x ;'
431: Kill comment on current line (`kill-comment').
432: `M-LFD'
433: Like RET followed by inserting and aligning a comment
434: (`indent-new-comment-line').
435:
436: The command that creates a comment is `Meta-;' (`indent-for-comment').
437: If there is no comment already on the line, a new comment is created,
438: aligned at a specific column called the "comment column". The comment
439: is created by inserting the string Emacs thinks comments should start with
440: (the value of `comment-start'; see below). Point is left after that
441: string. If the text of the line extends past the comment column, then the
442: indentation is done to a suitable boundary (usually, at least one space is
443: inserted). If the major mode has specified a string to terminate comments,
444: that is inserted after point, to keep the syntax valid.
445:
446: `Meta-;' can also be used to align an existing comment. If a line
447: already contains the string that starts comments, then `M-;' just moves
448: point after it and re-indents it to the conventional place. Exception:
449: comments starting in column 0 are not moved.
450:
451: Some major modes have special rules for indenting certain kinds of
452: comments in certain contexts. For example, in Lisp code, comments which
453: start with two semicolons are indented as if they were lines of code,
454: instead of at the comment column. Comments which start with three
455: semicolons are supposed to start at the left margin. Emacs understands
456: these conventions by indenting a double-semicolon comment using TAB,
457: and by not changing the indentation of a triple-semicolon comment at all.
458:
459: ;; This function is just an example
460: ;;; Here either two or three semicolons are appropriate.
461: (defun foo (x)
462: ;;; And now, the first part of the function:
463: ;; The following line adds one.
464: (1+ x)) ; This line adds one.
465:
466: In C code, a comment preceded on its line by nothing but whitespace
467: is indented like a line of code.
468:
469: Even when an existing comment is properly aligned, `M-;' is still
470: useful for moving directly to the start of the comment.
471:
472: `C-u - C-x ;' (`kill-comment') kills the comment on the current line,
473: if there is one. The indentation before the start of the comment is killed
474: as well. If there does not appear to be a comment in the line, nothing is
475: done. To reinsert the comment on another line, move to the end of that
476: line, do `C-y', and then do `M-;' to realign it. Note that
477: `C-u - C-x ;' is not a distinct key; it is `C-x ;' (`set-comment-column')
478: with a negative argument. That command is programmed so that when it
479: receives a negative argument it calls `kill-comment'. However,
480: `kill-comment' is a valid command which you could bind directly to a
481: key if you wanted to.
482:
483:
484: Multiple Lines of Comments
485: --------------------------
486:
487: If you are typing a comment and find that you wish to continue it on
488: another line, you can use the command `Meta-LFD' (`indent-new-comment-line'),
489: which terminates the comment you are typing, creates a new blank line
490: afterward, and begins a new comment indented under the old one. When Auto
491: Fill mode is on, going past the fill column while typing a comment causes
492: the comment to be continued in just this fashion. If point is not at the
493: end of the line when `M-LFD' is typed, the text on the rest of
494: the line becomes part of the new comment line.
495:
496:
497: Options Controlling Comments
498: ----------------------------
499:
500: The comment column is stored in the variable `comment-column'. You
501: can set it to a number explicitly. Alternatively, the command `C-x ;'
502: (`set-comment-column') sets the comment column to the column point is
503: at. `C-u C-x ;' sets the comment column to match the last comment
504: before point in the buffer, and then does a `Meta-;' to align the
505: current line's comment under the previous one. Note that `C-u - C-x ;'
506: runs the function `kill-comment' as described above.
507:
508: `comment-column' is a per-buffer variable; altering the variable
509: affects only the current buffer, but there is a default value which you can
510: change as well. *Note Locals::. Many major modes initialize this variable
511: for the current buffer.
512:
513: The comment commands recognize comments based on the regular expression
514: that is the value of the variable `comment-start-skip'. This regexp
515: should not match the null string. It may match more than the comment
516: starting delimiter in the strictest sense of the word; for example, in C
517: mode the value of the variable is `"/\\*+ *"', which matches extra
518: stars and spaces after the `/*' itself. (Note that `\\' is
519: needed in Lisp syntax to include a `\' in the string, which is needed
520: to deny the first star its special meaning in regexp syntax. *Note Regexps::.)
521:
522: When a comment command makes a new comment, it inserts the value of
523: `comment-start' to begin it. The value of `comment-end' is
524: inserted after point, so that it will follow the text that you will insert
525: into the comment. In C mode, `comment-start' has the value
526: `"/* "' and `comment-end' has the value `" */"'.
527:
528: `comment-multi-line' controls how `M-LFD' (`indent-new-comment-line')
529: behaves when used inside a comment. If `comment-multi-line' is
530: `nil', as it normally is, then the comment on the starting line is
531: terminated and a new comment is started on the new following line. If
532: `comment-multi-line' is not `nil', then the new following line is
533: set up as part of the same comment that was found on the starting line.
534: This is done by not inserting a terminator on the old line, and not
535: inserting a starter on the new line. In languages where multi-line comments
536: work, the choice of value for this variable is a matter of taste.
537:
538: The variable `comment-indent-hook' should contain a function that
539: will be called to compute the indentation for a newly inserted comment or
540: for aligning an existing comment. It is set differently by various major
541: modes. The function is called with no arguments, but with point at the
542: beginning of the comment, or at the end of a line if a new comment is to be
543: inserted. It should return the column in which the comment ought to start.
544: For example, in Lisp mode, the indent hook function bases its decision
545: on how many semicolons begin an existing comment, and on the code in the
546: preceding lines.
547:
548:
549: File: emacs Node: Balanced Editing, Prev: Comments, Up: Programs, Next: Lisp Completion
550:
551: Editing Without Unbalanced Parentheses
552: ======================================
553:
554: `M-('
555: Put parentheses around next sexp(s) (`insert-parentheses').
556: `M-)'
557: Move past next close parenthesis and re-indent
558: (`move-over-close-and-reindent').
559:
560: The commands `M-(' (`insert-parentheses') and `M-)'
561: (`move-over-close-and-reindent') are designed to facilitate a style of
562: editing which keeps parentheses balanced at all times. `M-(' inserts a
563: pair of parentheses, either together as in `()', or, if given an
564: argument, around the next several sexps, and leaves point after the open
565: parenthesis. Instead of typing `( F O O )', you can type `M-( F O
566: O', which has the same effect except for leaving the cursor before the
567: close parenthesis. Then you would type `M-)', which moves past the
568: close parenthesis, deleting any indentation preceding it (in this example
569: there is none), and indenting with LFD after it.
570:
571:
572: File: emacs Node: Lisp Completion, Prev: Balanced Editing, Up: Programs, Next: Documentation
573:
574: Completion for Lisp Symbols
575: ===========================
576:
577: Usually completion happens in the minibuffer. But one kind of completion
578: is available in all buffers: completion for Lisp symbol names.
579:
580: The command `M-TAB' (`lisp-complete-symbol') takes the
581: partial Lisp symbol before point to be an abbreviation, and compares it
582: against all nontrivial Lisp symbols currently known to Emacs. Any
583: additional characters that they all have in common are inserted at point.
584: Nontrivial symbols are those that have function definitions, values or
585: properties.
586:
587: If there is an open-parenthesis immediately before the beginning of
588: the partial symbol, only symbols with function definitions are considered
589: as completions.
590:
591: If the partial name in the buffer has more than one possible completion
592: and they have no additional characters in common, a list of all possible
593: completions is displayed in another window.
594:
595:
596: File: emacs Node: Documentation, Prev: Lisp Completion, Up: Programs, Next: Change Log
597:
598: Documentation Commands
599: ======================
600:
601: As you edit Lisp code to be run in Emacs, the commands `C-h f'
602: (`describe-function') and `C-h v' (`describe-variable') can
603: be used to print documentation of functions and variables that you want to
604: call. These commands use the minibuffer to read the name of a function or
605: variable to document, and display the documentation in a window.
606:
607: For extra convenience, these commands provide default arguments based on
608: the code in the neighborhood of point. `C-h f' sets the default to the
609: function called in the innermost list containing point. `C-h v' uses
610: the symbol name around or adjacent to point as its default.
611:
612: Documentation on Unix commands, system calls and libraries can be
613: obtained with the `M-x manual-entry' command. This reads a topic as an
614: argument, and displays the text on that topic from the Unix manual.
615: `manual-entry' always searches all 8 sections of the manual, and
616: concatenates all the entries that are found. For example, the topic
617: `termcap' finds the description of the termcap library from section 3,
618: followed by the description of the termcap data base from section 5.
619:
620:
621: File: emacs Node: Change Log, Prev: Documentation, Up: Programs, Next: Tags
622:
623: Change Logs
624: ===========
625:
626: The Emacs command `M-x add-change-log-entry' helps you keep a record
627: of when and why you have changed a program. It assumes that you have a
628: file in which you write a chronological sequence of entries describing
629: individual changes. The default is to store the change entries in a file
630: called `ChangeLog' in the same directory as the file you are editing.
631: The same `ChangeLog' file therefore records changes for all the files
632: in the directory.
633:
634: A change log entry starts with a header line that contains your name and
635: the current date. Aside from these header lines, every line in the change
636: log starts with a tab. One entry can describe several changes; each change
637: starts with a line starting with a tab and a star. `M-x add-change-log-entry'
638: visits the change log file and creates a new entry unless the most recent
639: entry is for today's date and your name. In either case, it adds a new
640: line to start the description of another change just after the header line
641: of the entry. When `M-x add-change-log-entry' is finished, all is
642: prepared for you to edit in the description of what you changed and how.
643: You must then save the change log file yourself.
644:
645: The change log file is always visited in Indented Text mode, which means
646: that LFD and auto-filling indent each new line like the previous
647: line. This is convenient for entering the contents of an entry, which must
648: all be indented. *Note Text Mode::.
649:
650: Here is an example of the formatting conventions used in the change log
651: for Emacs:
652:
653: Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
654:
655: * xdisp.c (try_window_id):
656: If C-k is done at end of next-to-last line,
657: this fn updates window_end_vpos and cannot leave
658: window_end_pos nonnegative (it is zero, in fact).
659: If display is preempted before lines are output,
660: this is inconsistent. Fix by setting
661: blank_end_of_window to nonzero.
662:
663: Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
664:
665: * cmds.c (Fnewline):
666: Call the auto fill hook if appropriate.
667:
668: * xdisp.c (try_window_id):
669: If point is found by compute_motion after xp, record that
670: permanently. If display_text_line sets point position wrong
671: (case where line is killed, point is at eob and that line is
672: not displayed), set it again in final compute_motion.
673:
674:
675: File: emacs Node: Tags, Prev: Change Log, Up: Programs, Next: Fortran
676:
677: Tag Tables
678: ==========
679:
680: A "tag table" is a description of how a multi-file program is broken
681: up into files. It lists the names of the component files and the names and
682: positions of the functions in each file. Grouping the related files makes
683: it possible to search or replace through all the files with one command.
684: Recording the function names and positions makes possible the `Meta-.'
685: command which you can use to find the definition of a function without
686: having to know which of the files it is in.
687:
688: Tag tables are stored in files called "tag table files". The
689: conventional name for a tag table file is `TAGS'.
690:
691: Each entry in the tag table records the name of one tag, the name of the
692: file that the tag is defined in (implicitly), and the position in that file
693: of the tag's definition.
694:
695: Just what names from the described files are recorded in the tag table
696: depends on the programming language of the described file. They normally
697: include all functions and subroutines, and may also include global
698: variables, data types, and anything else convenient. In any case, each
699: name recorded is called a "tag".
700:
701: * Menu:
702:
703: * Tag Syntax::
704: * Create Tag Table::
705: * Select Tag Table::
706: * Find Tag::
707: * Tags Search::
708: * Tags Stepping::
709: * List Tags::
710:
711:
712: File: emacs Node: Tag Syntax, Prev: Tags, Up: Tags, Next: Create Tag Table
713:
714: Source File Tag Syntax
715: ----------------------
716:
717: In Lisp code, any function defined with `defun', any variable
718: defined with `defvar' or `defconst', and in general the first
719: argument of any expression that starts with `(def' in column zero, is
720: a tag.
721:
722: In C code, any C function is a tag, and so is any typedef if `-t' is
723: specified when the tag table is constructed.
724:
725: In Fortran code, functions and subroutines are tags.
726:
727: In LaTeX text, the argument of any of the commands `\chapter',
728: `\section', `\subsection', `\subsubsection', `\eqno', `\label', `\ref',
729: `\cite', `\bibitem' and `\typeout' is a tag.
730:
731:
732: File: emacs Node: Create Tag Table, Prev: Tag Syntax, Up: Tags, Next: Select Tag Table
733:
734: Creating Tag Tables
735: -------------------
736:
737: The `etags' program is used to create a tag table file. It knows
738: the syntax of C, Fortran, LaTeX, Scheme and Emacs Lisp/Common Lisp. To
739: use `etags', type
740:
741: etags INPUTFILES...
742:
743: as a shell command. It reads the specified files and writes a tag table
744: named `TAGS' in the current working directory. `etags'
745: recognizes the language used in an input file based on its file name and
746: contents; there are no switches for specifying the language. The `-t'
747: switch tells `etags' to record typedefs in C code as tags.
748:
749: If the tag table data become outdated due to changes in the files
750: described in the table, the way to update the tag table is the same way it
751: was made in the first place. It is not necessary to do this often.
752:
753: If the tag table fails to record a tag, or records it for the wrong file,
754: then Emacs cannot possibly find its definition. However, if the position
755: recorded in the tag table becomes a little bit wrong (due to some editing
756: in the file that the tag definition is in), the only consequence is to slow
757: down finding the tag slightly. Even if the stored position is very wrong,
758: Emacs will still find the tag, but it must search the entire file for it.
759:
760: So you should update a tag table when you define new tags that you want
761: to have listed, or when you move tag definitions from one file to another,
762: or when changes become substantial. Normally there is no need to update
763: the tag table after each edit, or even every day.
764:
765:
766: File: emacs Node: Select Tag Table, Prev: Create Tag Table, Up: Tags, Next: Find Tag
767:
768: Selecting a Tag Table
769: ---------------------
770:
771: Emacs has at any time one "selected" tag table, and all the commands
772: for working with tag tables use the selected one. To select a tag table,
773: type `M-x visit-tags-table', which reads the tag table file name as an
774: argument. The name `TAGS' in the default directory is used as the
775: default file name.
776:
777: All this command does is store the file name in the variable
778: `tags-file-name'. Emacs does not actually read in the tag table
779: contents until you try to use them. Setting this variable yourself is just
780: as good as using `visit-tags-table'. The variable's initial value is
781: `nil'; this value tells all the commands for working with tag tables
782: that they must ask for a tag table file name to use.
783:
784:
785: File: emacs Node: Find Tag, Prev: Select Tag Table, Up: Tags, Next: Tags Search
786:
787: Finding a Tag
788: -------------
789:
790: The most important thing that a tag table enables you to do is to find
791: the definition of a specific tag.
792:
793: `M-. TAG'
794: Find first definition of TAG (`find-tag').
795: `C-u M-.'
796: Find next alternate definition of last tag specified.
797: `C-x 4 . TAG'
798: Find first definition of TAG, but display it in another window
799: (`find-tag-other-window').
800:
801: `M-.' (`find-tag') is the command to find the definition of a
802: specified tag. It searches through the tag table for that tag, as a
803: string, and then uses the tag table info to determine the file that the
804: definition is in and the approximate character position in the file of the
805: definition. Then `find-tag' visits that file, moves point to the
806: approximate character position, and starts searching ever-increasing
807: distances away for the the text that should appear at the beginning of the
808: definition.
809:
810: If an empty argument is given (just type RET), the sexp in the
811: buffer before or around point is used as the name of the tag to find.
812: *Note Lists::, for info on sexps.
813:
814: The argument to `find-tag' need not be the whole tag name; it can be
815: a substring of a tag name. However, there can be many tag names containing
816: the substring you specify. Since `find-tag' works by searching the
817: text of the tag table, it finds the first tag in the table that the
818: specified substring appears in. The way to find other tags that match the
819: substring is to give `find-tag' a numeric argument, as in `C-u
820: M-.'; this does not read a tag name, but continues searching the tag
821: table's text for another tag containing the same substring last used. If
822: you have a real META key, `M-0 M-.' is an easier alternative
823: to `C-u M-.'.
824:
825: Like most commands that can switch buffers, `find-tag' has another
826: similar command that displays the new buffer in another window. `C-x 4
827: .' invokes the function `find-tag-other-window'. (This key sequence
828: ends with a period.)
829:
830: Emacs comes with a tag table file `TAGS', in the directory
831: containing Lisp libraries, which includes all the Lisp libraries and all
832: the C sources of Emacs. By specifying this file with `visit-tags-table'
833: and then using `M-.' you can quickly look at the source of any Emacs
834: function.
835:
836:
837: File: emacs Node: Tags Search, Prev: Find Tag, Up: Tags, Next: Tags Stepping
838:
839: Searching and Replacing with Tag Tables
840: ---------------------------------------
841:
842: The commands in this section visit and search all the files listed in the
843: selected tag table, one by one. For these commands, the tag table serves
844: only to specify a sequence of files to search. A related command is
845: `M-x grep' (*Note Compilation::).
846:
847: `M-x tags-search'
848: Search for the specified regexp through the files in the selected tag
849: table.
850: `M-x tags-query-replace'
851: Perform a `query-replace' on each file in the selected tag table.
852: `M-,'
853: Restart one of the commands above, from the current location of point
854: (`tags-loop-continue').
855:
856: `M-x tags-search' reads a regexp using the minibuffer, then visits
857: the files of the selected tag table one by one, and searches through each
858: one for that regexp. It displays the name of the file being searched so
859: you can follow its progress. As soon as an occurrence is found,
860: `tags-search' returns.
861:
862: Having found one match, you probably want to find all the rest. To find
863: one more match, type `M-,' (`tags-loop-continue') to resume the
864: `tags-search'. This searches the rest of the current buffer, followed
865: by the remaining files of the tag table.
866:
867: `M-x tags-query-replace' performs a single `query-replace' through all
868: the files in the tag table. It reads a string to search for and a string
869: to replace with, just like ordinary `M-x query-replace'. It searches much
870: like `M-x tags-search' but repeatedly, processing matches according to your
871: input. *Note Replace::, for more information on `query-replace'.
872:
873: It is possible to get through all the files in the tag table with a
874: single invocation of `M-x tags-query-replace'. But since any
875: unrecognized character causes the command to exit, you may need to continue
876: where you left off. `M-,' can be used for this. It resumes the last
877: tags search or replace command that you did.
878:
879: It may have struck you that `tags-search' is a lot like `grep'.
880: You can also run `grep' itself as an inferior of Emacs and have Emacs
881: show you the matching lines one by one. This works mostly the same as
882: running a compilation and having Emacs show you where the errors were.
883: *Note Compilation::.
884:
885:
886: File: emacs Node: Tags Stepping, Prev: Tags Search, Up: Tags, Next: List Tags
887:
888: Stepping Through a Tag Table
889: ----------------------------
890:
891: If you wish to process all the files in the selected tag table, but
892: `M-x tags-search' and `M-x tags-query-replace' in particular are not what
893: you want, you can use `M-x next-file'.
894:
895: `C-u M-x next-file'
896: With a numeric argument, regardless of its value, visit the first
897: file in the tag table, and prepare to advance sequentially by files.
898: `M-x next-file'
899: Visit the next file in the selected tag table.
900:
901:
902: File: emacs Node: List Tags, Prev: Tags Stepping, Up: Tags
903:
904: Tag Table Inquiries
905: -------------------
906:
907: `M-x list-tags'
908: Display a list of the tags defined in a specific program file.
909: `M-x tags-apropos'
910: Display a list of all tags matching a specified regexp.
911:
912: `M-x list-tags' reads the name of one of the files described by the
913: selected tag table, and displays a list of all the tags defined in that
914: file. The "file name" argument is really just a string to compare
915: against the names recorded in the tag table; it is read as a string rather
916: than as a file name. Therefore, completion and defaulting are not
917: available, and you must enter the string the same way it appears in the tag
918: table. Do not include a directory as part of the file name unless the file
919: name recorded in the tag table includes a directory.
920:
921: `M-x tags-apropos' is like `apropos' for tags. It reads a regexp,
922: then finds all the tags in the selected tag table whose entries match that
923: regexp, and displays the tag names found.
924:
925:
926: File: emacs Node: Fortran, Prev: Tags, Up: Programs
927:
928: Fortran Mode
929: ============
930:
931: Fortran mode provides special motion commands for Fortran statements and
932: subprograms, and indentation commands that understand Fortran conventions
933: of nesting, line numbers and continuation statements.
934:
935: Special commands for comments are provided because Fortran comments are
936: unlike those of other languages.
937:
938: Built-in abbrevs optionally save typing when you insert Fortran keywords.
939:
940: Use `M-x fortran-mode' to switch to this major mode. Doing so calls
941: the value of `fortran-mode-hook' as a function of no arguments if
942: that variable has a value that is not `nil'.
943:
944: * Menu:
945:
946: * Motion: Fortran Motion. Moving point by statements or subprograms.
947: * Indent: Fortran Indent. Indentation commands for Fortran.
948: * Comments: Fortran Comments. Inserting and aligning comments.
949: * Columns: Fortran Columns. Measuring columns for valid Fortran.
950: * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
951:
952: Fortran mode was contributed by Michael Prange.
953:
954:
955: File: emacs Node: Fortran Motion, Prev: Fortran, Up: Fortran, Next: Fortran Indent
956:
957: Motion Commands
958: ---------------
959:
960: Fortran mode provides special commands to move by subprograms (functions
961: and subroutines) and by statements. There is also a command to put the
962: region around one subprogram, convenient for killing it or moving it.
963:
964:
965: `C-M-a'
966: Move to beginning of subprogram
967: (`beginning-of-fortran-subprogram').
968: `C-M-e'
969: Move to end of subprogram (`end-of-fortran-subprogram').
970: `C-M-h'
971: Put point at beginning of subprogram and mark at end
972: (`mark-fortran-subprogram').
973: `C-c C-n'
974: Move to beginning of current or next statement
975: (`fortran-next-statement').
976: `C-c C-p'
977: Move to beginning of current or previous statement
978: (`fortran-previous-statement').
979:
980:
981: File: emacs Node: Fortran Indent, Prev: Fortran Motion, Up: Fortran, Next: Fortran Comments
982:
983: Fortran Indentation
984: -------------------
985:
986: Special commands and features are needed for indenting Fortran code in
987: order to make sure various syntactic entities (line numbers, comment line
988: indicators and continuation line flags) appear in the columns that are
989: required for standard Fortran.
990:
991: * Menu:
992:
993: * Commands: ForIndent Commands. Commands for indenting Fortran.
994: * Numbers: ForIndent Num. How line numbers auto-indent.
995: * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
996: * Vars: ForIndent Vars. Variables controlling Fortran indent style.
997:
998:
999: File: emacs Node: ForIndent Commands, Prev: Fortran Indent, Up: Fortran Indent, Next: ForIndent Num
1000:
1001: Fortran Indentation Commands
1002: ............................
1003:
1004: `TAB'
1005: Indent the current line (`fortran-indent-line').
1006: `M-LFD'
1007: Break the current line and set up a continuation line.
1008: `C-M-q'
1009: Indent all the lines of the subprogram point is in
1010: (`fortran-indent-subprogram').
1011:
1012: TAB is redefined by Fortran mode to reindent the current line for
1013: Fortran (`fortran-indent-line'). Line numbers and continuation
1014: markers are indented to their required columns, and the body of the
1015: statement is independently indented based on its nesting in the program.
1016:
1017: The key `C-M-q' is redefined as `fortran-indent-subprogram', a
1018: command to reindent all the lines of the Fortran subprogram (function or
1019: subroutine) containing point.
1020:
1021: The key `M-LFD' is redefined as `fortran-split-line', a
1022: command to split a line in the appropriate fashion for Fortran. In a
1023: non-comment line, the second half becomes a continuation line and is
1024: indented accordingly. In a comment line, both halves become separate
1025: comment lines.
1026:
1027:
1028: File: emacs Node: ForIndent Num, Prev: ForIndent Commands, Up: Fortran Indent, Next: ForIndent Conv
1029:
1030: Line Numbers and Continuation
1031: .............................
1032:
1033: If a number is the first non-whitespace in the line, it is assumed to be
1034: a line number and is moved to columns 0 through 4. (Columns are always
1035: counted from 0 in GNU Emacs.) If the text on the line starts with the
1036: conventional Fortran continuation marker `$', it is moved to column 5.
1037: If the text begins with any non whitespace character in column 5, it is
1038: assumed to be an unconventional continuation marker and remains in column
1039: 5.
1040:
1041: Line numbers of four digits or less are normally indented one space.
1042: This amount is controlled by the variable `fortran-line-number-indent'
1043: which is the maximum indentation a line number can have. Line numbers
1044: are indented to right-justify them to end in column 4 unless that would
1045: require more than this maximum indentation. The default value of the
1046: variable is 1.
1047:
1048: Simply inserting a line number is enough to indent it according to these
1049: rules. As each digit is inserted, the indentation is recomputed. To turn
1050: off this feature, set the variable `fortran-electric-line-number' to
1051: `nil'. Then inserting line numbers is like inserting anything else.
1052:
1053:
1054: File: emacs Node: ForIndent Conv, Prev: ForIndent Num, Up: Fortran Indent, Next: ForIndent Vars
1055:
1056: Syntactic Conventions
1057: .....................
1058:
1059: Fortran mode assumes that you follow certain conventions that simplify
1060: the task of understanding a Fortran program well enough to indent it
1061: properly:
1062:
1063: * Two nested `do' loops never share a `continue' statement.
1064:
1065: * The same character appears in column 5 of all continuation lines, and
1066: this character is the value of the variable `fortran-continuation-char'.
1067: By default, this character is `$'.
1068:
1069: If you fail to follow these conventions, the indentation commands may
1070: indent some lines unaesthetically. However, a correct Fortran program will
1071: retain its meaning when reindented even if the conventions are not
1072: followed.
1073:
1074:
1075: File: emacs Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
1076:
1077: Variables for Fortran Indentation
1078: .................................
1079:
1080: Several additional variables control how Fortran indentation works.
1081:
1082: `fortran-do-indent'
1083: Extra indentation within each level of `do' statement (default 3).
1084:
1085: `fortran-if-indent'
1086: Extra indentation within each level of `if' statement (default 3).
1087:
1088: `fortran-continuation-indent'
1089: Extra indentation for bodies of continuation lines (default 5).
1090:
1091: `fortran-check-all-num-for-matching-do'
1092: If this is `nil', indentation assumes that each `do'
1093: statement ends on a `continue' statement. Therefore, when
1094: computing indentation for a statement other than `continue', it
1095: can save time by not checking for a `do' statement ending there.
1096: If this is non-`nil', indenting any numbered statement must check
1097: for a `do' that ends there. The default is `nil'.
1098:
1099: `fortran-minimum-statement-indent'
1100: Minimum indentation for fortran statements. For standard Fortran,
1101: this is 6. Statement bodies will never be indented less than this
1102: much.
1103:
1104:
1105: File: emacs Node: Fortran Comments, Prev: Fortran Indent, Up: Fortran, Next: Fortran Columns
1106:
1107: Comments
1108: --------
1109:
1110: The usual Emacs comment commands assume that a comment can follow a line
1111: of code. In Fortran, the standard comment syntax requires an entire line
1112: to be just a comment. Therefore, Fortran mode replaces the standard Emacs
1113: comment commands and defines some new variables.
1114:
1115: Fortran mode can also handle a nonstandard comment syntax where comments
1116: start with `!' and can follow other text. Because only some Fortran
1117: compilers accept this syntax, Fortran mode will not insert such comments
1118: unless you have said in advance to do so. To do this, set the variable
1119: `comment-start' to `"!"' (*Note Variables::).
1120:
1121: `M-;'
1122: Align comment or insert new comment (`fortran-comment-indent').
1123:
1124: `C-x ;'
1125: Applies to nonstandard `!' comments only.
1126:
1127: `C-c ;'
1128: Turn all lines of the region into comments, or (with arg)
1129: turn them back into real code (`fortran-comment-region').
1130:
1131: `M-;' in Fortran mode is redefined as the command
1132: `fortran-comment-indent'. Like the usual `M-;' command, this
1133: recognizes any kind of existing comment and aligns its text appropriately;
1134: if there is no existing comment, a comment is inserted and aligned. But
1135: inserting and aligning comments are not the same in Fortran mode as in
1136: other modes.
1137:
1138: When a new comment must be inserted, if the current line is blank, a
1139: full-line comment is inserted. On a non-blank line, a nonstandard `!'
1140: comment is inserted if you have said you want to use them. Otherwise a
1141: full-line comment is inserted on a new line before the current line.
1142:
1143: Nonstandard `!' comments are aligned like comments in other
1144: languages, but full-line comments are different. In a standard full-line
1145: comment, the comment delimiter itself must always appear in column zero.
1146: What can be aligned is the text within the comment. You can choose from
1147: three styles of alignment by setting the variable
1148: `fortran-comment-indent-style' to one of these values:
1149:
1150: `fixed'
1151: The text is aligned at a fixed column, which is the value of
1152: `fortran-comment-line-column'. This is the default.
1153: `relative'
1154: The text is aligned as if it were a line of code, but with an
1155: additional `fortran-comment-line-column' columns of indentation.
1156: `nil'
1157: Text in full-line columns is not moved automatically.
1158:
1159: In addition, you can specify the character to be used to indent within
1160: full-line comments by setting the variable `fortran-comment-indent-char'
1161: to the character you want to use.
1162:
1163: Fortran mode introduces two variables `comment-line-start' and
1164: `comment-line-start-skip' which play for full-line comments the same
1165: roles played by `comment-start' and `comment-start-skip' for
1166: ordinary text-following comments. Normally these are set properly by
1167: Fortran mode so you do not need to change them.
1168:
1169: The normal Emacs comment command `C-x ;' has not been redefined.
1170: If you use `!' comments, this command can be used with them. Otherwise
1171: it is useless in Fortran mode.
1172:
1173: The command `C-c ;' (`fortran-comment-region') turns all the
1174: lines of the region into comments by inserting the string `C$$$' at
1175: the front of each one. With a numeric arg, the region is turned back into
1176: live code by deleting `C$$$' from the front of each line in it. The
1177: string used for these comments can be controlled by setting the variable
1178: `fortran-comment-region'. Note that here we have an example of a
1179: command and a variable with the same name; these two uses of the name never
1180: conflict because in Lisp and in Emacs it is always clear from the context
1181: which one is meant.
1182:
1183:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.