diff options
Diffstat (limited to 'info/emacs-8')
| -rw-r--r-- | info/emacs-8 | 1191 |
1 files changed, 1191 insertions, 0 deletions
diff --git a/info/emacs-8 b/info/emacs-8 new file mode 100644 index 00000000000..bc18a3ae024 --- /dev/null +++ b/info/emacs-8 @@ -0,0 +1,1191 @@ +This is Info file ../info/emacs, produced by Makeinfo-1.49 from the +input file emacs.texi. + + This file documents the GNU Emacs editor. + + Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the sections entitled "The GNU Manifesto", "Distribution" and "GNU +General Public License" are included exactly as in the original, and +provided that the entire resulting derived work is distributed under the +terms of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the sections entitled "The GNU Manifesto", +"Distribution" and "GNU General Public License" may be included in a +translation approved by the author instead of in the original English. + + +File: emacs, Node: Comments, Next: Macro Expansion, Prev: Matching, Up: Programs + +Manipulating Comments +===================== + + The comment commands insert, kill and align comments. + +`M-;' + Insert or align comment (`indent-for-comment'). + +`C-x ;' + Set comment column (`set-comment-column'). + +`C-u - C-x ;' + Kill comment on current line (`kill-comment'). + +`M-LFD' + Like RET followed by inserting and aligning a comment + (`indent-new-comment-line'). + + The command that creates a comment is `Meta-;' +(`indent-for-comment'). If there is no comment already on the line, a +new comment is created, aligned at a specific column called the +"comment column". The comment is created by inserting the string Emacs +thinks comments should start with (the value of `comment-start'; see +below). Point is left after that string. If the text of the line +extends past the comment column, then the indentation is done to a +suitable boundary (usually, at least one space is inserted). If the +major mode has specified a string to terminate comments, that is +inserted after point, to keep the syntax valid. + + `Meta-;' can also be used to align an existing comment. If a line +already contains the string that starts comments, then `M-;' just moves +point after it and re-indents it to the conventional place. Exception: +comments starting in column 0 are not moved. + + Some major modes have special rules for indenting certain kinds of +comments in certain contexts. For example, in Lisp code, comments which +start with two semicolons are indented as if they were lines of code, +instead of at the comment column. Comments which start with three +semicolons are supposed to start at the left margin. Emacs understands +these conventions by indenting a double-semicolon comment using TAB, +and by not changing the indentation of a triple-semicolon comment at +all. + + ;; This function is just an example + ;;; Here either two or three semicolons are appropriate. + (defun foo (x) + ;;; And now, the first part of the function: + ;; The following line adds one. + (1+ x)) ; This line adds one. + + In C code, a comment preceded on its line by nothing but whitespace +is indented like a line of code. + + Even when an existing comment is properly aligned, `M-;' is still +useful for moving directly to the start of the comment. + + `C-u - C-x ;' (`kill-comment') kills the comment on the current line, +if there is one. The indentation before the start of the comment is +killed as well. If there does not appear to be a comment in the line, +nothing is done. To reinsert the comment on another line, move to the +end of that line, do `C-y', and then do `M-;' to realign it. Note that +`C-u - C-x ;' is not a distinct key; it is `C-x ;' +(`set-comment-column') with a negative argument. That command is +programmed so that when it receives a negative argument it calls +`kill-comment'. However, `kill-comment' is a valid command which you +could bind directly to a key if you wanted to. + +Multiple Lines of Comments +-------------------------- + + If you are typing a comment and find that you wish to continue it on +another line, you can use the command `Meta-LFD' +(`indent-new-comment-line'), which terminates the comment you are +typing, creates a new blank line afterward, and begins a new comment +indented under the old one. When Auto Fill mode is on, going past the +fill column while typing a comment causes the comment to be continued +in just this fashion. If point is not at the end of the line when +`M-LFD' is typed, the text on the rest of the line becomes part of the +new comment line. + +Options Controlling Comments +---------------------------- + + The comment column is stored in the variable `comment-column'. You +can set it to a number explicitly. Alternatively, the command `C-x ;' +(`set-comment-column') sets the comment column to the column point is +at. `C-u C-x ;' sets the comment column to match the last comment +before point in the buffer, and then does a `Meta-;' to align the +current line's comment under the previous one. Note that `C-u - C-x ;' +runs the function `kill-comment' as described above. + + `comment-column' is a per-buffer variable; altering the variable +affects only the current buffer, but there is a default value which you +can change as well. *Note Locals::. Many major modes initialize this +variable for the current buffer. + + The comment commands recognize comments based on the regular +expression that is the value of the variable `comment-start-skip'. +This regexp should not match the null string. It may match more than +the comment starting delimiter in the strictest sense of the word; for +example, in C mode the value of the variable is `"/\\*+ *"', which +matches extra stars and spaces after the `/*' itself. (Note that `\\' +is needed in Lisp syntax to include a `\' in the string, which is needed +to deny the first star its special meaning in regexp syntax. *Note +Regexps::.) + + When a comment command makes a new comment, it inserts the value of +`comment-start' to begin it. The value of `comment-end' is inserted +after point, so that it will follow the text that you will insert into +the comment. In C mode, `comment-start' has the value `"/* "' and +`comment-end' has the value `" */"'. + + `comment-multi-line' controls how `M-LFD' (`indent-new-comment-line') +behaves when used inside a comment. If `comment-multi-line' is `nil', +as it normally is, then the comment on the starting line is terminated +and a new comment is started on the new following line. If +`comment-multi-line' is not `nil', then the new following line is set +up as part of the same comment that was found on the starting line. +This is done by not inserting a terminator on the old line, and not +inserting a starter on the new line. In languages where multi-line +comments work, the choice of value for this variable is a matter of +taste. + + The variable `comment-indent-hook' should contain a function that +will be called to compute the indentation for a newly inserted comment +or for aligning an existing comment. It is set differently by various +major modes. The function is called with no arguments, but with point +at the beginning of the comment, or at the end of a line if a new +comment is to be inserted. It should return the column in which the +comment ought to start. For example, in Lisp mode, the indent hook +function bases its decision on how many semicolons begin an existing +comment, and on the code in the preceding lines. + + +File: emacs, Node: Macro Expansion, Next: Balanced Editing, Prev: Comments, Up: Programs + +Viewing How C Macros Expand +=========================== + + When you are debugging C code that uses macros, sometimes it is hard +to figure out precisely how the macros expand. The command `M-x +c-macro-expand'. It runs the C preprocessor and shows you what +expansion results from the region. The portion of the buffer before the +region is also included in preprocessing, for the sake of macros defined +there, but the output from this part isn't shown. + + +File: emacs, Node: Balanced Editing, Next: Lisp Completion, Prev: Macro Expansion, Up: Programs + +Editing Without Unbalanced Parentheses +====================================== + +`M-(' + Put parentheses around next sexp(s) (`insert-parentheses'). + +`M-)' + Move past next close parenthesis and re-indent + (`move-over-close-and-reindent'). + + The two commands, `M-(' (`insert-parentheses') and `M-)' +(`move-over-close-and-reindent'), are designed to facilitate a style of +editing which keeps parentheses balanced at all times. `M-(' inserts a +pair of parentheses, either together as in `()', or, if given an +argument, around the next several sexps, and leaves point after the open +parenthesis. Instead of typing `( F O O )', you can type `M-( F O O', +which has the same effect except for leaving the cursor before the +close parenthesis. Then you would type `M-)', which moves past the +close parenthesis, deleting any indentation preceding it (in this +example there is none), and indenting with LFD after it. + + +File: emacs, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs + +Completion for Lisp Symbols +=========================== + + Usually completion happens in the minibuffer. But one kind of +completion is available in all buffers: completion for Lisp symbol +names. + + The command `M-TAB' (`lisp-complete-symbol') takes the partial Lisp +symbol before point to be an abbreviation, and compares it against all +nontrivial Lisp symbols currently known to Emacs. Any additional +characters that they all have in common are inserted at point. +Nontrivial symbols are those that have function definitions, values or +properties. + + If there is an open-parenthesis immediately before the beginning of +the partial symbol, only symbols with function definitions are +considered as completions. + + If the partial name in the buffer has more than one possible +completion and they have no additional characters in common, a list of +all possible completions is displayed in another window. + + +File: emacs, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs + +Documentation Commands +====================== + + As you edit Lisp code to be run in Emacs, the commands `C-h f' +(`describe-function') and `C-h v' (`describe-variable') can be used to +print documentation of functions and variables that you want to call. +These commands use the minibuffer to read the name of a function or +variable to document, and display the documentation in a window. + + For extra convenience, these commands provide default arguments +based on the code in the neighborhood of point. `C-h f' sets the +default to the function called in the innermost list containing point. +`C-h v' uses the symbol name around or adjacent to point as its default. + + Documentation on Unix commands, system calls and libraries can be +obtained with the `M-x manual-entry' command. This reads a topic as an +argument, and displays the text on that topic from the Unix manual. +`manual-entry' always searches all 8 sections of the manual, and +concatenates all the entries that are found. For example, the topic +`termcap' finds the description of the termcap library from section 3, +followed by the description of the termcap data base from section 5. + + +File: emacs, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs + +Change Logs +=========== + + The Emacs command `M-x add-change-log-entry' helps you keep a record +of when and why you have changed a program. It assumes that you have a +file in which you write a chronological sequence of entries describing +individual changes. The default is to store the change entries in a +file called `ChangeLog' in the same directory as the file you are +editing. The same `ChangeLog' file therefore records changes for all +the files in the directory. + + A change log entry starts with a header line that contains your name +and the current date. Aside from these header lines, every line in the +change log starts with a tab. One entry can describe several changes; +each change starts with a line starting with a tab and a star. `M-x +add-change-log-entry' visits the change log file and creates a new +entry unless the most recent entry is for today's date and your name. +In either case, it adds a new line to start the description of another +change just after the header line of the entry. When `M-x +add-change-log-entry' is finished, all is prepared for you to edit in +the description of what you changed and how. You must then save the +change log file yourself. + + The change log file is always visited in Indented Text mode, which +means that LFD and auto-filling indent each new line like the previous +line. This is convenient for entering the contents of an entry, which +must all be indented. *Note Text Mode::. + + An alternative convenient command for starting a change log entry is +`C-x 4 a' (`add-change-log-entry-other-window'). It resembles +`add-change-log-entry' except that it visits the change log in another +window, and always uses the file `./ChangeLog'--it does not ask you for +the file name. + + Here is an example of the formatting conventions used in the change +log for Emacs: + + Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep) + + * xdisp.c (try_window_id): + If C-k is done at end of next-to-last line, + this fn updates window_end_vpos and cannot leave + window_end_pos nonnegative (it is zero, in fact). + If display is preempted before lines are output, + this is inconsistent. Fix by setting + blank_end_of_window to nonzero. + + Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep) + + * cmds.c (Fnewline): + Call the auto fill hook if appropriate. + + * xdisp.c (try_window_id): + If point is found by compute_motion after xp, record that + permanently. If display_text_line sets point position wrong + (case where line is killed, point is at eob and that line is + not displayed), set it again in final compute_motion. + + +File: emacs, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs + +Tag Tables +========== + + A "tag table" is a description of how a multi-file program is broken +up into files. It lists the names of the component files and the names +and positions of the functions in each file. Grouping the related +files makes it possible to search or replace through all the files with +one command. Recording the function names and positions makes possible +the `Meta-.' command which you can use to find the definition of a +function without having to know which of the files it is in. + + Tag tables are stored in files called "tag table files". The +conventional name for a tag table file is `TAGS'. + + Each entry in the tag table records the name of one tag, the name of +the file that the tag is defined in (implicitly), and the position in +that file of the tag's definition. + + Just what names from the described files are recorded in the tag +table depends on the programming language of the described file. They +normally include all functions and subroutines, and may also include +global variables, data types, and anything else convenient. In any +case, each name recorded is called a "tag". + +* Menu: + +* Tag Syntax:: +* Create Tag Table:: +* Select Tag Table:: +* Find Tag:: +* Tags Search:: +* Tags Stepping:: +* List Tags:: + + +File: emacs, Node: Tag Syntax, Next: Create Tag Table, Prev: Tags, Up: Tags + +Source File Tag Syntax +---------------------- + + In Lisp code, any function defined with `defun', any variable +defined with `defvar' or `defconst', and in general the first argument +of any expression that starts with `(def' in column zero, is a tag. + + In C code, any C function is a tag, and so is any typedef if `-t' is +specified when the tag table is constructed. + + In Fortran code, functions and subroutines are tags. + + In LaTeX text, the argument of any of the commands `\chapter', +`\section', `\subsection', `\subsubsection', `\eqno', `\label', `\ref', +`\cite', `\bibitem' and `\typeout' is a tag. + + +File: emacs, Node: Create Tag Table, Next: Select Tag Table, Prev: Tag Syntax, Up: Tags + +Creating Tag Tables +------------------- + + The `etags' program is used to create a tag table file. It knows +the syntax of C, Fortran, LaTeX, Scheme and Emacs Lisp/Common Lisp. To +use `etags', type + + etags INPUTFILES... + +as a shell command. It reads the specified files and writes a tag table +named `TAGS' in the current working directory. `etags' recognizes the +language used in an input file based on its file name and contents; +there are no switches for specifying the language. The `-t' switch +tells `etags' to record typedefs in C code as tags. + + If the tag table data become outdated due to changes in the files +described in the table, the way to update the tag table is the same way +it was made in the first place. It is not necessary to do this often. + + If the tag table fails to record a tag, or records it for the wrong +file, then Emacs cannot possibly find its definition. However, if the +position recorded in the tag table becomes a little bit wrong (due to +some editing in the file that the tag definition is in), the only +consequence is to slow down finding the tag slightly. Even if the +stored position is very wrong, Emacs will still find the tag, but it +must search the entire file for it. + + So you should update a tag table when you define new tags that you +want to have listed, or when you move tag definitions from one file to +another, or when changes become substantial. Normally there is no need +to update the tag table after each edit, or even every day. + + +File: emacs, Node: Select Tag Table, Next: Find Tag, Prev: Create Tag Table, Up: Tags + +Selecting a Tag Table +--------------------- + + Emacs has at any time one "selected" tag table, and all the commands +for working with tag tables use the selected one. To select a tag +table, type `M-x visit-tags-table', which reads the tag table file name +as an argument. The name `TAGS' in the default directory is used as the +default file name. + + All this command does is store the file name in the variable +`tags-file-name'. Emacs does not actually read in the tag table +contents until you try to use them. Setting this variable yourself is +just as good as using `visit-tags-table'. The variable's initial value +is `nil'; this value tells all the commands for working with tag tables +that they must ask for a tag table file name to use. + + +File: emacs, Node: Find Tag, Next: Tags Search, Prev: Select Tag Table, Up: Tags + +Finding a Tag +------------- + + The most important thing that a tag table enables you to do is to +find the definition of a specific tag. + +`M-. TAG' + Find first definition of TAG (`find-tag'). + +`C-u M-.' + Find next alternate definition of last tag specified. + +`C-x 4 . TAG' + Find first definition of TAG, but display it in another window + (`find-tag-other-window'). + + `M-.' (`find-tag') is the command to find the definition of a +specified tag. It searches through the tag table for that tag, as a +string, and then uses the tag table info to determine the file that the +definition is in and the approximate character position in the file of +the definition. Then `find-tag' visits that file, moves point to the +approximate character position, and starts searching ever-increasing +distances away for the the text that should appear at the beginning of +the definition. + + If an empty argument is given (just type RET), the sexp in the +buffer before or around point is used as the name of the tag to find. +*Note Lists::, for info on sexps. + + The argument to `find-tag' need not be the whole tag name; it can be +a substring of a tag name. However, there can be many tag names +containing the substring you specify. Since `find-tag' works by +searching the text of the tag table, it finds the first tag in the +table that the specified substring appears in. + + The way to find other tags that match the substring is to give +`find-tag' a numeric argument, as in `C-u M-.'; this does not read a +tag name, but continues searching the tag table's text for another tag +containing the same substring last used. If you have a real META key, +`M-0 M-.' is an easier alternative to `C-u M-.'. (That is a zero in +`M-0'.) + + Like most commands that can switch buffers, `find-tag' has another +similar command that displays the new buffer in another window. `C-x 4 +.' invokes the function `find-tag-other-window'. (This key sequence +ends with a period.) + + Emacs comes with a tag table file `TAGS', in the `src' subdirectory, +which includes all the Lisp libraries and all the C sources of Emacs. +By specifying this file with `visit-tags-table' and then using `M-.' +you can quickly look at the source of any Emacs function. + + +File: emacs, Node: Tags Search, Next: Tags Stepping, Prev: Find Tag, Up: Tags + +Searching and Replacing with Tag Tables +--------------------------------------- + + The commands in this section visit and search all the files listed +in the selected tag table, one by one. For these commands, the tag +table serves only to specify a sequence of files to search. A related +command is `M-x grep' (*note Compilation::.). + +`M-x tags-search' + Search for the specified regexp through the files in the selected + tag table. + +`M-x tags-query-replace' + Perform a `query-replace' on each file in the selected tag table. + +`M-,' + Restart one of the commands above, from the current location of + point (`tags-loop-continue'). + + `M-x tags-search' reads a regexp using the minibuffer, then visits +the files of the selected tag table one by one, and searches through +each one for that regexp. It displays the name of the file being +searched so you can follow its progress. As soon as an occurrence is +found, `tags-search' returns. + + Having found one match, you probably want to find all the rest. To +find one more match, type `M-,' (`tags-loop-continue') to resume the +`tags-search'. This searches the rest of the current buffer, followed +by the remaining files of the tag table. + + `M-x tags-query-replace' performs a single `query-replace' through +all the files in the tag table. It reads a string to search for and a +string to replace with, just like ordinary `M-x query-replace'. It +searches much like `M-x tags-search' but repeatedly, processing matches +according to your input. *Note Replace::, for more information on +`query-replace'. + + It is possible to get through all the files in the tag table with a +single invocation of `M-x tags-query-replace'. But since any +unrecognized character causes the command to exit, you may need to +continue where you left off. `M-,' can be used for this. It resumes +the last tags search or replace command that you did. + + It may have struck you that `tags-search' is a lot like `grep'. You +can also run `grep' itself as an inferior of Emacs and have Emacs show +you the matching lines one by one. This works mostly the same as +running a compilation and having Emacs show you where the errors were. +*Note Compilation::. + + +File: emacs, Node: Tags Stepping, Next: List Tags, Prev: Tags Search, Up: Tags + +Stepping Through a Tag Table +---------------------------- + + If you wish to process all the files in the selected tag table, but +`M-x tags-search' and `M-x tags-query-replace' in particular are not +what you want, you can use `M-x next-file'. + +`C-u M-x next-file' + With a numeric argument, regardless of its value, visit the first + file in the tag table, and prepare to advance sequentially by + files. + +`M-x next-file' + Visit the next file in the selected tag table. + + +File: emacs, Node: List Tags, Prev: Tags Stepping, Up: Tags + +Tag Table Inquiries +------------------- + +`M-x list-tags' + Display a list of the tags defined in a specific program file. + +`M-x tags-apropos' + Display a list of all tags matching a specified regexp. + + `M-x list-tags' reads the name of one of the files described by the +selected tag table, and displays a list of all the tags defined in that +file. The "file name" argument is really just a string to compare +against the names recorded in the tag table; it is read as a string +rather than as a file name. Therefore, completion and defaulting are +not available, and you must enter the string the same way it appears in +the tag table. Do not include a directory as part of the file name +unless the file name recorded in the tag table includes a directory. + + `M-x tags-apropos' is like `apropos' for tags. It reads a regexp, +then finds all the tags in the selected tag table whose entries match +that regexp, and displays the tag names found. + + +File: emacs, Node: Fortran, Prev: Tags, Up: Programs + +Fortran Mode +============ + + Fortran mode provides special motion commands for Fortran statements +and subprograms, and indentation commands that understand Fortran +conventions of nesting, line numbers and continuation statements. + + Special commands for comments are provided because Fortran comments +are unlike those of other languages. + + Built-in abbrevs optionally save typing when you insert Fortran +keywords. + + Use `M-x fortran-mode' to switch to this major mode. Doing so calls +the value of `fortran-mode-hook' as a function of no arguments if that +variable has a value that is not `nil'. + +* Menu: + +* Motion: Fortran Motion. Moving point by statements or subprograms. +* Indent: Fortran Indent. Indentation commands for Fortran. +* Comments: Fortran Comments. Inserting and aligning comments. +* Columns: Fortran Columns. Measuring columns for valid Fortran. +* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. + + Fortran mode was contributed by Michael Prange. + + +File: emacs, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran + +Motion Commands +--------------- + + Fortran mode provides special commands to move by subprograms +(functions and subroutines) and by statements. There is also a command +to put the region around one subprogram, convenient for killing it or +moving it. + +`C-M-a' + Move to beginning of subprogram + (`beginning-of-fortran-subprogram'). + +`C-M-e' + Move to end of subprogram (`end-of-fortran-subprogram'). + +`C-M-h' + Put point at beginning of subprogram and mark at end + (`mark-fortran-subprogram'). + +`C-c C-n' + Move to beginning of current or next statement + (`fortran-next-statement'). + +`C-c C-p' + Move to beginning of current or previous statement + (`fortran-previous-statement'). + + +File: emacs, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran + +Fortran Indentation +------------------- + + Special commands and features are needed for indenting Fortran code +in order to make sure various syntactic entities (line numbers, comment +line indicators and continuation line flags) appear in the columns that +are required for standard Fortran. + +* Menu: + +* Commands: ForIndent Commands. Commands for indenting Fortran. +* Numbers: ForIndent Num. How line numbers auto-indent. +* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. +* Vars: ForIndent Vars. Variables controlling Fortran indent style. + + +File: emacs, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent + +Fortran Indentation Commands +............................ + +`TAB' + Indent the current line (`fortran-indent-line'). + +`M-LFD' + Break the current line and set up a continuation line. + +`C-M-q' + Indent all the lines of the subprogram point is in + (`fortran-indent-subprogram'). + + TAB is redefined by Fortran mode to reindent the current line for +Fortran (`fortran-indent-line'). Line numbers and continuation markers +are indented to their required columns, and the body of the statement +is independently indented based on its nesting in the program. + + The key `C-M-q' is redefined as `fortran-indent-subprogram', a +command to reindent all the lines of the Fortran subprogram (function or +subroutine) containing point. + + The key `M-LFD' is redefined as `fortran-split-line', a command to +split a line in the appropriate fashion for Fortran. In a non-comment +line, the second half becomes a continuation line and is indented +accordingly. In a comment line, both halves become separate comment +lines. + + +File: emacs, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent + +Line Numbers and Continuation +............................. + + If a number is the first non-whitespace in the line, it is assumed +to be a line number and is moved to columns 0 through 4. (Columns are +always counted from 0 in GNU Emacs.) If the text on the line starts +with the conventional Fortran continuation marker `$', it is moved to +column 5. If the text begins with any non whitespace character in +column 5, it is assumed to be an unconventional continuation marker and +remains in column 5. + + Line numbers of four digits or less are normally indented one space. +This amount is controlled by the variable `fortran-line-number-indent' +which is the maximum indentation a line number can have. Line numbers +are indented to right-justify them to end in column 4 unless that would +require more than this maximum indentation. The default value of the +variable is 1. + + Simply inserting a line number is enough to indent it according to +these rules. As each digit is inserted, the indentation is recomputed. + To turn off this feature, set the variable +`fortran-electric-line-number' to `nil'. Then inserting line numbers +is like inserting anything else. + + +File: emacs, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent + +Syntactic Conventions +..................... + + Fortran mode assumes that you follow certain conventions that +simplify the task of understanding a Fortran program well enough to +indent it properly: + + * Two nested `do' loops never share a `continue' statement. + + * The same character appears in column 5 of all continuation lines, + and this character is the value of the variable + `fortran-continuation-char'. By default, this character is `$'. + +If you fail to follow these conventions, the indentation commands may +indent some lines unaesthetically. However, a correct Fortran program +will retain its meaning when reindented even if the conventions are not +followed. + + +File: emacs, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent + +Variables for Fortran Indentation +................................. + + Several additional variables control how Fortran indentation works. + +`fortran-do-indent' + Extra indentation within each level of `do' statement + (default 3). + +`fortran-if-indent' + Extra indentation within each level of `if' statement + (default 3). + +`fortran-continuation-indent' + Extra indentation for bodies of continuation lines (default 5). + +`fortran-check-all-num-for-matching-do' + If this is `nil', indentation assumes that each `do' statement + ends on a `continue' statement. Therefore, when computing + indentation for a statement other than `continue', it can save + time by not checking for a `do' statement ending there. If this is + non-`nil', indenting any numbered statement must check for a `do' + that ends there. The default is `nil'. + +`fortran-minimum-statement-indent' + Minimum indentation for fortran statements. For standard Fortran, + this is 6. Statement bodies will never be indented less than this + much. + + +File: emacs, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran + +Comments +-------- + + The usual Emacs comment commands assume that a comment can follow a +line of code. In Fortran, the standard comment syntax requires an +entire line to be just a comment. Therefore, Fortran mode replaces the +standard Emacs comment commands and defines some new variables. + + Fortran mode can also handle a nonstandard comment syntax where +comments start with `!' and can follow other text. Because only some +Fortran compilers accept this syntax, Fortran mode will not insert such +comments unless you have said in advance to do so. To do this, set the +variable `comment-start' to `"!"' (*note Variables::.). + +`M-;' + Align comment or insert new comment (`fortran-comment-indent'). + +`C-x ;' + Applies to nonstandard `!' comments only. + +`C-c ;' + Turn all lines of the region into comments, or (with arg) turn + them back into real code (`fortran-comment-region'). + + `M-;' in Fortran mode is redefined as the command +`fortran-comment-indent'. Like the usual `M-;' command, this +recognizes any kind of existing comment and aligns its text +appropriately; if there is no existing comment, a comment is inserted +and aligned. But inserting and aligning comments are not the same in +Fortran mode as in other modes. + + When a new comment must be inserted, if the current line is blank, a +full-line comment is inserted. On a non-blank line, a nonstandard `!' +comment is inserted if you have said you want to use them. Otherwise a +full-line comment is inserted on a new line before the current line. + + Nonstandard `!' comments are aligned like comments in other +languages, but full-line comments are different. In a standard +full-line comment, the comment delimiter itself must always appear in +column zero. What can be aligned is the text within the comment. You +can choose from three styles of alignment by setting the variable +`fortran-comment-indent-style' to one of these values: + +`fixed' + The text is aligned at a fixed column, which is the value of + `fortran-comment-line-column'. This is the default. + +`relative' + The text is aligned as if it were a line of code, but with an + additional `fortran-comment-line-column' columns of indentation. + +`nil' + Text in full-line columns is not moved automatically. + + In addition, you can specify the character to be used to indent +within full-line comments by setting the variable +`fortran-comment-indent-char' to the character you want to use. + + Fortran mode introduces the two variables, `comment-line-start' and +`comment-line-start-skip', which play for full-line comments the same +roles played by `comment-start' and `comment-start-skip' for ordinary +text-following comments. Normally these are set properly by Fortran +mode so you do not need to change them. + + The normal Emacs comment command `C-x ;' has not been redefined. If +you use `!' comments, this command can be used with them. Otherwise it +is useless in Fortran mode. + + The command `C-c ;' (`fortran-comment-region') turns all the lines +of the region into comments by inserting the string `C$$$' at the front +of each one. With a numeric arg, the region is turned back into live +code by deleting `C$$$' from the front of each line in it. The string +used for these comments can be controlled by setting the variable +`fortran-comment-region'. Note that here we have an example of a +command and a variable with the same name; these two uses of the name +never conflict because in Lisp and in Emacs it is always clear from the +context which one is meant. + + +File: emacs, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran + +Columns +------- + +`C-c C-r' + Displays a "column ruler" momentarily above the current line + (`fortran-column-ruler'). + +`C-c C-w' + Splits the current window horizontally so that it is 72 columns + wide. This may help you avoid going over that limit + (`fortran-window-create'). + + The command `C-c C-r' (`fortran-column-ruler') shows a column ruler +momentarily above the current line. The comment ruler is two lines of +text that show you the locations of columns with special significance +in Fortran programs. Square brackets show the limits of the columns for +line numbers, and curly brackets show the limits of the columns for the +statement body. Column numbers appear above them. + + Note that the column numbers count from zero, as always in GNU +Emacs. As a result, the numbers may not be those you are familiar +with; but the actual positions in the line are standard Fortran. + + The text used to display the column ruler is the value of the +variable `fortran-comment-ruler'. By changing this variable, you can +change the display. + + For even more help, use `C-c C-w' (`fortran-window-create'), a +command which splits the current window horizontally, making a window 72 +columns wide. By editing in this window you can immediately see when +you make a line too wide to be correct Fortran. + + +File: emacs, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran + +Fortran Keyword Abbrevs +----------------------- + + Fortran mode provides many built-in abbrevs for common keywords and +declarations. These are the same sort of abbrev that you can define +yourself. To use them, you must turn on Abbrev mode (*note Abbrevs::.). + + The built-in abbrevs are unusual in one way: they all start with a +semicolon. You cannot normally use semicolons in an abbrev, but Fortran +mode makes this possible by changing the syntax of semicolon to "word +constituent". + + For example, one built-in Fortran abbrev is `;c' for `continue'. If +you insert `;c' and then insert a punctuation character such as a space +or a newline, the `;c' will change automatically to `continue', +provided Abbrev mode is enabled. + + Type `;?' or `;C-h' to display a list of all the built-in Fortran +abbrevs and what they stand for. + + +File: emacs, Node: Compiling/Testing, Next: Abbrevs, Prev: Programs, Up: Top + +Compiling and Testing Programs +****************************** + + The previous chapter discusses the Emacs commands that are useful for +making changes in programs. This chapter deals with commands that +assist in the larger process of developing and maintaining programs. + +* Menu: + +* Compilation:: Compiling programs in languages other than Lisp + (C, Pascal, etc.) +* Modes: Lisp Modes. Various modes for editing Lisp programs, with + different facilities for running the Lisp programs. +* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. +* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. +* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. +* Debug: Lisp Debug. Debugging Lisp programs running in Emacs. +* External Lisp:: Communicating through Emacs with a separate Lisp. + + +File: emacs, Node: Compilation, Next: Lisp Modes, Prev: Compiling/Testing, Up: Compiling/Testing + +Running `make', or Compilers Generally +====================================== + + Emacs can run compilers for noninteractive languages such as C and +Fortran as inferior processes, feeding the error log into an Emacs +buffer. It can also parse the error messages and visit the files in +which errors are found, moving point right to the line where the error +occurred. + +`M-x compile' + Run a compiler asynchronously under Emacs, with error messages to + `*compilation*' buffer. + +`M-x grep' + Run `grep' asynchronously under Emacs, with matching lines listed + in the buffer named `*compilation*'. + +`M-x kill-compilation' +`M-x kill-grep' + Kill the running compilation or `grep' subprocess. + +`C-x `' + Visit the locus of the next compiler error message or `grep' match. + + To run `make' or another compiler, do `M-x compile'. This command +reads a shell command line using the minibuffer, and then executes the +specified command line in an inferior shell with output going to the +buffer named `*compilation*'. The current buffer's default directory +is used as the working directory for the execution of the command; +normally, therefore, the makefile comes from this directory. + + When the shell command line is read, the minibuffer appears +containing a default command line, which is the command you used the +last time you did `M-x compile'. If you type just RET, the same +command line is used again. The first `M-x compile' provides `make -k' +as the default. The default is taken from the variable +`compile-command'; if the appropriate compilation command for a file is +something other than `make -k', it can be useful to have the file +specify a local value for `compile-command' (*note File Variables::.). + + Starting a compilation causes the buffer `*compilation*' to be +displayed in another window but not selected. Its mode line tells you +whether compilation is finished, with the word `run' or `exit' inside +the parentheses. You do not have to keep this buffer visible; +compilation continues in any case. + + To kill the compilation process, do `M-x kill-compilation'. You will +see that the mode line of the `*compilation*' buffer changes to say +`signal' instead of `run'. Starting a new compilation also kills any +running compilation, as only one can exist at any time. However, this +requires confirmation before actually killing a compilation that is +running. + + To parse the compiler error messages, type `C-x `' (`next-error'). +The character following the `C-x' is the grave accent, not the single +quote. This command displays the buffer `*compilation*' in one window +and the buffer in which the next error occurred in another window. +Point in that buffer is moved to the line where the error was found. +The corresponding error message is scrolled to the top of the window in +which `*compilation*' is displayed. + + The first time `C-x `' is used after the start of a compilation, it +parses all the error messages, visits all the files that have error +messages, and makes markers pointing at the lines that the error +messages refer to. Then it moves to the first error message location. +Subsequent uses of `C-x `' advance down the data set up by the first +use. When the preparsed error messages are exhausted, the next `C-x `' +checks for any more error messages that have come in; this is useful if +you start editing the compiler errors while the compilation is still +going on. If no more error messages have come in, `C-x `' reports an +error. + + `C-u C-x `' discards the preparsed error message data and parses the +`*compilation*' buffer over again, then displaying the first error. +This way, you can process the same set of errors again. + + Instead of running a compiler, you can run `grep' and see the lines +on which matches were found. To do this, type `M-x grep' with an +argument line that contains the same arguments you would give `grep' +when running it normally: a `grep'-style regexp (usually in +singlequotes to quote the shell's special characters) followed by +filenames which may use wildcards. The output from `grep' goes in the +`*compilation*' buffer and the lines that matched can be found with +`C-x `' as if they were compilation errors. + + Note: a shell is used to run the compile command, but the shell is +told that it should be noninteractive. This means in particular that +the shell starts up with no prompt. If you find your usual shell +prompt making an unsightly appearance in the `*compilation*' buffer, it +means you have made a mistake in your shell's init file (`.cshrc' or +`.shrc' or ...) by setting the prompt unconditionally. The shell init +file should set the prompt only if there already is a prompt. + + Here is how to do it in `csh': + + if ($?prompt) set prompt = ... + + Here is how to do it in the Bourne-Again shell: + + if [ ! "$PS1" ]; then + PS1=... + fi + + +File: emacs, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Compiling/Testing + +Major Modes for Lisp +==================== + + Emacs has four different major modes for Lisp. They are the same in +terms of editing commands, but differ in the commands for executing Lisp +expressions. + +Emacs-Lisp mode + The mode for editing source files of programs to run in Emacs Lisp. + This mode defines `C-M-x' to evaluate the current defun. *Note + Lisp Libraries::. + +Lisp Interaction mode + The mode for an interactive session with Emacs Lisp. It defines + LFD to evaluate the sexp before point and insert its value in the + buffer. *Note Lisp Interaction::. + +Lisp mode + The mode for editing source files of programs that run in Lisps + other than Emacs Lisp. This mode defines `C-M-x' to send the + current defun to an inferior Lisp process. *Note External Lisp::. + +Inferior Lisp mode + The mode for an interactive session with an inferior Lisp process. + This mode combines the special features of Lisp mode and Shell mode + (*note Shell Mode::.). + +Scheme mode + Like Lisp mode but for Scheme programs. + +Inferior Scheme mode + The mode for an interactive session with an inferior Scheme + process. + + +File: emacs, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Compiling/Testing + +Libraries of Lisp Code for Emacs +================================ + + Lisp code for Emacs editing commands is stored in files whose names +conventionally end in `.el'. This ending tells Emacs to edit them in +Emacs-Lisp mode (*note Lisp Modes::.). + +* Menu: + +* Loading:: Loading libraries of Lisp code into Emacs for use. +* Compiling Libraries:: Compiling a library makes it load and run faster. +* Mocklisp:: Converting Mocklisp to Lisp so GNU Emacs can run it. + + +File: emacs, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries + +Loading Libraries +----------------- + + To execute a file of Emacs Lisp, use `M-x load-file'. This command +reads a file name using the minibuffer and then executes the contents of +that file as Lisp code. It is not necessary to visit the file first; +in any case, this command reads the file as found on disk, not text in +an Emacs buffer. + + Once a file of Lisp code is installed in the Emacs Lisp library +directories, users can load it using `M-x load-library'. Programs can +load it by calling `load-library', or with `load', a more primitive +function that is similar but accepts some additional arguments. + + `M-x load-library' differs from `M-x load-file' in that it searches +a sequence of directories and tries three file names in each directory. + The three names are, first, the specified name with `.elc' appended; +second, with `.el' appended; third, the specified name alone. A `.elc' +file would be the result of compiling the Lisp file into byte code; it +is loaded if possible in preference to the Lisp file itself because the +compiled file will load and run faster. + + Because the argument to `load-library' is usually not in itself a +valid file name, file name completion is not available. Indeed, when +using this command, you usually do not know exactly what file name will +be used. + + The sequence of directories searched by `M-x load-library' is +specified by the variable `load-path', a list of strings that are +directory names. The default value of the list contains the directory +where the Lisp code for Emacs itself is stored. If you have libraries +of your own, put them in a single directory and add that directory to +`load-path'. `nil' in this list stands for the current default +directory, but it is probably not a good idea to put `nil' in the list. + If you find yourself wishing that `nil' were in the list, most likely +what you really want to do is use `M-x load-file' this once. + + Often you do not have to give any command to load a library, because +the commands defined in the library are set up to "autoload" that +library. Running any of those commands causes `load' to be called to +load the library; this replaces the autoload definitions with the real +ones from the library. + + If autoloading a file does not finish, either because of an error or +because of a `C-g' quit, all function definitions made by the file are +undone automatically. So are any calls to `provide'. As a consequence, +if you use one of the autoloadable commands again, the entire file will +be loaded a second time. This prevents problems where the command is no +longer autoloading but it works wrong because not all the file was +loaded. Function definitions are undone only for autoloading; explicit +calls to `load' do not undo anything if loading is not completed. + + +File: emacs, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries + +Compiling Libraries +------------------- + + Emacs Lisp code can be compiled into byte-code which loads faster, +takes up less space when loaded, and executes faster. + + The way to make a byte-code compiled file from an Emacs-Lisp source +file is with `M-x byte-compile-file'. The default argument for this +function is the file visited in the current buffer. It reads the +specified file, compiles it into byte code, and writes an output file +whose name is made by appending `c' to the input file name. Thus, the +file `rmail.el' would be compiled into `rmail.elc'. + + To recompile the changed Lisp files in a directory, use `M-x +byte-recompile-directory'. Specify just the directory name as an +argument. Each `.el' file that has been byte-compiled before is +byte-compiled again if it has changed since the previous compilation. +A numeric argument to this command tells it to offer to compile each +`.el' file that has not already been compiled. You must answer `y' or +`n' to each offer. + + Emacs can be invoked noninteractively from the shell to do byte +compilation with the aid of the function `batch-byte-compile'. In this +case, the files to be compiled are specified with command-line +arguments. Use a shell command of the form + + emacs -batch -f batch-byte-compile FILES... + + Directory names may also be given as arguments; +`byte-recompile-directory' is invoked (in effect) on each such +directory. `batch-byte-compile' uses all the remaining command-line +arguments as file or directory names, then kills the Emacs process. + + `M-x disassemble' explains the result of byte compilation. Its +argument is a function name. It displays the byte-compiled code in a +help window in symbolic form, one instruction per line. If the +instruction refers to a variable or constant, that is shown too. + + +File: emacs, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries + +Converting Mocklisp to Lisp +--------------------------- + + GNU Emacs can run Mocklisp files by converting them to Emacs Lisp +first. To convert a Mocklisp file, visit it and then type `M-x +convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file +in a file whose name ends in `.el' and use the new file as a Lisp +library. + + It does not currently work to byte-compile converted Mocklisp code. +This is because converted Mocklisp code uses some special Lisp features +to deal with Mocklisp's incompatible ideas of how arguments are +evaluated and which values signify "true" or "false". + +
\ No newline at end of file |