GNUtools/emacs/info/emacs-8 - annotate

Return to emacs-8 CVS log

Up to [Apple XNU] / GNUtools / emacs / info

Annotation of GNUtools/emacs/info/emacs-8, revision 1.1.1.1

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

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.