-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from
xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Mode Line, Next: XEmacs under X, Prev: Echo Area, Up: Frame
+File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
-The Mode Line
+Replace Commands and Case
+-------------------------
+
+If the arguments to a replace command are in lower case, the command
+preserves case when it makes a replacement. Thus, the following
+command:
+
+ M-x replace-string <RET> foo <RET> bar <RET>
+
+replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
+and `Foo' with `Bar'. If upper-case letters are used in the second
+argument, they remain upper-case every time that argument is inserted.
+If upper-case letters are used in the first argument, the second
+argument is always substituted exactly as given, with no case
+conversion. Likewise, if the variable `case-replace' is set to `nil',
+replacement is done without case conversion. If `case-fold-search' is
+set to `nil', case is significant in matching occurrences of `foo' to
+replace; also, case conversion of the replacement string is not done.
+
+\1f
+File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
+
+Query Replace
+-------------
+
+`M-% STRING <RET> NEWSTRING <RET>'
+`M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
+ Replace some occurrences of STRING with NEWSTRING.
+
+`M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
+ Replace some matches for REGEXP with NEWSTRING.
+
+ If you want to change only some of the occurrences of `foo' to
+`bar', not all of them, you can use `query-replace' instead of `M-%'.
+This command finds occurrences of `foo' one by one, displays each
+occurrence, and asks you whether to replace it. A numeric argument to
+`query-replace' tells it to consider only occurrences that are bounded
+by word-delimiter characters.
+
+ Aside from querying, `query-replace' works just like
+`replace-string', and `query-replace-regexp' works just like
+`replace-regexp'.
+
+ The things you can type when you are shown an occurrence of STRING
+or a match for REGEXP are:
+
+`<SPC>'
+ to replace the occurrence with NEWSTRING. This preserves case,
+ just like `replace-string', provided `case-replace' is non-`nil',
+ as it normally is.
+
+`<DEL>'
+ to skip to the next occurrence without replacing this one.
+
+`, (Comma)'
+ to replace this occurrence and display the result. You are then
+ prompted for another input character. However, since the
+ replacement has already been made, <DEL> and <SPC> are equivalent.
+ At this point, you can type `C-r' (see below) to alter the
+ replaced text. To undo the replacement, you can type `C-x u'.
+ This exits the `query-replace'. If you want to do further
+ replacement you must use `C-x <ESC> <ESC>' to restart (*note
+ Repetition::).
+
+`<ESC>'
+ to exit without doing any more replacements.
+
+`. (Period)'
+ to replace this occurrence and then exit.
+
+`!'
+ to replace all remaining occurrences without asking again.
+
+`^'
+ to go back to the location of the previous occurrence (or what
+ used to be an occurrence), in case you changed it by mistake.
+ This works by popping the mark ring. Only one `^' in a row is
+ allowed, because only one previous replacement location is kept
+ during `query-replace'.
+
+`C-r'
+ to enter a recursive editing level, in case the occurrence needs
+ to be edited rather than just replaced with NEWSTRING. When you
+ are done, exit the recursive editing level with `C-M-c' and the
+ next occurrence will be displayed. *Note Recursive Edit::.
+
+`C-w'
+ to delete the occurrence, and then enter a recursive editing level
+ as in `C-r'. Use the recursive edit to insert text to replace the
+ deleted occurrence of STRING. When done, exit the recursive
+ editing level with `C-M-c' and the next occurrence will be
+ displayed.
+
+`C-l'
+ to redisplay the screen and then give another answer.
+
+`C-h'
+ to display a message summarizing these options, then give another
+ answer.
+
+ If you type any other character, Emacs exits the `query-replace', and
+executes the character as a command. To restart the `query-replace',
+use `C-x <ESC> <ESC>', which repeats the `query-replace' because it
+used the minibuffer to read its arguments. *Note C-x ESC ESC:
+Repetition.
+
+\1f
+File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
+
+Other Search-and-Loop Commands
+==============================
+
+Here are some other commands that find matches for a regular expression.
+They all operate from point to the end of the buffer.
+
+`M-x occur'
+ Print each line that follows point and contains a match for the
+ specified regexp. A numeric argument specifies the number of
+ context lines to print before and after each matching line; the
+ default is none.
+
+ The buffer `*Occur*' containing the output serves as a menu for
+ finding occurrences in their original context. Find an occurrence
+ as listed in `*Occur*', position point there, and type `C-c C-c';
+ this switches to the buffer that was searched and moves point to
+ the original of the same occurrence.
+
+`M-x list-matching-lines'
+ Synonym for `M-x occur'.
+
+`M-x count-matches'
+ Print the number of matches following point for the specified
+ regexp.
+
+`M-x delete-non-matching-lines'
+ Delete each line that follows point and does not contain a match
+ for the specified regexp.
+
+`M-x delete-matching-lines'
+ Delete each line that follows point and contains a match for the
+ specified regexp.
+
+\1f
+File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
+
+Commands for Fixing Typos
+*************************
+
+This chapter describes commands that are especially useful when you
+catch a mistake in your text just after you have made it, or when you
+change your mind while composing text on line.
+
+* Menu:
+
+* Kill Errors:: Commands to kill a batch of recently entered text.
+* Transpose:: Exchanging two characters, words, lines, lists...
+* Fixing Case:: Correcting case of last word entered.
+* Spelling:: Apply spelling checker to a word, or a whole file.
+
+\1f
+File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
+
+Killing Your Mistakes
+=====================
+
+`<DEL>'
+ Delete last character (`delete-backward-char').
+
+`M-<DEL>'
+ Kill last word (`backward-kill-word').
+
+`C-x <DEL>'
+ Kill to beginning of sentence (`backward-kill-sentence').
+
+ The <DEL> character (`delete-backward-char') is the most important
+correction command. When used among graphic (self-inserting)
+characters, it can be thought of as canceling the last character typed.
+
+ When your mistake is longer than a couple of characters, it might be
+more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
+to the start of the last word, and `C-x <DEL>' kills back to the start
+of the last sentence. `C-x <DEL>' is particularly useful when you are
+thinking of what to write as you type it, in case you change your mind
+about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
+`C-y' and `M-y' to retrieve. *Note Yanking::.
+
+ `M-<DEL>' is often useful even when you have typed only a few
+characters wrong, if you know you are confused in your typing and aren't
+sure exactly what you typed. At such a time, you cannot correct with
+<DEL> except by looking at the screen to see what you did. It requires
+less thought to kill the whole word and start over.
+
+\1f
+File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
+
+Transposing Text
+================
+
+`C-t'
+ Transpose two characters (`transpose-chars').
+
+`M-t'
+ Transpose two words (`transpose-words').
+
+`C-M-t'
+ Transpose two balanced expressions (`transpose-sexps').
+
+`C-x C-t'
+ Transpose two lines (`transpose-lines').
+
+ The common error of transposing two adjacent characters can be fixed
+with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
+the two characters on either side of point. When given at the end of a
+line, `C-t' transposes the last two characters on the line, rather than
+transposing the last character of the line with the newline, which
+would be useless. If you catch a transposition error right away, you
+can fix it with just `C-t'. If you catch the error later, move the
+cursor back to between the two transposed characters. If you
+transposed a space with the last character of the word before it, the
+word motion commands are a good way of getting there. Otherwise, a
+reverse search (`C-r') is often the best way. *Note Search::.
+
+ `Meta-t' (`transpose-words') transposes the word before point with
+the word after point. It moves point forward over a word, dragging the
+word preceding or containing point forward as well. The punctuation
+characters between the words do not move. For example, `FOO, BAR'
+transposes into `BAR, FOO' rather than `BAR FOO,'.
+
+ `C-M-t' (`transpose-sexps') is a similar command for transposing two
+expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
+exchanges lines. It works like `M-t' but in determines the division of
+the text into syntactic units differently.
+
+ A numeric argument to a transpose command serves as a repeat count:
+it tells the transpose command to move the character (word, sexp, line)
+before or containing point across several other characters (words,
+sexps, lines). For example, `C-u 3 C-t' moves the character before
+point forward across three other characters. This is equivalent to
+repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
+backward across four words. `C-u - C-M-t' would cancel the effect of
+plain `C-M-t'.
+
+ A numeric argument of zero transposes the character (word, sexp,
+line) ending after point with the one ending after the mark (otherwise a
+command with a repeat count of zero would do nothing).
+
+\1f
+File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
+
+Case Conversion
+===============
+
+`M-- M-l'
+ Convert last word to lower case. Note that `Meta--' is
+ "Meta-minus."
+
+`M-- M-u'
+ Convert last word to all upper case.
+
+`M-- M-c'
+ Convert last word to lower case with capital initial.
+
+ A common error is to type words in the wrong case. Because of this,
+the word case-conversion commands `M-l', `M-u', and `M-c' do not move
+the cursor when used with a negative argument. As soon as you see you
+have mistyped the last word, you can simply case-convert it and
+continue typing. *Note Case::.
+
+\1f
+File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
+
+Checking and Correcting Spelling
+================================
+
+`M-$'
+ Check and correct spelling of word (`spell-word').
+
+`M-x spell-buffer'
+ Check and correct spelling of each word in the buffer.
+
+`M-x spell-region'
+ Check and correct spelling of each word in the region.
+
+`M-x spell-string'
+ Check spelling of specified word.
+
+ To check the spelling of the word before point, and optionally
+correct it, use the command `M-$' (`spell-word'). This command runs an
+inferior process containing the `spell' program to see whether the word
+is correct English. If it is not, it asks you to edit the word (in the
+minibuffer) into a corrected spelling, and then performs a
+`query-replace' to substitute the corrected spelling for the old one
+throughout the buffer.
+
+ If you exit the minibuffer without altering the original spelling, it
+means you do not want to do anything to that word. In that case, the
+`query-replace' is not done.
+
+ `M-x spell-buffer' checks each word in the buffer the same way that
+`spell-word' does, doing a `query-replace' for every incorrect word if
+appropriate.
+
+ `M-x spell-region' is similar to `spell-buffer' but operates only on
+the region, not the entire buffer.
+
+ `M-x spell-string' reads a string as an argument and checks whether
+that is a correctly spelled English word. It prints a message giving
+the answer in the echo area.
+
+\1f
+File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
+
+File Handling
+*************
+
+The basic unit of stored data in Unix is the "file". To edit a file,
+you must tell Emacs to examine the file and prepare a buffer containing
+a copy of the file's text. This is called "visiting" the file. Editing
+commands apply directly to text in the buffer; that is, to the copy
+inside Emacs. Your changes appear in the file itself only when you
+"save" the buffer back into the file.
+
+ Emacs is also able to handle "remote files" which are stored on
+other hosts. Not only is Emacs somewhat aware of the special issues
+involved with network file systems, but it can also use FTP and ssh (or
+rsh) to make local copies of the files, and refresh them on the remote
+host automatically when you save the buffer. The FTP interface is
+provided by the standard `efs' package *Note EFS: (efs)Top. The
+ssh/rsh interface is provided by the optional `tramp' package *Note
+TRAMP: (tramp)Top. These packages attempt to implement all of the
+operations described below, making remote file use transparent (except
+for unavoidable network delays).
+
+ In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, and operate on file directories.
+
+* Menu:
+
+* File Names:: How to type and edit file name arguments.
+* Visiting:: Visiting a file prepares Emacs to edit the file.
+* Saving:: Saving makes your changes permanent.
+* Reverting:: Reverting cancels all the changes not saved.
+* Auto Save:: Auto Save periodically protects against loss of data.
+* Version Control:: Version control systems (RCS and SCCS).
+* ListDir:: Listing the contents of a file directory.
+* Comparing Files:: Finding where two files differ.
+* Dired:: ``Editing'' a directory to delete, rename, etc.
+ the files in it.
+* Misc File Ops:: Other things you can do on files.
+
+\1f
+File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
+
+File Names
+==========
+
+Most Emacs commands that operate on a file require you to specify the
+file name. (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.) File names are specified in the minibuffer
+(*note Minibuffer::). "Completion" is available, to make it easier to
+specify long file names. *Note Completion::.
+
+ There is always a "default file name" which is used if you enter an
+empty argument by typing just <RET>. Normally the default file name is
+the name of the file visited in the current buffer; this makes it easy
+to operate on that file with any of the Emacs file commands.
+
+ The syntax for accessing remote files unfortunately varies depending
+on the method used. The syntax for using FTP is
+`/USER@REMOTE-HOST:PATH-ON-REMOTE-HOST'. The syntax for using ssh is
+`/[USER@REMOTE-HOST]PATH-ON-REMOTE-HOST'.
+
+ In both cases the `USER@' portion is optional (it defaults to your
+local user name). PATH-ON-REMOTE-HOST may use the `~' notation to
+indicate USER's home directory on the remote host. The default file
+name will reflect the remote host information.
+
+ Each buffer has a default directory, normally the same as the
+directory of the file visited in that buffer. When Emacs reads a file
+name, the default directory is used if you do not specify a directory.
+If you specify a directory in a relative fashion, with a name that does
+not start with a slash, it is interpreted with respect to the default
+directory. The default directory of the current buffer is kept in the
+variable `default-directory', which has a separate value in every
+buffer. The value of the variable should end with a slash.
+
+ For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
+the default directory is `/u/rms/gnu/'. If you type just `foo', which
+does not specify a directory, it is short for `/u/rms/gnu/foo'.
+`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
+the filename `/u/rms/gnu/new/foo'.
+
+ When visiting a remote file via EFS or TRAMP, the remote directory
+becomes the default directory (*note Visiting::) for that buffer, just
+as a local directory would.
+
+ The variable `default-directory-alist' takes an alist of major modes
+and their opinions on `default-directory' as a Lisp expression to
+evaluate. A resulting value of `nil' is ignored in favor of
+`default-directory'.
+
+ You can create a new directory with the function `make-directory',
+which takes as an argument a file name string. The current directory is
+displayed in the minibuffer when the function is called; you can delete
+the old directory name and supply a new directory name. For example, if
+the current directory is `/u/rms/gnu', you can delete `gnu' and type
+`oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
+similar to creating one. To remove a directory, use
+`remove-directory'; it takes one argument, a file name string.
+
+ The command `M-x pwd' prints the current buffer's default directory,
+and the command `M-x cd' sets it (to a value read using the
+minibuffer). A buffer's default directory changes only when the `cd'
+command is used. A file-visiting buffer's default directory is
+initialized to the directory of the file that is visited there. If a
+buffer is created with `C-x b', its default directory is copied from
+that of the buffer that was current at the time.
+
+ The default directory name actually appears in the minibuffer when
+the minibuffer becomes active to read a file name. This serves two
+purposes: it shows you what the default is, so that you can type a
+relative file name and know with certainty what it will mean, and it
+allows you to edit the default to specify a different directory. To
+inhibit the insertion of the default directory, set the variable
+`insert-default-directory' to `nil'.
+
+ Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name. The final minibuffer contents may look invalid, but that is not
+so. *Note Minibuffer File::.
+
+ `$' in a file name is used to substitute environment variables. For
+example, if you have used the shell command `setenv FOO rms/hacks' to
+set up an environment variable named `FOO', then you can use
+`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
+`/u/rms/hacks/test.c'. The environment variable name consists of all
+the alphanumeric characters after the `$'; alternatively, it may be
+enclosed in braces after the `$'. Note that the `setenv' command
+affects Emacs only if done before Emacs is started.
+
+ To access a file with `$' in its name, type `$$'. This pair is
+converted to a single `$' at the same time variable substitution is
+performed for single `$'. The Lisp function that performs the
+substitution is called `substitute-in-file-name'. The substitution is
+performed only on filenames read as such using the minibuffer.
+
+\1f
+File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
+
+Visiting Files
+==============
+
+`C-x C-f'
+ Visit a file (`find-file').
+
+`C-x C-v'
+ Visit a different file instead of the one visited last
+ (`find-alternate-file').
+
+`C-x 4 C-f'
+ Visit a file, in another window (`find-file-other-window'). Don't
+ change this window.
+
+`C-x 5 C-f'
+ Visit a file, in another frame (`find-file-other-frame'). Don't
+ change this window or frame.
+
+ "Visiting" a file means copying its contents into an Emacs buffer so
+you can edit it. Emacs creates a new buffer for each file you visit.
+We say that the buffer is visiting the file that it was created to
+hold. Emacs constructs the buffer name from the file name by throwing
+away the directory and keeping just the file name. For example, a file
+named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
+If a buffer with that name exists, a unique name is constructed by
+appending `<2>', `<3>',and so on, using the lowest number that makes a
+name that is not already in use.
+
+ Each window's mode line shows the name of the buffer that is being
+displayed in that window, so you can always tell what buffer you are
+editing.
+
+ The changes you make with Emacs are made in the Emacs buffer. They
+do not take effect in the file that you visit, or any other permanent
+place, until you "save" the buffer. Saving the buffer means that Emacs
+writes the current contents of the buffer into its visited file. *Note
+Saving::.
+
+ If a buffer contains changes that have not been saved, the buffer is
+said to be "modified". This is important because it implies that some
+changes will be lost if the buffer is not saved. The mode line displays
+two stars near the left margin if the buffer is modified.
+
+ To visit a file, use the command `C-x C-f' (`find-file'). Follow
+the command with the name of the file you wish to visit, terminated by a
+<RET>. If you are using XEmacs under X, you can also use the Open...
+command from the File menu bar item.
+
+ The file name is read using the minibuffer (*note Minibuffer::), with
+defaulting and completion in the standard manner (*note File Names::).
+While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
+
+ `C-x C-f' has completed successfully when text appears on the screen
+and a new buffer name appears in the mode line. If the specified file
+does not exist and could not be created or cannot be read, an error
+results. The error message is printed in the echo area, and includes
+the name of the file that Emacs was trying to visit.
+
+ If you visit a file that is already in Emacs, `C-x C-f' does not make
+another copy. It selects the existing buffer containing that file.
+However, before doing so, it checks that the file itself has not changed
+since you visited or saved it last. If the file has changed, Emacs
+prints a warning message. *Note Simultaneous Editing: Interlocking.
+
+ You can switch to a specific file called out in the current buffer by
+calling the function `find-this-file'. By providing a prefix argument,
+this function calls `filename-at-point' and switches to a buffer
+visiting the file FILENAME. It creates one if none already exists. You
+can use this function to edit the file mentioned in the buffer you are
+working in or to test if the file exists. You can do that by using the
+minibuffer completion after snatching the all or part of the filename.
+
+ If the variable `find-file-use-truenames''s value is non-`nil', a
+buffer's visited filename will always be traced back to the real file.
+The filename will never be a symbolic link, and there will never be a
+symbolic link anywhere in its directory path. In other words, the
+`buffer-file-name' and `buffer-file-truename' will be equal.
+
+ If the variable `find-file-compare-truenames' value is non-`nil',
+the `find-file' command will check the `buffer-file-truename' of all
+visited files when deciding whether a given file is already in a
+buffer, instead of just `buffer-file-name'. If you attempt to visit
+another file which is a symbolic link to a file that is already in a
+buffer, the existing buffer will be found instead of a newly created
+one. This works if any component of the pathname (including a
+non-terminal component) is a symbolic link as well, but doesn't work
+with hard links (nothing does).
+
+ If you want to create a file, just visit it. Emacs prints `(New
+File)' in the echo area, but in other respects behaves as if you had
+visited an existing empty file. If you make any changes and save them,
+the file is created.
+
+ If you visit a nonexistent file unintentionally (because you typed
+the wrong file name), use the `C-x C-v' (`find-alternate-file') command
+to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
+it kills the current buffer (after first offering to save it if it is
+modified). `C-x C-v' is allowed even if the current buffer is not
+visiting a file.
+
+ If the file you specify is actually a directory, Dired is called on
+that directory (*note Dired::). To inhibit this, set the variable
+`find-file-run-dired' to `nil'; then it is an error to try to visit a
+directory.
+
+ `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
+the buffer containing the specified file is selected in another window.
+The window that was selected before `C-x 4 f' continues to show the
+same buffer it was already showing. If you use this command when only
+one window is being displayed, that window is split in two, with one
+window showing the same buffer as before, and the other one showing the
+newly requested file. *Note Windows::.
+
+ `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
+it creates a new frame in which the file is displayed.
+
+ Use the function `find-this-file-other-window' to edit a file
+mentioned in the buffer you are editing or to test if that file exists.
+To do this, use the minibuffer completion after snatching the part or
+all of the filename. By providing a prefix argument, the function calls
+`filename-at-point' and switches you to a buffer visiting the file
+FILENAME in another window. The function creates a buffer if none
+already exists. This function is similar to `find-file-other-window'.
+
+ There are two hook variables that allow extensions to modify the
+operation of visiting files. Visiting a file that does not exist runs
+the functions in the list `find-file-not-found-hooks'; the value of this
+variable is expected to be a list of functions which are called one by
+one until one of them returns non-`nil'. Any visiting of a file,
+whether extant or not, expects `find-file-hooks' to contain list of
+functions and calls them all, one by one. In both cases the functions
+receive no arguments. Visiting a nonexistent file runs the
+`find-file-not-found-hooks' first.
+
+\1f
+File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
+
+Saving Files
+============
+
+"Saving" a buffer in Emacs means writing its contents back into the file
+that was visited in the buffer.
+
+`C-x C-s'
+ Save the current buffer in its visited file (`save-buffer').
+
+`C-x s'
+ Save any or all buffers in their visited files
+ (`save-some-buffers').
+
+`M-~'
+ Forget that the current buffer has been changed (`not-modified').
+
+`C-x C-w'
+ Save the current buffer in a specified file, and record that file
+ as the one visited in the buffer (`write-file').
+
+`M-x set-visited-file-name'
+ Change file the name under which the current buffer will be saved.
+
+ To save a file and make your changes permanent, type `C-x C-s'
+(`save-buffer'). After saving is finished, `C-x C-s' prints a message
+such as:
+
+ Wrote /u/rms/gnu/gnu.tasks
+
+If the selected buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), Emacs does not save it
+because it would have no effect. Instead, `C-x C-s' prints a message
+in the echo area saying:
+
+ (No changes need to be saved)
+
+ The command `C-x s' (`save-some-buffers') can save any or all
+modified buffers. First it asks, for each modified buffer, whether to
+save it. The questions should be answered with `y' or `n'. `C-x C-c',
+the key that kills Emacs, invokes `save-some-buffers' and therefore
+asks the same questions.
+
+ If you have changed a buffer and do not want the changes to be saved,
+you should take some action to prevent it. Otherwise, you are liable to
+save it by mistake each time you use `save-some-buffers' or a related
+command. One thing you can do is type `M-~' (`not-modified'), which
+removes the indication that the buffer is modified. If you do this,
+none of the save commands will believe that the buffer needs to be
+saved. (`~' is often used as a mathematical symbol for `not'; thus
+`Meta-~' is `not', metafied.) You could also use
+`set-visited-file-name' (see below) to mark the buffer as visiting a
+different file name, not in use for anything important.
+
+ You can also undo all the changes made since the file was visited or
+saved, by reading the text from the file again. This is called
+"reverting". *Note Reverting::. Alternatively, you can undo all the
+changes by repeating the undo command `C-x u'; but this only works if
+you have not made more changes than the undo mechanism can remember.
+
+ `M-x set-visited-file-name' alters the name of the file that the
+current buffer is visiting. It prompts you for the new file name in the
+minibuffer. You can also use `set-visited-file-name' on a buffer that
+is not visiting a file. The buffer's name is changed to correspond to
+the file it is now visiting unless the new name is already used by a
+different buffer; in that case, the buffer name is not changed.
+`set-visited-file-name' does not save the buffer in the newly visited
+file; it just alters the records inside Emacs so that it will save the
+buffer in that file. It also marks the buffer as "modified" so that
+`C-x C-s' will save.
+
+ If you wish to mark a buffer as visiting a different file and save it
+right away, use `C-x C-w' (`write-file'). It is precisely equivalent
+to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a
+buffer that is not visiting a file has the same effect as `C-x C-w';
+that is, it reads a file name, marks the buffer as visiting that file,
+and saves it there. The default file name in a buffer that is not
+visiting a file is made by combining the buffer name with the buffer's
+default directory.
+
+ If Emacs is about to save a file and sees that the date of the latest
+version on disk does not match what Emacs last read or wrote, Emacs
+notifies you of this fact, because it probably indicates a problem
+caused by simultaneous editing and requires your immediate attention.
+*Note Simultaneous Editing: Interlocking.
+
+ If the variable `require-final-newline' is non-`nil', Emacs puts a
+newline at the end of any file that doesn't already end in one, every
+time a file is saved or written.
+
+ Use the hook variable `write-file-hooks' to implement other ways to
+write files, and specify things to be done before files are written.
+The value of this variable should be a list of Lisp functions. When a
+file is to be written, the functions in the list are called, one by
+one, with no arguments. If one of them returns a non-`nil' value, Emacs
+takes this to mean that the file has been written in some suitable
+fashion; the rest of the functions are not called, and normal writing is
+not done. Use the hook variable `after-save-hook' to list all the
+functions to be called after writing out a buffer to a file.
+
+* Menu:
+
+* Backup:: How Emacs saves the old version of your file.
+* Interlocking:: How Emacs protects against simultaneous editing
+ of one file by two users.
+
+\1f
+File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
+
+Backup Files
+------------
+
+Because Unix does not provide version numbers in file names, rewriting a
+file in Unix automatically destroys all record of what the file used to
+contain. Thus, saving a file from Emacs throws away the old contents of
+the file--or it would, except that Emacs carefully copies the old
+contents to another file, called the "backup" file, before actually
+saving. (Make sure that the variable `make-backup-files' is non-`nil'.
+Backup files are not written if this variable is `nil').
+
+ At your option, Emacs can keep either a single backup file or a
+series of numbered backup files for each file you edit.
+
+ Emacs makes a backup for a file only the first time a file is saved
+from one buffer. No matter how many times you save a file, its backup
+file continues to contain the contents from before the file was visited.
+Normally this means that the backup file contains the contents from
+before the current editing session; however, if you kill the buffer and
+then visit the file again, a new backup file is made by the next save.
+
+* Menu:
+
+* Names: Backup Names. How backup files are named;
+ Choosing single or numbered backup files.
+* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
+* Copying: Backup Copying. Backups can be made by copying or renaming.
+
+\1f
+File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
+
+Single or Numbered Backups
+..........................
+
+If you choose to have a single backup file (the default), the backup
+file's name is constructed by appending `~' to the file name being
+edited; thus, the backup file for `eval.c' is `eval.c~'.
+
+ If you choose to have a series of numbered backup files, backup file
+names are made by appending `.~', the number, and another `~' to the
+original file name. Thus, the backup files of `eval.c' would be called
+`eval.c.~1~', `eval.c.~2~', and so on, through names like
+`eval.c.~259~' and beyond.
+
+ If protection stops you from writing backup files under the usual
+names, the backup file is written as `%backup%~' in your home directory.
+Only one such file can exist, so only the most recently made backup is
+available.
+
+ The choice of single backup or numbered backups is controlled by the
+variable `version-control'. Its possible values are:
+
+`t'
+ Make numbered backups.
+
+`nil'
+ Make numbered backups for files that have numbered backups already.
+ Otherwise, make single backups.
+
+`never'
+ Never make numbered backups; always make single backups.
+
+`version-control' may be set locally in an individual buffer to control
+the making of backups for that buffer's file. For example, Rmail mode
+locally sets `version-control' to `never' to make sure that there is
+only one backup for an Rmail file. *Note Locals::.
+
+\1f
+File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
+
+Automatic Deletion of Backups
+.............................
+
+To prevent unlimited consumption of disk space, Emacs can delete
+numbered backup versions automatically. Generally Emacs keeps the
+first few backups and the latest few backups, deleting any in between.
+This happens every time a new backup is made. The two variables that
+control the deletion are `kept-old-versions' and `kept-new-versions'.
+Their values are, respectively the number of oldest (lowest-numbered)
+backups to keep and the number of newest (highest-numbered) ones to
+keep, each time a new backup is made. The values are used just after a
+new backup version is made; that newly made backup is included in the
+count in `kept-new-versions'. By default, both variables are 2.
+
+ If `delete-old-versions' is non-`nil', excess middle versions are
+deleted without notification. If it is `nil', the default, you are
+asked whether the excess middle versions should really be deleted.
+
+ You can also use Dired's `.' (Period) command to delete old versions.
+*Note Dired::.
+
+\1f
+File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup
+
+Copying vs. Renaming
+....................
+
+You can make backup files by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names. If you
+rename the old file into the backup file, the alternate names become
+names for the backup file. If you copy the old file instead, the
+alternate names remain names for the file that you are editing, and the
+contents accessed by those names will be the new contents.
+
+ How you make a backup file may also affect the file's owner and
+group. If you use copying, they do not change. If renaming is used,
+you become the file's owner, and the file's group becomes the default
+(different operating systems have different defaults for the group).
+
+ Having the owner change is usually a good idea, because then the
+owner is always the person who last edited the file. Occasionally
+there is a file whose owner should not change. Since most files should
+change owners, it is a good idea to use local variable lists to set
+`backup-by-copying-when-mismatch' for the special cases where the owner
+should not change (*note File Variables::).
+
+ Three variables control the choice of renaming or copying.
+Normally, renaming is done. If the variable `backup-by-copying' is
+non-`nil', copying is used. Otherwise, if the variable
+`backup-by-copying-when-linked' is non-`nil', copying is done for files
+that have multiple names, but renaming may still be done when the file
+being edited has only one name. If the variable
+`backup-by-copying-when-mismatch' is non-`nil', copying is done if
+renaming would cause the file's owner or group to change.
+
+\1f
+File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving
+
+Protection Against Simultaneous Editing
+---------------------------------------
+
+Simultaneous editing occurs when two users visit the same file, both
+make changes, and both save their changes. If no one was informed that
+this was happening, and you saved first, you would later find that your
+changes were lost. On some systems, Emacs notices immediately when the
+second user starts to change a file already being edited, and issues a
+warning. When this is not possible, or if the second user has started
+to change the file despite the warning, Emacs checks when the file is
+saved, and issues a second warning when a user is about to overwrite a
+file containing another user's changes. If you are the user editing the
+file, you can take corrective action at this point and prevent actual
+loss of work.
+
+ When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that you have locked the file. (It does
+this by writing another file in a directory reserved for this purpose.)
+The lock is removed when you save the changes. The idea is that the
+file is locked whenever the buffer is modified. If you begin to modify
+the buffer while the visited file is locked by someone else, this
+constitutes a collision, and Emacs asks you what to do. It does this
+by calling the Lisp function `ask-user-about-lock', which you can
+redefine to customize what it does. The standard definition of this
+function asks you a question and accepts three possible answers:
+
+`s'
+ Steal the lock. Whoever was already changing the file loses the
+ lock, and you get the lock.
+
+`p'
+ Proceed. Go ahead and edit the file despite its being locked by
+ someone else.
+
+`q'
+ Quit. This causes an error (`file-locked') and the modification
+ you were trying to make in the buffer does not actually take place.
+
+ Note that locking works on the basis of a file name; if a file has
+multiple names, Emacs does not realize that the two names are the same
+file and cannot prevent two users from editing it simultaneously under
+different names. However, basing locking on names means that Emacs can
+interlock the editing of new files that do not really exist until they
+are saved.
+
+ Some systems are not configured to allow Emacs to make locks. On
+these systems, Emacs cannot detect trouble in advance, but it can still
+detect it in time to prevent you from overwriting someone else's
+changes.
+
+ Every time Emacs saves a buffer, it first checks the
+last-modification date of the existing file on disk to see that it has
+not changed since the file was last visited or saved. If the date does
+not match, it implies that changes were made in the file in some other
+way, and these changes are about to be lost if Emacs actually does
+save. To prevent this, Emacs prints a warning message and asks for
+confirmation before saving. Occasionally you will know why the file
+was changed and know that it does not matter; then you can answer `yes'
+and proceed. Otherwise, you should cancel the save with `C-g' and
+investigate the situation.
+
+ The first thing you should do when notified that simultaneous editing
+has already taken place is to list the directory with `C-u C-x C-d'
+(*note Directory Listing: ListDir.). This will show the file's current
+author. You should attempt to contact that person and ask him not to
+continue editing. Often the next step is to save the contents of your
+Emacs buffer under a different name, and use `diff' to compare the two
+files.
+
+ Simultaneous editing checks are also made when you visit a file that
+is already visited with `C-x C-f' and when you start to modify a file.
+This is not strictly necessary, but it is useful to find out about such
+a problem as early as possible, when corrective action takes less work.
+
+ Another way to protect your file is to set the read, write, and
+executable permissions for the file. Use the function
+`set-default-file-modes' to set the UNIX `umask' value to the NMASK
+argument. The `umask' value is the default protection mode for new
+files.
+
+\1f
+File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files
+
+Reverting a Buffer
+==================
+
+If you have made extensive changes to a file and then change your mind
+about them, you can get rid of all changes by reading in the previous
+version of the file. To do this, use `M-x revert-buffer', which
+operates on the current buffer. Since reverting a buffer can result in
+very extensive changes, you must confirm it with `yes'.
+
+ You may request that `revert-buffer' check for an auto-save file
+that is more recent than the visited file by providing a prefix
+argument. If a recent auto-save file exists, `revert-buffer' offers to
+read the auto-save file instead of the visited file (*note Auto
+Save::). Emacs asks you about the auto-save file before the request
+for confirmation of the `revert-buffer' operation, and demands `y' or
+`n' as an answer. If you have started to type `yes' to confirm the
+revert operation, the `y' will answer the question about using the
+auto-save file, but the `es' will not be valid confirmation for the
+reversion. This gives you a chance to cancel the operation with `C-g'
+and try again with the answers you really intend.
+
+ `revert-buffer' preserves the value of point (in characters from the
+beginning of the file). If the file was edited only slightly, you will
+be at approximately the same piece of text after reverting as before.
+If you have made more extensive changes, after reversion point may be
+in a totally different context than your last edits before reversion.
+
+ A buffer reverted from its visited file is marked "not modified"
+until you make a change. The buffer's modes will also be recalculated,
+by `normal-mode'.
+
+ Some kinds of buffers whose contents reflect data bases other than
+files, such as Dired buffers, can also be reverted. For them,
+reverting means refreshing their contents from the appropriate data.
+Buffers created randomly with `C-x b' cannot be reverted;
+`revert-buffer' reports an error when asked to do so.
+
+\1f
+File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files
+
+Auto-Saving: Protection Against Disasters
+=========================================
+
+Emacs saves all the visited files from time to time (based on counting
+your keystrokes) without being asked. This is called "auto-saving".
+It prevents you from losing more than a limited amount of work if the
+system crashes.
+
+ When Emacs determines it is time for auto-saving, each buffer is
+considered and is auto-saved if auto-saving is turned on for it and it
+has changed since the last time it was auto-saved. If any auto-saving
+is done, the message `Auto-saving...' is displayed in the echo area
+until auto-saving is finished. Errors occurring during auto-saving are
+caught so that they do not interfere with the execution of commands you
+have been typing.
+
+* Menu:
+
+* Files: Auto Save Files.
+* Control: Auto Save Control.
+* Recover:: Recovering text from auto-save files.
+
+\1f
+File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save
+
+Auto-Save Files
+---------------
+
+Auto-saving does not normally write to the files you visited, because
+it can be undesirable to save a program that is in an inconsistent
+state when you have made only half of a planned change. Instead,
+auto-saving is done in a different file called the "auto-save file",
+and the visited file is changed only when you save explicitly, for
+example, with `C-x C-s'.
+
+ Normally, the name of the auto-save file is generated by appending
+`#' to the front and back of the visited file name. Thus, a buffer
+visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most
+buffers that are not visiting files are auto-saved only if you request
+it explicitly; when they are auto-saved, the auto-save file name is
+generated by appending `#%' to the front and `#' to the back of buffer
+name. For example, the `*mail*' buffer in which you compose messages
+to be sent is auto-saved in a file named `#%*mail*#'. Names of
+auto-save files are generated this way unless you customize the
+functions `make-auto-save-file-name' and `auto-save-file-name-p' to do
+something different. The file name to be used for auto-saving a buffer
+is calculated at the time auto-saving is turned on in that buffer.
+
+ If you want auto-saving to be done in the visited file, set the
+variable `auto-save-visited-file-name' to be non-`nil'. In this mode,
+there is really no difference between auto-saving and explicit saving.
+
+ Emacs deletes a buffer's auto-save file when you explicitly save the
+buffer. To inhibit the deletion, set the variable
+`delete-auto-save-files' to `nil'. Changing the visited file name with
+`C-x C-w' or `set-visited-file-name' renames any auto-save file to
+correspond to the new visited name.
+
+\1f
+File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
+
+Controlling Auto-Saving
+-----------------------
+
+Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable `auto-save-default' is non-`nil' (but not in
+batch mode; *note Entering Emacs::). The default for this variable is
+`t', so Emacs auto-saves buffers that visit files by default. You can
+use the command `M-x auto-save-mode' to turn auto-saving for a buffer
+on or off. Like other minor mode commands, `M-x auto-save-mode' turns
+auto-saving on with a positive argument, off with a zero or negative
+argument; with no argument, it toggles.
+
+ Emacs performs auto-saving periodically based on counting how many
+characters you have typed since the last time auto-saving happened. The
+variable `auto-save-interval' specifies the number of characters
+between auto-saves. By default, it is 300. Emacs also auto-saves
+whenever you call the function `do-auto-save'.
+
+ Emacs also does auto-saving whenever it gets a fatal error. This
+includes killing the Emacs job with a shell command such as `kill
+-emacs', or disconnecting a phone line or network connection.
+
+ You can set the number of seconds of idle time before an auto-save is
+done. Setting the value of the variable `auto-save-timeout' to zero or
+`nil' will disable auto-saving due to idleness.
+
+ The actual amount of idle time between auto-saves is logarithmically
+related to the size of the current buffer. This variable is the number
+of seconds after which an auto-save will happen when the current buffer
+is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
+3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
+buffer.
+
+ For this variable to have any effect, you must do `(require 'timer)'.
+
+\1f
+File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save
+
+Recovering Data from Auto-Saves
+-------------------------------
+
+If you want to use the contents of an auto-save file to recover from a
+loss of data, use the command `M-x recover-file <RET> FILE <RET>'.
+Emacs visits FILE and then (after your confirmation) restores the
+contents from the auto-save file `#FILE#'. You can then save the file
+with `C-x C-s' to put the recovered text into FILE itself. For
+example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
+
+ M-x recover-file <RET> foo.c <RET>
+ C-x C-s
+
+ Before asking for confirmation, `M-x recover-file' displays a
+directory listing describing the specified file and the auto-save file,
+so you can compare their sizes and dates. If the auto-save file is
+older, `M-x recover-file' does not offer to read it.
+
+ Auto-saving is disabled by `M-x recover-file' because using this
+command implies that the auto-save file contains valuable data from a
+past session. If you save the data in the visited file and then go on
+to make new changes, turn auto-saving back on with `M-x auto-save-mode'.
+
+\1f
+File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files
+
+Version Control
+===============
+
+"Version control systems" are packages that can record multiple
+versions of a source file, usually storing the unchanged parts of the
+file just once. Version control systems also record history information
+such as the creation time of each version, who created it, and a
+description of what was changed in that version.
+
+ The GNU project recommends the version control system known as RCS,
+which is free software and available from the Free Software Foundation.
+Emacs supports use of either RCS or SCCS (a proprietary, but widely
+used, version control system that is not quite as powerful as RCS)
+through a facility called VC. The same Emacs commands work with either
+RCS or SCCS, so you hardly have to know which one of them you are using.
+
+* Menu:
+
+* Concepts of VC:: Basic version control information;
+ checking files in and out.
+* Editing with VC:: Commands for editing a file maintained
+ with version control.
+* Variables for Check-in/out:: Variables that affect the commands used
+ to check files in or out.
+* Log Entries:: Logging your changes.
+* Change Logs and VC:: Generating a change log file from log
+ entries.
+* Old Versions:: Examining and comparing old versions.
+* VC Status:: Commands to view the VC status of files and
+ look at log entries.
+* Renaming and VC:: A command to rename both the source and
+ master file correctly.
+* Snapshots:: How to make and use snapshots, a set of
+ file versions that can be treated as a unit.
+* Version Headers:: Inserting version control headers into
+ working files.
+
+\1f
+File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control
+
+Concepts of Version Control
+---------------------------
+
+When a file is under version control, we also say that it is
+"registered" in the version control system. Each registered file has a
+corresponding "master file" which represents the file's present state
+plus its change history, so that you can reconstruct from it either the
+current version or any specified earlier version. Usually the master
+file also records a "log entry" for each version describing what was
+changed in that version.
+
+ The file that is maintained under version control is sometimes called
+the "work file" corresponding to its master file.
+
+ To examine a file, you "check it out". This extracts a version of
+the source file (typically, the most recent) from the master file. If
+you want to edit the file, you must check it out "locked". Only one
+user can do this at a time for any given source file. (This kind of
+locking is completely unrelated to the locking that Emacs uses to
+detect simultaneous editing of a file.)
+
+ When you are done with your editing, you must "check in" the new
+version. This records the new version in the master file, and unlocks
+the source file so that other people can lock it and thus modify it.
+
+ Checkin and checkout are the basic operations of version control.
+You can do both of them with a single Emacs command: `C-x C-q'
+(`vc-toggle-read-only').
+
+ A "snapshot" is a coherent collection of versions of the various
+files that make up a program. *Note Snapshots::.
+
+\1f
+File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control
+
+Editing with Version Control
+----------------------------
+
+When you visit a file that is maintained using version control, the
+mode line displays `RCS' or `SCCS' to inform you that version control
+is in use, and also (in case you care) which low-level system the file
+is actually stored in. Normally, such a source file is read-only, and
+the mode line indicates this with `%%'. With RCS, the mode line also
+indicates the number of the head version, which is normally also the
+version you are looking at.
+
+ These are the commands for editing a file maintained with version
+control:
+
+`C-x C-q'
+ Check the visited file in or out.
+
+`C-x v u'
+ Revert the buffer and the file to the last checked in version.
+
+`C-x v c'
+ Remove the last-entered change from the master for the visited
+ file. This undoes your last check-in.
+
+`C-x v i'
+ Register the visited file in version control.
+
+(`C-x v' is the prefix key for version control commands; all of these
+commands except for `C-x C-q' start with `C-x v'.)
+
+ When you want to modify a file maintained with version control, type
+`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and
+tells RCS or SCCS to lock the file. This means making the file
+writable for you (but not for anyone else).
+
+ When you are finished editing the file, type `C-x C-q' again. When
+used on a file that is checked out, this command checks the file in.
+But check-in does not start immediately; first, you must enter the "log
+entry"--a description of the changes in the new version. `C-x C-q'
+pops up a buffer for you to enter this in. When you are finished
+typing in the log entry, type `C-c C-c' to terminate it; this is when
+actual check-in takes place.
+
+ Once you have checked in your changes, the file is unlocked, so that
+other users can lock it and modify it.
+
+ Emacs does not save backup files for source files that are maintained
+with version control. If you want to make backup files despite version
+control, set the variable `vc-make-backup-files' to a non-`nil' value.
+
+ Normally the work file exists all the time, whether it is locked or
+not. If you set `vc-keep-workfiles' to `nil', then checking in a new
+version with `C-x C-q' deletes the work file; but any attempt to visit
+the file with Emacs creates it again.
+
+ It is not impossible to lock a file that someone else has locked. If
+you try to check out a file that is locked, `C-x C-q' asks you whether
+you want to "steal the lock." If you say yes, the file becomes locked
+by you, but a message is sent to the person who had formerly locked the
+file, to inform him of what has happened. The mode line indicates that
+a file is locked by someone else by displaying the login name of that
+person, before the version number.
+
+ If you want to discard your current set of changes and revert to the
+last version checked in, use `C-x v u' (`vc-revert-buffer'). This
+cancels your last check-out, leaving the file unlocked. If you want to
+make a different set of changes, you must first check the file out
+again. `C-x v u' requires confirmation, unless it sees that you
+haven't made any changes since the last checked-in version.
+
+ `C-x v u' is also the command to use if you lock a file and then
+don't actually change it.
+
+ You can cancel a change after checking it in, with `C-x v c'
+(`vc-cancel-version'). This command discards all record of the most
+recent checked in version, so be careful about using it. It requires
+confirmation with `yes'. By default, `C-x v c' reverts your workfile
+and buffer to the previous version (the one that precedes the version
+that is deleted), but you can prevent the reversion by giving the
+command a prefix argument. Then the buffer does not change.
+
+ This command with a prefix argument is useful when you have checked
+in a change and then discover a trivial error in it; you can cancel the
+erroneous check-in, fix the error, and repeat the check-in.
+
+ Be careful when invoking `C-x v c', as it is easy to throw away a
+lot of work with it. To help you be careful, this command always
+requires confirmation with `yes'.
+
+ You can register the visited file for version control using
+`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is
+non-`nil', it specifies which version control system to use; otherwise,
+this uses RCS if it is installed on your system and SCCS if not. After
+`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you
+wish to edit it.
+
+ By default, the initial version number is 1.1. If you want to use a
+different number, give `C-x v i' a prefix argument; then it reads the
+initial version number using the minibuffer.
+
+ If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
+comment (much like a log entry) to describe the purpose of this source
+file.
+
+ To specify the version number for a subsequent checkin, use the
+command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command
+that `C-x C-q' uses to do the "real work" when the visited file uses
+version control. When used for checkin, and given a prefix argument,
+it reads the version number with the minibuffer.
+
+\1f
+File: xemacs.info, Node: Variables for Check-in/out, Next: Log Entries, Prev: Editing with VC, Up: Version Control
+
+Variables Affecting Check-in and Check-out
+------------------------------------------
+
+If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i' can
+save the current buffer without asking, and `C-x v u' also operates
+without asking for confirmation. (This variable does not affect `C-x v
+c'; that is so drastic that it should always ask for confirmation.)
+
+ VC mode does much of its work by running the shell commands for RCS
+and SCCS. If `vc-command-messages' is non-`nil', VC displays messages
+to indicate which shell commands it runs, and additional messages when
+the commands finish.
+
+ Normally, VC assumes that it can deduce the locked/unlocked state of
+files by looking at the file permissions of the work file; this is
+fast. However, if the `RCS' or `SCCS' subdirectory is actually a
+symbolic link, then VC does not trust the file permissions to reflect
+this status.
+
+ You can specify the criterion for whether to trust the file
+permissions by setting the variable `vc-mistrust-permissions'. Its
+value may be `t' (always mistrust the file permissions and check the
+master file), `nil' (always trust the file permissions), or a function
+of one argument which makes the decision. The argument is the directory
+name of the `RCS' or `SCCS' subdirectory. A non-`nil' value from the
+function says to mistrust the file permissions.
+
+ If you find that the file permissions of work files are changed
+erroneously, set `vc-mistrust-permissions' to `t'. Then VC always
+checks the master file to determine the file's status.
+
+ You can specify additional directories to search for version control
+programs by setting the variable `vc-path'. These directories are
+searched before the usual search path. The proper result usually
+happens automatically.
+
+\1f
+File: xemacs.info, Node: Log Entries, Next: Change Logs and VC, Prev: Variables for Check-in/out, Up: Version Control
+
+Log Entries
+-----------
+
+When you're editing an initial comment or log entry for inclusion in a
+master file, finish your entry by typing `C-c C-c'.
+
+`C-c C-c'
+ Finish the comment edit normally (`vc-finish-logentry'). This
+ finishes check-in.
+
+ To abort check-in, just don't type `C-c C-c' in that buffer. You
+can switch buffers and do other editing. As long as you don't try to
+check in another file, the entry you were editing remains in its
+buffer, and you can go back to that buffer at any time to complete the
+check-in.
+
+ If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files. To do
+this, use the history of previous log entries. The commands `M-n',
+`M-p', `M-s' and `M-r' for doing this work just like the minibuffer
+history commands (except that these versions are used outside the
+minibuffer).
+
+ Each time you check in a file, the log entry buffer is put into VC
+Log mode, which involves running two hooks: `text-mode-hook' and
+`vc-log-mode-hook'.
+
+\1f
+File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control
+
+Change Logs and VC
+------------------
+
+If you use RCS for a program and also maintain a change log file for it
+(*note Change Log::), you can generate change log entries automatically
+from the version control log entries:
+
+`C-x v a'
+ Visit the current directory's change log file and create new
+ entries for versions checked in since the most recent entry in the
+ change log file (`vc-update-change-log').
+
+ This command works with RCS only; it does not work with SCCS.
+
+ For example, suppose the first line of `ChangeLog' is dated 10 April
+1992, and that the only check-in since then was by Nathaniel Bowditch
+to `rcs2log' on 8 May 1992 with log text `Ignore log messages that
+start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text
+like this:
+
+ Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * rcs2log: Ignore log messages that start with `#'.
+
+You can then edit the new change log entry further as you wish.
+
+ Normally, the log entry for file `foo' is displayed as `* foo: TEXT
+OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log
+entry starts with `(FUNCTIONNAME): '. For example, if the log entry
+for `vc.el' is `(vc-do-command): Check call-process status.', then the
+text in `ChangeLog' looks like this:
+
+ Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.el (vc-do-command): Check call-process status.
+
+ When `C-x v a' adds several change log entries at once, it groups
+related log entries together if they all are checked in by the same
+author at nearly the same time. If the log entries for several such
+files all have the same text, it coalesces them into a single entry.
+For example, suppose the most recent checkins have the following log
+entries:
+
+For `vc.texinfo':
+ Fix expansion typos.
+For `vc.el':
+ Don't call expand-file-name.
+For `vc-hooks.el':
+ Don't call expand-file-name.
+
+ They appear like this in `ChangeLog':
+
+ Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.texinfo: Fix expansion typos.
+
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+ Normally, `C-x v a' separates log entries by a blank line, but you
+can mark several related log entries to be clumped together (without an
+intervening blank line) by starting the text of each related log entry
+with a label of the form `{CLUMPNAME} '. The label itself is not
+copied to `ChangeLog'. For example, suppose the log entries are:
+
+For `vc.texinfo':
+ {expand} Fix expansion typos.
+For `vc.el':
+ {expand} Don't call expand-file-name.
+For `vc-hooks.el':
+ {expand} Don't call expand-file-name.
+
+Then the text in `ChangeLog' looks like this:
+
+ Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.texinfo: Fix expansion typos.
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+ A log entry whose text begins with `#' is not copied to `ChangeLog'.
+For example, if you merely fix some misspellings in comments, you can
+log the change with an entry beginning with `#' to avoid putting such
+trivia into `ChangeLog'.
+
+\1f
+File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
+
+Examining And Comparing Old Versions
+------------------------------------
+
+`C-x v ~ VERSION <RET>'
+ Examine version VERSION of the visited file, in a buffer of its
+ own (`vc-version-other-window').
+
+`C-x v ='
+ Compare the current buffer contents with the latest checked-in
+ version of the file.
+
+`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
+ Compare the specified two versions of FILE.
+
+ You can examine any version of a file by first visiting it, and then
+using `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
+the text of version VERSION in a file named `FILENAME.~VERSION~', then
+visits it in a separate window.
+
+ To compare two versions of a file, use the command `C-x v ='
+(`vc-diff').
+
+ Plain `C-x v =' compares the current buffer contents (saving them in
+the file if necessary) with the last checked-in version of the file.
+With a prefix argument, `C-x v =' reads a file name and two version
+numbers, then compares those versions of the specified file.
+
+ If you supply a directory name instead of the name of a work file,
+this command compares the two specified versions of all registered files
+in that directory and its subdirectories. You can also specify a
+snapshot name (*note Snapshots::) instead of one or both version
+numbers.
+
+ You can specify a checked-in version by its number; you can specify
+the most recent checked-in version with an empty version number.
+
+ This command works by running the `vcdiff' utility, getting the
+options from the variable `diff-switches'. It displays the output in a
+special buffer in another window. Unlike the `M-x diff' command, `C-x
+v =' does not try to find the changes in the old and new versions.
+This is because one or both versions normally do not exist as files.
+They exist only in the records of the master file. *Note Comparing
+Files::, for more information about `M-x diff'.
+
+\1f
+File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control
+
+VC Status Commands
+------------------
+
+To view the detailed version control status and history of a file, type
+`C-x v l' (`vc-print-log'). It displays the history of changes to the
+current file, including the text of the log entries. The output
+appears in a separate window.
+
+ When you are working on a large program, it's often useful to find
+all the files that are currently locked, or all the files maintained in
+version control at all. You can use `C-x v d' (`vc-directory') to show
+all the locked files in or beneath the current directory. This
+includes all files that are locked by any user. `C-u C-x v d' lists
+all files in or beneath the current directory that are maintained with
+version control.
+
+ The list of files is displayed as a buffer that uses an augmented
+Dired mode. The names of the users locking various files are shown (in
+parentheses) in place of the owner and group. All the normal Dired
+commands work in this buffer. Most interactive VC commands work also,
+and apply to the file name on the current line.
+
+ The `C-x v v' command (`vc-next-action'), when used in the augmented
+Dired buffer, operates on all the marked files (or the file on the
+current line). If it operates on more than one file, it handles each
+file according to its current state; thus, it may check out one file
+and check in another (because it is already checked out). If it has to
+check in any files, it reads a single log entry, then uses that text
+for all the files being checked in. This can be convenient for
+registering or checking in several files at once, as part of the same
+change.
+
+\1f
+File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control
+
+Renaming VC Work Files and Master Files
+---------------------------------------
+
+When you rename a registered file, you must also rename its master file
+correspondingly to get proper results. Use `vc-rename-file' to rename
+the source file as you specify, and rename its master file accordingly.
+It also updates any snapshots (*note Snapshots::) that mention the
+file, so that they use the new name; despite this, the snapshot thus
+modified may not completely work (*note Snapshot Caveats::).
+
+ You cannot use `vc-rename-file' on a file that is locked by someone
+else.
+
+\1f
+File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control
+
+Snapshots
+---------
+
+A "snapshot" is a named set of file versions (one for each registered
+file) that you can treat as a unit. One important kind of snapshot is
+a "release", a (theoretically) stable version of the system that is
+ready for distribution to users.
+
+* Menu:
+
+* Making Snapshots:: The snapshot facilities.
+* Snapshot Caveats:: Things to be careful of when using snapshots.
+
+\1f
+File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots
+
+Making and Using Snapshots
+..........................
+
+There are two basic commands for snapshots; one makes a snapshot with a
+given name, the other retrieves a named snapshot.
+
+`C-x v s NAME <RET>'
+ Define the last saved versions of every registered file in or
+ under the current directory as a snapshot named NAME
+ (`vc-create-snapshot').
+
+`C-x v r NAME <RET>'
+ Check out all registered files at or below the current directory
+ level using whatever versions correspond to the snapshot NAME
+ (`vc-retrieve-snapshot').
+
+ This command reports an error if any files are locked at or below
+ the current directory, without changing anything; this is to avoid
+ overwriting work in progress.
+
+ A snapshot uses a very small amount of resources--just enough to
+record the list of file names and which version belongs to the
+snapshot. Thus, you need not hesitate to create snapshots whenever
+they are useful.
+
+ You can give a snapshot name as an argument to `C-x v =' or `C-x v
+~' (*note Old Versions::). Thus, you can use it to compare a snapshot
+against the current files, or two snapshots against each other, or a
+snapshot against a named version.
+
+\1f
+File: xemacs.info, Node: Snapshot Caveats, Prev: Making Snapshots, Up: Snapshots
+
+Snapshot Caveats
+................
+
+VC's snapshot facilities are modeled on RCS's named-configuration
+support. They use RCS's native facilities for this, so under VC
+snapshots made using RCS are visible even when you bypass VC.
+
+ For SCCS, VC implements snapshots itself. The files it uses contain
+name/file/version-number triples. These snapshots are visible only
+through VC.
+
+ A snapshot is a set of checked-in versions. So make sure that all
+the files are checked in and not locked when you make a snapshot.
+
+ File renaming and deletion can create some difficulties with
+snapshots. This is not a VC-specific problem, but a general design
+issue in version control systems that no one has solved very well yet.
+
+ If you rename a registered file, you need to rename its master along
+with it (the command `vc-rename-file' does this automatically). If you
+are using SCCS, you must also update the records of the snapshot, to
+mention the file by its new name (`vc-rename-file' does this, too). An
+old snapshot that refers to a master file that no longer exists under
+the recorded name is invalid; VC can no longer retrieve it. It would
+be beyond the scope of this manual to explain enough about RCS and SCCS
+to explain how to update the snapshots by hand.
+
+ Using `vc-rename-file' makes the snapshot remain valid for
+retrieval, but it does not solve all problems. For example, some of the
+files in the program probably refer to others by name. At the very
+least, the makefile probably mentions the file that you renamed. If you
+retrieve an old snapshot, the renamed file is retrieved under its new
+name, which is not the name that the makefile expects. So the program
+won't really work as retrieved.
+
+\1f
+File: xemacs.info, Node: Version Headers, Prev: Snapshots, Up: Version Control
+
+Inserting Version Control Headers
+---------------------------------
+
+Sometimes it is convenient to put version identification strings
+directly into working files. Certain special strings called "version
+headers" are replaced in each successive version by the number of that
+version.
+
+ You can use the `C-x v h' command (`vc-insert-headers') to insert a
+suitable header string.
+
+`C-x v h'
+ Insert headers in a file for use with your version-control system.
+
+ The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS.
+(The actual strings inserted do not have the backslashes in them. They
+were placed in the Info source file so that the strings don't get
+interpreted as version-control headers when the Info source files are
+maintained under version control.) You can specify other headers to
+insert by setting the variable `vc-header-alist'. Its value is a list
+of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or
+`SCCS' and STRING is the string to use.
+
+ Instead of a single string, you can specify a list of strings; then
+each string in the list is inserted as a separate header on a line of
+its own.
+
+ It is often necessary to use "superfluous" backslashes when writing
+the strings that you put in this variable. This is to prevent the
+string in the constant from being interpreted as a header itself if the
+Emacs Lisp file containing it is maintained with version control.
+
+ Each header is inserted surrounded by tabs, inside comment
+delimiters, on a new line at the start of the buffer. Normally the
+ordinary comment start and comment end strings of the current mode are
+used, but for certain modes, there are special comment delimiters for
+this purpose; the variable `vc-comment-alist' specifies them. Each
+element of this list has the form `(MODE STARTER ENDER)'.
+
+ The variable `vc-static-header-alist' specifies further strings to
+add based on the name of the buffer. Its value should be a list of
+elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the
+buffer name, FORMAT is inserted as part of the header. A header line
+is inserted for each element that matches the buffer name, and for each
+string specified by `vc-header-alist'. The header line is made by
+processing the string from `vc-header-alist' with the format taken from
+the element. The default value for `vc-static-header-alist' is:
+
+ (("\\.c$" .
+ "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+ #endif /* lint */\n"))
+
+which specifies insertion of a string of this form:
+
+
+ #ifndef lint
+ static char vcid[] = "STRING";
+ #endif /* lint */
+
+\1f
+File: xemacs.info, Node: ListDir, Next: Comparing Files, Prev: Version Control, Up: Files
+
+Listing a File Directory
+========================
+
+Files are organized by Unix into "directories". A "directory listing"
+is a list of all the files in a directory. Emacs provides directory
+listings in brief format (file names only) and verbose format (sizes,
+dates, and authors included).
+
+`C-x C-d DIR-OR-PATTERN'
+ Print a brief directory listing (`list-directory').
+
+`C-u C-x C-d DIR-OR-PATTERN'
+ Print a verbose directory listing.
+
+ To print a directory listing, use `C-x C-d' (`list-directory').
+This command prompts in the minibuffer for a file name which is either
+a directory to be listed or pattern containing wildcards for the files
+to be listed. For example,
+
+ C-x C-d /u2/emacs/etc <RET>
+
+lists all the files in directory `/u2/emacs/etc'. An example of
+specifying a file name pattern is:
+
+ C-x C-d /u2/emacs/src/*.c <RET>
+
+ Normally, `C-x C-d' prints a brief directory listing containing just
+file names. A numeric argument (regardless of value) tells it to print
+a verbose listing (like `ls -l').
+
+ Emacs obtains the text of a directory listing by running `ls' in an
+inferior process. Two Emacs variables control the switches passed to
+`ls': `list-directory-brief-switches' is a string giving the switches
+to use in brief listings (`"-CF"' by default).
+`list-directory-verbose-switches' is a string giving the switches to
+use in a verbose listing (`"-l"' by default).
+
+ The variable `directory-abbrev-alist' is an alist of abbreviations
+for file directories. The list consists of elements of the form `(FROM
+. TO)', each meaning to replace `FROM' with `TO' when it appears in a
+directory name. This replacement is done when setting up the default
+directory of a newly visited file. Every `FROM' string should start
+with ``^''.
+
+ Use this feature when you have directories which you normally refer
+to via absolute symbolic links. Make `TO' the name of the link, and
+`FROM' the name it is linked to.
+
+\1f
+File: xemacs.info, Node: Comparing Files, Next: Dired, Prev: ListDir, Up: Files
+
+Comparing Files
+===============
+
+The command `M-x diff' compares two files, displaying the differences
+in an Emacs buffer named `*Diff*'. It works by running the `diff'
+program, using options taken from the variable `diff-switches', whose
+value should be a string.
+
+ The buffer `*Diff*' has Compilation mode as its major mode, so you
+can use `C-x `' to visit successive changed locations in the two source
+files. You can also move to a particular hunk of changes and type `C-c
+C-c' to find the corresponding source location. You can also use the
+other special commands of Compilation mode: <SPC> and <DEL> for
+scrolling, and `M-p' and `M-n' for cursor motion. *Note Compilation::.
+
+ The command `M-x diff-backup' compares a specified file with its most
+recent backup. If you specify the name of a backup file, `diff-backup'
+compares it with the source file that it is a backup of.
+
+ The command `M-x compare-windows' compares the text in the current
+window with that in the next window. Comparison starts at point in each
+window. Point moves forward in each window, a character at a time in
+each window, until the next characters in the two windows are
+different. Then the command is finished. For more information about
+windows in Emacs, *Note Windows::.
+
+ With a numeric argument, `compare-windows' ignores changes in
+whitespace. If the variable `compare-ignore-case' is non-`nil', it
+ignores differences in case as well.
+
+\1f
+File: xemacs.info, Node: Dired, Next: Misc File Ops, Prev: Comparing Files, Up: Files
+
+Dired, the Directory Editor
+===========================
+
+Dired makes it easy to delete or visit many of the files in a single
+directory at once. It creates an Emacs buffer containing a listing of
+the directory. You can use the normal Emacs commands to move around in
+this buffer and special Dired commands to operate on the files.
+
+* Menu:
+
+* Enter: Dired Enter. How to invoke Dired.
+* Edit: Dired Edit. Editing the Dired buffer.
+* Deletion: Dired Deletion. Deleting files with Dired.
+* Immed: Dired Immed. Other file operations through Dired.
+
+\1f
+File: xemacs.info, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired
+
+Entering Dired
+--------------
+
+To invoke dired, type `C-x d' or `M-x dired'. The command reads a
+directory name or wildcard file name pattern as a minibuffer argument
+just like the `list-directory' command, `C-x C-d'. Where `dired'
+differs from `list-directory' is in naming the buffer after the
+directory name or the wildcard pattern used for the listing, and putting
+the buffer into Dired mode so that the special commands of Dired are
+available in it. The variable `dired-listing-switches' is a string
+used as an argument to `ls' in making the directory; this string must
+contain `-l'.
+
+ To display the Dired buffer in another window rather than in the
+selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x
+d'.
+
+\1f
+File: xemacs.info, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired
+
+Editing in Dired
+----------------
+
+Once the Dired buffer exists, you can switch freely between it and other
+Emacs buffers. Whenever the Dired buffer is selected, certain special
+commands are provided that operate on files that are listed. The Dired
+buffer is "read-only", and inserting text in it is not useful, so
+ordinary printing characters such as `d' and `x' are used for Dired
+commands. Most Dired commands operate on the file described by the line
+that point is on. Some commands perform operations immediately; others
+"flag" a file to be operated on later.
+
+ Most Dired commands that operate on the current line's file also
+treat a numeric argument as a repeat count, meaning to act on the files
+of the next few lines. A negative argument means to operate on the
+files of the preceding lines, and leave point on the first of those
+lines.
+
+ All the usual Emacs cursor motion commands are available in Dired
+buffers. Some special purpose commands are also provided. The keys
+`C-n' and `C-p' are redefined so that they try to position the cursor
+at the beginning of the filename on the line, rather than at the
+beginning of the line.
+
+ For extra convenience, <SPC> and `n' in Dired are equivalent to
+`C-n'. `p' is equivalent to `C-p'. Moving by lines is done so often
+in Dired that it deserves to be easy to type. <DEL> (move up and
+unflag) is often useful simply for moving up.
+
+ The `g' command in Dired runs `revert-buffer' to reinitialize the
+buffer from the actual disk directory and show any changes made in the
+directory by programs other than Dired. All deletion flags in the Dired
+buffer are lost when this is done.
+
+\1f
+File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired
+
+Deleting Files With Dired
+-------------------------
+
+The primary use of Dired is to flag files for deletion and then delete
+them.
+
+`d'
+ Flag this file for deletion.
+
+`u'
+ Remove deletion-flag on this line.
+
+`<DEL>'
+ Remove deletion-flag on previous line, moving point to that line.
+
+`x'
+ Delete the files that are flagged for deletion.
+
+`#'
+ Flag all auto-save files (files whose names start and end with `#')
+ for deletion (*note Auto Save::).
+
+`~'
+ Flag all backup files (files whose names end with `~') for deletion
+ (*note Backup::).
+
+`. (Period)'
+ Flag excess numeric backup files for deletion. The oldest and
+ newest few backup files of any one file are exempt; the middle
+ ones are flagged.
+
+ You can flag a file for deletion by moving to the line describing the
+file and typing `d' or `C-d'. The deletion flag is visible as a `D' at
+the beginning of the line. Point is moved to the beginning of the next
+line, so that repeated `d' commands flag successive files.
+
+ The files are flagged for deletion rather than deleted immediately to
+avoid the danger of deleting a file accidentally. Until you direct
+Dired to delete the flagged files, you can remove deletion flags using
+the commands `u' and <DEL>. `u' works just like `d', but removes flags
+rather than making flags. <DEL> moves upward, removing flags; it is
+like `u' with numeric argument automatically negated.
+
+ To delete the flagged files, type `x'. This command first displays a
+list of all the file names flagged for deletion, and requests
+confirmation with `yes'. Once you confirm, all the flagged files are
+deleted, and their lines are deleted from the text of the Dired buffer.
+The shortened Dired buffer remains selected. If you answer `no' or
+quit with `C-g', you return immediately to Dired, with the deletion
+flags still present and no files actually deleted.
+
+ The `#', `~', and `.' commands flag many files for deletion, based
+on their names. These commands are useful precisely because they do
+not actually delete any files; you can remove the deletion flags from
+any flagged files that you really wish to keep.
+
+ `#' flags for deletion all files that appear to have been made by
+auto-saving (that is, files whose names begin and end with `#'). `~'
+flags for deletion all files that appear to have been made as backups
+for files that were edited (that is, files whose names end with `~').
+
+ `.' (Period) flags just some of the backup files for deletion: only
+numeric backups that are not among the oldest few nor the newest few
+backups of any one file. Normally `dired-kept-versions' (not
+`kept-new-versions'; that applies only when saving) specifies the
+number of newest versions of each file to keep, and `kept-old-versions'
+specifies the number of oldest versions to keep. Period with a
+positive numeric argument, as in `C-u 3 .', specifies the number of
+newest versions to keep, overriding `dired-kept-versions'. A negative
+numeric argument overrides `kept-old-versions', using minus the value
+of the argument to specify the number of oldest versions of each file
+to keep.
+
+\1f
+File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired
+
+Immediate File Operations in Dired
+----------------------------------
+
+Some file operations in Dired take place immediately when they are
+requested.
+
+`C'
+ Copies the file described on the current line. You must supply a
+ file name to copy to, using the minibuffer.
+
+`f'
+ Visits the file described on the current line. It is just like
+ typing `C-x C-f' and supplying that file name. If the file on
+ this line is a subdirectory, `f' actually causes Dired to be
+ invoked on that subdirectory. *Note Visiting::.
+
+`o'
+ Like `f', but uses another window to display the file's buffer.
+ The Dired buffer remains visible in the first window. This is
+ like using `C-x 4 C-f' to visit the file. *Note Windows::.
+
+`R'
+ Renames the file described on the current line. You must supply a
+ file name to rename to, using the minibuffer.
+
+`v'
+ Views the file described on this line using `M-x view-file'.
+ Viewing a file is like visiting it, but is slanted toward moving
+ around in the file conveniently and does not allow changing the
+ file. *Note View File: Misc File Ops. Viewing a file that is a
+ directory runs Dired on that directory.
+
+\1f
+File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files
+
+Miscellaneous File Operations
+=============================
+
+Emacs has commands for performing many other operations on files. All
+operate on one file; they do not accept wildcard file names.
+
+ You can use the command `M-x add-name-to-file' to add a name to an
+existing file without removing the old name. The new name must belong
+on the file system that the file is on.
+
+ `M-x append-to-file' adds the text of the region to the end of the
+specified file.
+
+ `M-x copy-file' reads the file OLD and writes a new file named NEW
+with the same contents. Confirmation is required if a file named NEW
+already exists, because copying overwrites the old contents of the file
+NEW.
+
+ `M-x delete-file' deletes a specified file, like the `rm' command in
+the shell. If you are deleting many files in one directory, it may be
+more convenient to use Dired (*note Dired::).
+
+ `M-x insert-file' inserts a copy of the contents of a specified file
+into the current buffer at point, leaving point unchanged before the
+contents and the mark after them. *Note Mark::.
+
+ `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and
+then creates a symbolic link named LINKNAME and pointing at OLD.
+Future attempts to open file LINKNAME will then refer to the file named
+OLD at the time the opening is done, or will result in an error if the
+name OLD is not in use at that time. Confirmation is required if you
+create the link while LINKNAME is in use. Note that not all systems
+support symbolic links.
+
+ `M-x rename-file' reads two file names OLD and NEW using the
+minibuffer, then renames file OLD as NEW. If a file named NEW already
+exists, you must confirm with `yes' or renaming is not done; this is
+because renaming causes the previous meaning of the name NEW to be
+lost. If OLD and NEW are on different file systems, the file OLD is
+copied and deleted.
+
+ `M-x view-file' allows you to scan or read a file by sequential
+screenfuls. It reads a file name argument using the minibuffer. After
+reading the file into an Emacs buffer, `view-file' reads and displays
+one windowful. You can then type <SPC> to scroll forward one window,
+or <DEL> to scroll backward. Various other commands are provided for
+moving around in the file, but none for changing it; type `C-h' while
+viewing a file for a list of them. Most commands are the default Emacs
+cursor motion commands. To exit from viewing, type `C-c'.
+
+\1f
+File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top
+
+Using Multiple Buffers
+**********************
+
+Text you are editing in Emacs resides in an object called a "buffer".
+Each time you visit a file, Emacs creates a buffer to hold the file's
+text. Each time you invoke Dired, Emacs creates a buffer to hold the
+directory listing. If you send a message with `C-x m', a buffer named
+`*mail*' is used to hold the text of the message. When you ask for a
+command's documentation, it appears in a buffer called `*Help*'.
+
+ At any time, one and only one buffer is "selected". It is also
+called the "current buffer". Saying a command operates on "the buffer"
+really means that the command operates on the selected buffer, as most
+commands do.
+
+ When Emacs creates multiple windows, each window has a chosen buffer
+which is displayed there, but at any time only one of the windows is
+selected and its chosen buffer is the selected buffer. Each window's
+mode line displays the name of the buffer the window is displaying
+(*note Windows::).
+
+ Each buffer has a name which can be of any length but is
+case-sensitive. You can select a buffer using its name. Most buffers
+are created when you visit files; their names are derived from the
+files' names. You can also create an empty buffer with any name you
+want. A newly started Emacs has a buffer named `*scratch*' which you
+can use for evaluating Lisp expressions in Emacs.
+
+ Each buffer records what file it is visiting, whether it is
+modified, and what major mode and minor modes are in effect in it
+(*note Major Modes::). Any Emacs variable can be made "local to" a
+particular buffer, meaning its value in that buffer can be different
+from the value in other buffers. *Note Locals::.
+
+* Menu:
+
+* Select Buffer:: Creating a new buffer or reselecting an old one.
+* List Buffers:: Getting a list of buffers that exist.
+* Misc Buffer:: Renaming; changing read-onliness; copying text.
+* Kill Buffer:: Killing buffers you no longer need.
+* Several Buffers:: How to go through the list of all buffers
+ and operate variously on several of them.
+
+\1f
+File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers
+
+Creating and Selecting Buffers
+==============================
+
+`C-x b BUFFER <RET>'
+ Select or create a buffer named BUFFER (`switch-to-buffer').
+
+`C-x 4 b BUFFER <RET>'
+ Similar, but select a buffer named BUFFER in another window
+ (`switch-to-buffer-other-window').
+
+`M-x switch-to-other-buffer N'
+ Switch to the previous buffer.
+
+ To select a buffer named BUFNAME, type `C-x b BUFNAME <RET>'. This
+is the command `switch-to-buffer' with argument BUFNAME. You can use
+completion on an abbreviation for the buffer name you want (*note
+Completion::). An empty argument to `C-x b' specifies the most
+recently selected buffer that is not displayed in any window.
+
+ Most buffers are created when you visit files, or use Emacs commands
+that display text. You can also create a buffer explicitly by typing
+`C-x b BUFNAME <RET>', which creates a new, empty buffer that is not
+visiting any file, and selects it for editing. The new buffer's major
+mode is determined by the value of `default-major-mode' (*note Major
+Modes::). Buffers not visiting files are usually used for making notes
+to yourself. If you try to save one, you are asked for the file name
+to use.
+
+ The function `switch-to-buffer-other-frame' is similar to
+`switch-to-buffer' except that it creates a new frame in which to
+display the selected buffer.
+
+ Use `M-x switch-to-other-buffer' to visit the previous buffer. If
+you supply a positive integer N, the Nth most recent buffer is
+displayed. If you supply an argument of 0, the current buffer is moved
+to the bottom of the buffer stack.
+
+ Note that you can also use `C-x C-f' and any other command for
+visiting a file to switch buffers. *Note Visiting::.
+
+\1f
+File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers
+
+Listing Existing Buffers
+========================
+
+`C-x C-b'
+ List the existing buffers (`list-buffers').
+
+ To print a list of all existing buffers, type `C-x C-b'. Each line
+in the list shows one buffer's name, major mode, and visited file. A
+`*' at the beginning of a line indicates the buffer has been
+"modified". If several buffers are modified, it may be time to save
+some with `C-x s' (*note Saving::). A `%' indicates a read-only
+buffer. A `.' marks the selected buffer. Here is an example of a
+buffer list:
+
+ MR Buffer Size Mode File
+ -- ------ ---- ---- ----
+ .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
+ *Help* 1287 Fundamental
+ files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
+ % RMAIL 64042 RMAIL /u/rms/RMAIL
+ *% man 747 Dired /u2/emacs/man/
+ net.emacs 343885 Fundamental /u/rms/net.emacs
+ fileio.c 27691 C /u2/emacs/src/fileio.c
+ NEWS 67340 Text /u2/emacs/etc/NEWS
+ *scratch* 0 Lisp Interaction
+
+Note that the buffer `*Help*' was made by a help request; it is not
+visiting any file. The buffer `man' was made by Dired on the directory
+`/u2/emacs/man/'.
+
+ As you move the mouse over the `*Buffer List*' buffer, the lines are
+highlighted. This visual cue indicates that clicking the right mouse
+button (`button3') will pop up a menu of commands on the buffer
+represented by this line. This menu duplicates most of those commands
+which are bound to keys in the `*Buffer List*' buffer.
+
+\1f
+File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers
+
+Miscellaneous Buffer Operations
+===============================
+
+`C-x C-q'
+ Toggle read-only status of buffer (`toggle-read-only').
+
+`M-x rename-buffer'
+ Change the name of the current buffer.
+
+`M-x view-buffer'
+ Scroll through a buffer.
+
+ A buffer can be "read-only", which means that commands to change its
+text are not allowed. Normally, read-only buffers are created by
+subsystems such as Dired and Rmail that have special commands to operate
+on the text. Emacs also creates a read-only buffer if you visit a file
+that is protected. To make changes in a read-only buffer, use the
+command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer
+writable, and makes a writable buffer read-only. This works by setting
+the variable `buffer-read-only', which has a local value in each buffer
+and makes a buffer read-only if its value is non-`nil'.
+
+ `M-x rename-buffer' changes the name of the current buffer,
+prompting for the new name in the minibuffer. There is no default. If
+you specify a name that is used by a different buffer, an error is
+signalled and renaming is not done.
+
+ `M-x view-buffer' is similar to `M-x view-file' (*note Misc File
+Ops::), but it examines an already existing Emacs buffer. View mode
+provides convenient commands for scrolling through the buffer but not
+for changing it. When you exit View mode, the resulting value of point
+remains in effect.
+
+ To copy text from one buffer to another, use the commands `M-x
+append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::.
+
+\1f
+File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers
+
+Killing Buffers
+===============
+
+After using Emacs for a while, you may accumulate a large number of
+buffers and may want to eliminate the ones you no longer need. There
+are several commands for doing this.
+
+`C-x k'
+ Kill a buffer, specified by name (`kill-buffer').
+
+`M-x kill-some-buffers'
+ Offer to kill each buffer, one by one.
+
+ `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
+the minibuffer. If you type just <RET> in the minibuffer, the default,
+killing the current buffer, is used. If the current buffer is killed,
+the buffer that has been selected recently but does not appear in any
+window now is selected. If the buffer being killed contains unsaved
+changes, you are asked to confirm with `yes' before the buffer is
+killed.
+
+ The command `M-x kill-some-buffers' asks about each buffer, one by
+one. An answer of `y' means to kill the buffer. Killing the current
+buffer or a buffer containing unsaved changes selects a new buffer or
+asks for confirmation just like `kill-buffer'.
+
+\1f
+File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers
+
+Operating on Several Buffers
+============================
+
+The "buffer-menu" facility is like a "Dired for buffers"; it allows you
+to request operations on various Emacs buffers by editing a buffer
+containing a list of them. You can save buffers, kill them (here
+called "deleting" them, for consistency with Dired), or display them.
+
+`M-x buffer-menu'
+ Begin editing a buffer listing all Emacs buffers.
+
+ The command `buffer-menu' writes a list of all Emacs buffers into
+the buffer `*Buffer List*', and selects that buffer in Buffer Menu
+mode. The buffer is read-only. You can only change it using the
+special commands described in this section. Most of the commands are
+graphic characters. You can use Emacs cursor motion commands in the
+`*Buffer List*' buffer. If the cursor is on a line describing a
+buffer, the following special commands apply to that buffer:
+
+`d'
+ Request to delete (kill) the buffer, then move down. A `D' before
+ the buffer name on a line indicates a deletion request. Requested
+ deletions actually take place when you use the `x' command.
+
+`k'
+ Synonym for `d'.
+
+`C-d'
+ Like `d' but move up afterwards instead of down.
+
+`s'
+ Request to save the buffer. An `S' before the buffer name on a
+ line indicates the request. Requested saves actually take place
+ when you use the `x' command. You can request both saving and
+ deletion for the same buffer.
+
+`~'
+ Mark buffer "unmodified". The command `~' does this immediately
+ when typed.
+
+`x'
+ Perform previously requested deletions and saves.
+
+`u'
+ Remove any request made for the current line, and move down.
+
+`<DEL>'
+ Move to previous line and remove any request made for that line.
+
+ All commands that add or remove flags to request later operations
+also move down a line. They accept a numeric argument as a repeat
+count, unless otherwise specified.
+
+ There are also special commands to use the buffer list to select
+another buffer, and to specify one or more other buffers for display in
+additional windows.
+
+`1'
+ Select the buffer in a full-frame window. This command takes
+ effect immediately.
+
+`2'
+ Immediately set up two windows, with this buffer in one and the
+ buffer selected before `*Buffer List*' in the other.
+
+`f'
+ Immediately select the buffer in place of the `*Buffer List*'
+ buffer.
+
+`o'
+ Immediately select the buffer in another window as if by `C-x 4 b',
+ leaving `*Buffer List*' visible.
+
+`q'
+ Immediately select this buffer, and display any buffers previously
+ flagged with the `m' command in other windows. If there are no
+ buffers flagged with `m', this command is equivalent to `1'.
+
+`m'
+ Flag this buffer to be displayed in another window if the `q'
+ command is used. The request shows as a `>' at the beginning of
+ the line. The same buffer may not have both a delete request and a
+ display request.
+
+ Going back between a `buffer-menu' buffer and other Emacs buffers is
+easy. You can, for example, switch from the `*Buffer List*' buffer to
+another Emacs buffer, and edit there. You can then reselect the
+`buffer-menu' buffer and perform operations already requested, or you
+can kill that buffer or pay no further attention to it. All that
+`buffer-menu' does directly is create and select a suitable buffer, and
+turn on Buffer Menu mode. All the other capabilities of the buffer
+menu are implemented by special commands provided in Buffer Menu mode.
+
+ The only difference between `buffer-menu' and `list-buffers' is that
+`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers'
+does not. If you run `list-buffers' (that is, type `C-x C-b') and
+select the buffer list manually, you can use all the commands described
+here.
+
+\1f
+File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top
+
+Multiple Windows
+****************
+
+Emacs can split the frame into two or many windows, which can display
+parts of different buffers or different parts of one buffer. If you are
+running XEmacs under X, that means you can have the X window that
+contains the Emacs frame have multiple subwindows.
+
+* Menu:
+
+* Basic Window:: Introduction to Emacs windows.
+* Split Window:: New windows are made by splitting existing windows.
+* Other Window:: Moving to another window or doing something to it.
+* Pop Up Window:: Finding a file or buffer in another window.
+* Change Window:: Deleting windows and changing their sizes.
+
+\1f
+File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows
+
+Concepts of Emacs Windows
+=========================
+
+When Emacs displays multiple windows, each window has one Emacs buffer
+designated for display. The same buffer may appear in more than one
+window; if it does, any changes in its text are displayed in all the
+windows that display it. Windows showing the same buffer can show
+different parts of it, because each window has its own value of point.
+
+ At any time, one window is the "selected window"; the buffer
+displayed by that window is the current buffer. The cursor shows the
+location of point in that window. Each other window has a location of
+point as well, but since the terminal has only one cursor, it cannot
+show the location of point in the other windows.
+
+ Commands to move point affect the value of point for the selected
+Emacs window only. They do not change the value of point in any other
+Emacs window, including those showing the same buffer. The same is
+true for commands such as `C-x b' to change the selected buffer in the
+selected window; they do not affect other windows at all. However,
+there are other commands such as `C-x 4 b' that select a different
+window and switch buffers in it. Also, all commands that display
+information in a window, including (for example) `C-h f'
+(`describe-function') and `C-x C-b' (`list-buffers'), work by switching
+buffers in a non-selected window without affecting the selected window.
+
+ Each window has its own mode line, which displays the buffer name,
+modification status, and major and minor modes of the buffer that is
+displayed in the window. *Note Mode Line::, for details on the mode
+line.
+
+\1f
+File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows
+
+Splitting Windows
+=================
+
+`C-x 2'
+ Split the selected window into two windows, one above the other
+ (`split-window-vertically').
+
+`C-x 3'
+ Split the selected window into two windows positioned side by side
+ (`split-window-horizontally').
+
+`C-x 6'
+ Save the current window configuration in register REG (a letter).
+
+`C-x 7'
+ Restore (make current) the window configuration in register REG (a
+ letter). Use with a register previously set with `C-x 6'.
+
+ The command `C-x 2' (`split-window-vertically') breaks the selected
+window into two windows, one above the other. Both windows start out
+displaying the same buffer, with the same value of point. By default
+each of the two windows gets half the height of the window that was
+split. A numeric argument specifies how many lines to give to the top
+window.
+
+ `C-x 3' (`split-window-horizontally') breaks the selected window
+into two side-by-side windows. A numeric argument specifies how many
+columns to give the one on the left. A line of vertical bars separates
+the two windows. Windows that are not the full width of the frame have
+truncated mode lines which do not always appear in inverse video,
+because Emacs display routines cannot display a region of inverse video
+that is only part of a line on the screen.
+
+ When a window is less than the full width, many text lines are too
+long to fit. Continuing all those lines might be confusing. Set the
+variable `truncate-partial-width-windows' to non-`nil' to force
+truncation in all windows less than the full width of the frame,
+independent of the buffer and its value for `truncate-lines'. *Note
+Continuation Lines::.
+
+ Horizontal scrolling is often used in side-by-side windows. *Note
+Display::.
+
+ You can resize a window and store that configuration in a register by
+supplying a REGISTER argument to `window-configuration-to-register'
+(`C-x 6'). To return to the window configuration established with
+`window-configuration-to-register', use `jump-to-register' (`C-x j').
+
+\1f
+File: xemacs.info, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows
+
+Using Other Windows
+===================
+
+`C-x o'
+ Select another window (`other-window'). That is the letter `o',
+ not zero.
+
+`M-C-v'
+ Scroll the next window (`scroll-other-window').
+
+`M-x compare-windows'
+ Find the next place where the text in the selected window does not
+ match the text in the next window.
+
+`M-x other-window-any-frame N'
+ Select the Nth different window on any frame.
+
+ To select a different window, use `C-x o' (`other-window'). That is
+an `o', for `other', not a zero. When there are more than two windows,
+the command moves through all the windows in a cyclic order, generally
+top to bottom and left to right. From the rightmost and bottommost
+window, it goes back to the one at the upper left corner. A numeric
+argument, N, moves several steps in the cyclic order of windows. A
+negative numeric argument moves around the cycle in the opposite order.
+If the optional second argument WHICH-FRAMES is non-`nil', the
+function cycles through all frames. When the minibuffer is active, the
+minibuffer is the last window in the cycle; you can switch from the
+minibuffer window to one of the other windows, and later switch back
+and finish supplying the minibuffer argument that is requested. *Note
+Minibuffer Edit::.
+
+ The command `M-x other-window-any-frame' also selects the window N
+steps away in the cyclic order. However, unlike `other-window', this
+command selects a window on the next or previous frame instead of
+wrapping around to the top or bottom of the current frame, when there
+are no more windows.
+
+ The usual scrolling commands (*note Display::) apply to the selected
+window only. `M-C-v' (`scroll-other-window') scrolls the window that
+`C-x o' would select. Like `C-v', it takes positive and negative
+arguments.
+
+ The command `M-x compare-windows' compares the text in the current
+window with the text in the next window. Comparison starts at point in
+each window. Point moves forward in each window, a character at a time,
+until the next set of characters in the two windows are different.
+Then the command is finished.
+
+ A prefix argument IGNORE-WHITESPACE means ignore changes in
+whitespace. The variable `compare-windows-whitespace' controls how
+whitespace is skipped.
+
+ If `compare-ignore-case' is non-`nil', changes in case are also
+ignored.
+
+\1f
+File: xemacs.info, Node: Pop Up Window, Next: Change Window, Prev: Other Window, Up: Windows
+
+Displaying in Another Window
+============================
+
+`C-x 4' is a prefix key for commands that select another window
+(splitting the window if there is only one) and select a buffer in that
+window. Different `C-x 4' commands have different ways of finding the
+buffer to select.
+
+`C-x 4 b BUFNAME <RET>'
+ Select buffer BUFNAME in another window. This runs
+ `switch-to-buffer-other-window'.
+
+`C-x 4 f FILENAME <RET>'
+ Visit file FILENAME and select its buffer in another window. This
+ runs `find-file-other-window'. *Note Visiting::.
+
+`C-x 4 d DIRECTORY <RET>'
+ Select a Dired buffer for directory DIRECTORY in another window.
+ This runs `dired-other-window'. *Note Dired::.
+
+`C-x 4 m'
+ Start composing a mail message in another window. This runs
+ `mail-other-window', and its same-window version is `C-x m' (*note
+ Sending Mail::).
+
+`C-x 4 .'
+ Find a tag in the current tag table in another window. This runs
+ `find-tag-other-window', the multiple-window variant of `M-.'
+ (*note Tags::).
+
+ If the variable `display-buffer-function' is non-`nil', its value is
+the function to call to handle `display-buffer'. It receives two
+arguments, the buffer and a flag that if non-`nil' means that the
+currently selected window is not acceptable. Commands such as
+`switch-to-buffer-other-window' and `find-file-other-window' work using
+this function.
+
+\1f
+File: xemacs.info, Node: Change Window, Prev: Pop Up Window, Up: Windows
+
+Deleting and Rearranging Windows
+================================
+
+`C-x 0'
+ Get rid of the selected window (`delete-window'). That is a zero.
+ If there is more than one Emacs frame, deleting the sole remaining
+ window on that frame deletes the frame as well. If the current
+ frame is the only frame, it is not deleted.
+
+`C-x 1'
+ Get rid of all windows except the selected one
+ (`delete-other-windows').
+
+`C-x ^'
+ Make the selected window taller, at the expense of the other(s)
+ (`enlarge-window').
+
+`C-x }'
+ Make the selected window wider (`enlarge-window-horizontally').
+
+ To delete a window, type `C-x 0' (`delete-window'). (That is a
+zero.) The space occupied by the deleted window is distributed among
+the other active windows (but not the minibuffer window, even if that
+is active at the time). Once a window is deleted, its attributes are
+forgotten; there is no automatic way to make another window of the same
+shape or showing the same buffer. The buffer continues to exist, and
+you can select it in any window with `C-x b'.
+
+ `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
+deletes all the windows except the selected one (and the minibuffer).
+The selected window expands to use the whole frame except for the echo
+area.
+
+ To readjust the division of space among existing windows, use `C-x
+^' (`enlarge-window'). It makes the currently selected window longer
+by one line or as many lines as a numeric argument specifies. With a
+negative argument, it makes the selected window smaller. `C-x }'
+(`enlarge-window-horizontally') makes the selected window wider by the
+specified number of columns. The extra screen space given to a window
+comes from one of its neighbors, if that is possible; otherwise, all
+the competing windows are shrunk in the same proportion. If this makes
+some windows too small, those windows are deleted and their space is
+divided up. Minimum window size is specified by the variables
+`window-min-height' and `window-min-width'.
+
+ You can also resize windows within a frame by clicking the left mouse
+button on a modeline, and dragging.
+
+ Clicking the right button on a mode line pops up a menu of common
+window manager operations. This menu contains the following options:
+
+Delete Window
+ Remove the window above this modeline from the frame.
+
+Delete Other Windows
+ Delete all windows on the frame except for the one above this
+ modeline.
+
+Split Window
+ Split the window above the mode line in half, creating another
+ window.
+
+Split Window Horizontally
+ Split the window above the mode line in half horizontally, so that
+ there will be two windows side-by-side.
+
+Balance Windows
+ Readjust the sizes of all windows on the frame until all windows
+ have roughly the same number of lines.
+
+\1f
+File: xemacs.info, Node: Mule, Next: Major Modes, Prev: Windows, Up: Top
+
+World Scripts Support
+*********************
+
+If you compile XEmacs with Mule option, it supports a wide variety of
+world scripts, including Latin script, as well as Arabic script,
+Simplified Chinese script (for mainland of China), Traditional Chinese
+script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA
+symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts
+(Hangul and Hanja) and Cyrillic script (for Byelorussian, Bulgarian,
+Russian, Serbian and Ukrainian). These features have been merged from
+the modified version of Emacs known as MULE (for "MULti-lingual
+Enhancement to GNU Emacs").
+
+* Menu:
+
+* Mule Intro:: Basic concepts of Mule.
+* Language Environments:: Setting things up for the language you use.
+* Input Methods:: Entering text characters not on your keyboard.
+* Select Input Method:: Specifying your choice of input methods.
+* Mule and Fonts:: Additional font-related issues
+* Coding Systems:: Character set conversion when you read and
+ write files, and so on.
+* Recognize Coding:: How XEmacs figures out which conversion to use.
+* Specify Coding:: Various ways to choose which conversion to use.
+
+\1f
+File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
+
+What is Mule?
=============
- Each text window's last line is a "mode line" which describes what is
-going on in that window. When there is only one text window, the mode
-line appears right above the echo area. The mode line is in inverse
-video if the terminal supports that, starts and ends with dashes, and
-contains text like `XEmacs: SOMETHING'.
-
- If a mode line has something else in place of `XEmacs: SOMETHING',
-the window above it is in a special subsystem such as Dired. The mode
-line then indicates the status of the subsystem.
-
- Normally, the mode line has the following appearance:
-
- --CH-XEmacs: BUF (MAJOR MINOR)----POS------
-
-This gives information about the buffer being displayed in the window:
-the buffer's name, what major and minor modes are in use, whether the
-buffer's text has been changed, and how far down the buffer you are
-currently looking.
-
- CH contains two stars (`**') if the text in the buffer has been
-edited (the buffer is "modified"), or two dashes (`--') if the buffer
-has not been edited. Exception: for a read-only buffer, it is `%%'.
-
- BUF is the name of the window's chosen "buffer". The chosen buffer
-in the selected window (the window that the cursor is in) is also
-XEmacs's selected buffer, the buffer in which editing takes place. When
-we speak of what some command does to "the buffer", we mean the
-currently selected buffer. *Note Buffers::.
-
- POS tells you whether there is additional text above the top of the
-screen or below the bottom. If your file is small and it is completely
-visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
-are looking at the beginning of the file, `Bot' if you are looking at
-the end of the file, or `NN%', where NN is the percentage of the file
-above the top of the screen.
-
- MAJOR is the name of the "major mode" in effect in the buffer. At
-any time, each buffer is in one and only one major mode. The available
-major modes include Fundamental mode (the least specialized), Text
-mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
-the modes differ and how you select one.
-
- MINOR is a list of some of the "minor modes" that are turned on in
-the window's chosen buffer. For example, `Fill' means that Auto Fill
-mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
-that Overwrite mode is on. *Note Minor Modes::, for more information.
-`Narrow' means that the buffer being displayed has editing restricted
-to only a portion of its text. This is not really a minor mode, but is
-like one. *Note Narrowing::. `Def' means that a keyboard macro is
-being defined. *Note Keyboard Macros::.
-
- Some buffers display additional information after the minor modes.
-For example, Rmail buffers display the current message number and the
-total number of messages. Compilation buffers and Shell mode display
-the status of the subprocess.
-
- If XEmacs is currently inside a recursive editing level, square
-brackets (`[...]') appear around the parentheses that surround the
-modes. If XEmacs is in one recursive editing level within another,
-double square brackets appear, and so on. Since information on
-recursive editing applies to XEmacs in general and not to any one
-buffer, the square brackets appear in every mode line on the screen or
-not in any of them. *Note Recursive Edit::.
-
- XEmacs can optionally display the time and system load in all mode
-lines. To enable this feature, type `M-x display-time'. The
-information added to the mode line usually appears after the file name,
-before the mode names and their parentheses. It looks like this:
-
- HH:MMpm L.LL [D]
-
-(Some fields may be missing if your operating system cannot support
-them.) HH and MM are the hour and minute, followed always by `am' or
-`pm'. L.LL is the average number of running processes in the whole
-system recently. D is an approximate index of the ratio of disk
-activity to CPU activity for all users.
-
- The word `Mail' appears after the load level if there is mail for
-you that you have not read yet.
-
- Customization note: the variable `mode-line-inverse-video' controls
-whether the mode line is displayed in inverse video (assuming the
-terminal supports it); `nil' means no inverse video. The default is
-`t'. For X frames, simply set the foreground and background colors
-appropriately.
-
-\1f
-File: xemacs.info, Node: XEmacs under X, Prev: Mode Line, Up: Frame
-
-Using XEmacs Under the X Window System
-======================================
+Mule is the MUltiLingual Extension to XEmacs. It provides facilities
+not only for handling text written in many different languages, but in
+fact multilingual texts containing several languages in the same buffer.
+This goes beyond the simple facilities offered by Unicode for
+representation of multilingual text. Mule also supports input methods,
+composing display using fonts in various different encodings, changing
+character syntax and other editing facilities to correspond to local
+language usage, and more.
+
+ The most obvious problem is that of the different character coding
+systems used by different languages. ASCII supplies all the characters
+needed for most computer programming languages and US English (it lacks
+the currency symbol for British English), but other Western European
+languages (French, Spanish, German) require more than 96 code positions
+for accented characters. In fact, even with 8 bits to represent 96 more
+character (including accented characters and symbols such as currency
+symbols), some languages' alphabets remain incomplete (Croatian,
+Polish). (The 64 "missing characters" are reserved for control
+characters.) Furthermore, many European languages have their own
+alphabets, which must conflict with the accented characters since the
+ASCII characters are needed for computer interaction (error and log
+messages are typically in ASCII).
+
+ For economy of space, historical practice has been for each language
+to establish its own encoding for the characters it needs. This allows
+most European languages to represented with one octet (byte) per
+character. However, many Asian languages have thousands of characters
+and require two or more octets per character. For multilingual
+purposes, the ISO 2022 standard establishes escape codes that allow
+switching encodings in midstream. (It's also ISO 2022 that establishes
+the standard that code points 0-31 and 128-159 are control codes.)
+
+ However, this is error-prone and complex for internal processing.
+For this reason XEmacs uses an internal coding system which can encode
+all of the world's scripts. Unfortunately, for historical reasons, this
+code is not Unicode, although we are moving in that direction.
+
+ XEmacs translates between the internal character encoding and various
+other coding systems when reading and writing files, when exchanging
+data with subprocesses, and (in some cases) in the `C-q' command (see
+below). The internal encoding is never visible to the user in a
+production XEmacs, but unfortunately the process cannot be completely
+transparent to the user. This is because the same ranges of octets may
+represent 1-octet ISO-8859-1 (which is satisfactory for most Western
+European use prior to the introduction of the Euro currency), 1-octet
+ISO-8859-15 (which substitutes the Euro for the rarely used "generic
+currency" symbol), 1-octet ISO-8859-5 (Cyrillic), or multioctet EUC-JP
+(Japanese). There's no way to tell without being able to read!
+
+ A number of heuristics are incorporated in Mule for automatic
+recognition, there are facilities for the user to set defaults, and
+where necessary (rarely, we hope) to set coding systems directly.
+
+ The command `C-h h' (`view-hello-file') displays the file
+`etc/HELLO', which shows how to say "hello" in many languages. This
+illustrates various scripts.
+
+ Keyboards, even in the countries where these character sets are used,
+generally don't have keys for all the characters in them. So XEmacs
+supports various "input methods", typically one for each script or
+language, to make it convenient to type them.
+
+ The prefix key `C-x <RET>' is used for commands that pertain to
+world scripts, coding systems, and input methods.
+
+\1f
+File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule
+
+Language Environments
+=====================
+
+All supported character sets are supported in XEmacs buffers if it is
+compiled with Mule; there is no need to select a particular language in
+order to display its characters in an XEmacs buffer. However, it is
+important to select a "language environment" in order to set various
+defaults. The language environment really represents a choice of
+preferred script (more or less) rather that a choice of language.
+
+ The language environment controls which coding systems to recognize
+when reading text (*note Recognize Coding::). This applies to files,
+incoming mail, netnews, and any other text you read into XEmacs. It may
+also specify the default coding system to use when you create a file.
+Each language environment also specifies a default input method.
+
+ The command to select a language environment is `M-x
+set-language-environment'. It makes no difference which buffer is
+current when you use this command, because the effects apply globally to
+the XEmacs session. The supported language environments include:
+
+ ASCII, Chinese-BIG5, Chinese-GB, Croatian, Cyrillic-ALT,
+ Cyrillic-ISO, Cyrillic-KOI8, Cyrillic-Win, Czech, English,
+ Ethiopic, French, German, Greek, Hebrew, IPA, Japanese, Korean,
+ Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Norwegian, Polish,
+ Romanian, Slovenian, Thai-XTIS, Vietnamese.
+
+ Some operating systems let you specify the language you are using by
+setting locale environment variables. XEmacs handles one common special
+case of this: if your locale name for character types contains the
+string `8859-N', XEmacs automatically selects the corresponding
+language environment.
+
+ To display information about the effects of a certain language
+environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
+(`describe-language-environment'). This tells you which languages this
+language environment is useful for, and lists the character sets,
+coding systems, and input methods that go with it. It also shows some
+sample text to illustrate scripts used in this language environment.
+By default, this command describes the chosen language environment.
+
+\1f
+File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule
+
+Input Methods
+=============
+
+An "input method" is a kind of character conversion designed
+specifically for interactive input. In XEmacs, typically each language
+has its own input method; sometimes several languages which use the same
+characters can share one input method. A few languages support several
+input methods.
+
+ The simplest kind of input method works by mapping ASCII letters into
+another alphabet. This is how the Greek and Russian input methods work.
+
+ A more powerful technique is composition: converting sequences of
+characters into one letter. Many European input methods use composition
+to produce a single non-ASCII letter from a sequence that consists of a
+letter followed by accent characters. For example, some methods convert
+the sequence `'a' into a single accented letter.
+
+ The input methods for syllabic scripts typically use mapping followed
+by composition. The input methods for Thai and Korean work this way.
+First, letters are mapped into symbols for particular sounds or tone
+marks; then, sequences of these which make up a whole syllable are
+mapped into one syllable sign.
+
+ Chinese and Japanese require more complex methods. In Chinese input
+methods, first you enter the phonetic spelling of a Chinese word (in
+input method `chinese-py', among others), or a sequence of portions of
+the character (input methods `chinese-4corner' and `chinese-sw', and
+others). Since one phonetic spelling typically corresponds to many
+different Chinese characters, you must select one of the alternatives
+using special XEmacs commands. Keys such as `C-f', `C-b', `C-n',
+`C-p', and digits have special definitions in this situation, used for
+selecting among the alternatives. <TAB> displays a buffer showing all
+the possibilities.
+
+ In Japanese input methods, first you input a whole word using
+phonetic spelling; then, after the word is in the buffer, XEmacs
+converts it into one or more characters using a large dictionary. One
+phonetic spelling corresponds to many differently written Japanese
+words, so you must select one of them; use `C-n' and `C-p' to cycle
+through the alternatives.
+
+ Sometimes it is useful to cut off input method processing so that the
+characters you have just entered will not combine with subsequent
+characters. For example, in input method `latin-1-postfix', the
+sequence `e '' combines to form an `e' with an accent. What if you
+want to enter them as separate characters?
+
+ One way is to type the accent twice; that is a special feature for
+entering the separate letter and accent. For example, `e ' '' gives
+you the two characters `e''. Another way is to type another letter
+after the `e'--something that won't combine with that--and immediately
+delete it. For example, you could type `e e <DEL> '' to get separate
+`e' and `''.
+
+ Another method, more general but not quite as easy to type, is to use
+`C-\ C-\' between two characters to stop them from combining. This is
+the command `C-\' (`toggle-input-method') used twice. *Note Select
+Input Method::.
+
+ `C-\ C-\' is especially useful inside an incremental search, because
+stops waiting for more characters to combine, and starts searching for
+what you have already entered.
+
+ The variables `input-method-highlight-flag' and
+`input-method-verbose-flag' control how input methods explain what is
+happening. If `input-method-highlight-flag' is non-`nil', the partial
+sequence is highlighted in the buffer. If `input-method-verbose-flag'
+is non-`nil', the list of possible characters to type next is displayed
+in the echo area (but not when you are in the minibuffer).
+
+\1f
+File: xemacs.info, Node: Select Input Method, Next: Mule and Fonts, Prev: Input Methods, Up: Mule
+
+Selecting an Input Method
+=========================
+
+`C-\'
+ Enable or disable use of the selected input method.
+
+`C-x <RET> C-\ METHOD <RET>'
+ Select a new input method for the current buffer.
+
+`C-h I METHOD <RET>'
+`C-h C-\ METHOD <RET>'
+ Describe the input method METHOD (`describe-input-method'). By
+ default, it describes the current input method (if any).
+
+`M-x list-input-methods'
+ Display a list of all the supported input methods.
+
+ To choose an input method for the current buffer, use `C-x <RET>
+C-\' (`select-input-method'). This command reads the input method name
+with the minibuffer; the name normally starts with the language
+environment that it is meant to be used with. The variable
+`current-input-method' records which input method is selected.
+
+ Input methods use various sequences of ASCII characters to stand for
+non-ASCII characters. Sometimes it is useful to turn off the input
+method temporarily. To do this, type `C-\' (`toggle-input-method').
+To reenable the input method, type `C-\' again.
+
+ If you type `C-\' and you have not yet selected an input method, it
+prompts for you to specify one. This has the same effect as using `C-x
+<RET> C-\' to specify an input method.
+
+ Selecting a language environment specifies a default input method for
+use in various buffers. When you have a default input method, you can
+select it in the current buffer by typing `C-\'. The variable
+`default-input-method' specifies the default input method (`nil' means
+there is none).
+
+ Some input methods for alphabetic scripts work by (in effect)
+remapping the keyboard to emulate various keyboard layouts commonly used
+for those scripts. How to do this remapping properly depends on your
+actual keyboard layout. To specify which layout your keyboard has, use
+the command `M-x quail-set-keyboard-layout'.
+
+ To display a list of all the supported input methods, type `M-x
+list-input-methods'. The list gives information about each input
+method, including the string that stands for it in the mode line.
+
+\1f
+File: xemacs.info, Node: Mule and Fonts, Next: Coding Systems, Prev: Select Input Method, Up: Mule
+
+Mule and Fonts
+==============
+
+(This section is X11-specific.)
+
+ Text in XEmacs buffers is displayed using various faces. In
+addition to specifying properties of a face, such as font and color,
+there are some additional properties of Mule charsets that are used in
+text.
+
+ There is currently two properties of a charset that could be
+adjusted by user: font registry and so called "ccl-program".
+
+ Font registry is a regular expression matching the font registry
+field for this character set. For example, both the `ascii' and
+`latin-iso8859-1' charsets use the registry `"ISO8859-1"'. This field
+is used to choose an appropriate font when the user gives a general
+font specification such as `-*-courier-medium-r-*-140-*', i.e. a
+14-point upright medium-weight Courier font.
+
+ You can set font registry for a charset using `set-charset-registry'
+function in one of your startup files. This function takes two
+arguments: character set (as a symbol) and font registry (as a string).
+
+ E. g., for Cyrillic texts Mule uses `cyrillic-iso8859-5' charset
+with `"ISO8859-5"' as a default registry, and we want to use `"koi8-r"'
+instead, because fonts in that encoding are installed on our system.
+Use:
+
+ (set-charset-registry 'cyrillic-iso8859-5 "koi8-r")
+
+ (Please note that you probably also want to set font registry for
+`ascii' charset so that mixed English/Cyrillic texts be displayed using
+the same font.)
+
+ "CCL-programs" are a little special-purpose scripts defined within
+XEmacs or in some package. Those scripts allow XEmacs to use fonts that
+are in different encoding from the encoding that is used by Mule for
+text in buffer. Returning to the above example, we need to somehow tell
+XEmacs that we have different encodings of fonts and text and so it
+needs to convert characters between those encodings when displaying.
+That's what `set-charset-ccl-program' function is used for. There are
+quite a few various CCL programs defined within XEmacs, and there is no
+comprehensive list of them, so you currently have to consult sources.
+
+ We know that there is a CCL program called `ccl-encode-koi8-r-font'
+that is used exactly for needed purpose: to convert characters between
+`ISO8859-5' encoding and `koi8-r'. Use:
+
+ (set-charset-ccl-program 'cyrillic-iso8859-5 'ccl-encode-koi8-r-font)
+
+ There are several more uses for CCL programs, not related to fonts,
+but those uses are not described here.
+
+\1f
+File: xemacs.info, Node: Coding Systems, Next: Recognize Coding, Prev: Mule and Fonts, Up: Mule
+
+Coding Systems
+==============
+
+Users of various languages have established many more-or-less standard
+coding systems for representing them. XEmacs does not use these coding
+systems internally; instead, it converts from various coding systems to
+its own system when reading data, and converts the internal coding
+system to other coding systems when writing data. Conversion is
+possible in reading or writing files, in sending or receiving from the
+terminal, and in exchanging data with subprocesses.
+
+ XEmacs assigns a name to each coding system. Most coding systems are
+used for one language, and the name of the coding system starts with the
+language name. Some coding systems are used for several languages;
+their names usually start with `iso'. There are also special coding
+systems `binary' and `no-conversion' which do not convert printing
+characters at all.
+
+ In addition to converting various representations of non-ASCII
+characters, a coding system can perform end-of-line conversion. XEmacs
+handles three different conventions for how to separate lines in a file:
+newline, carriage-return linefeed, and just carriage-return.
+
+`C-h C CODING <RET>'
+ Describe coding system CODING.
+
+`C-h C <RET>'
+ Describe the coding systems currently in use.
+
+`M-x list-coding-systems'
+ Display a list of all the supported coding systems.
+
+`C-u M-x list-coding-systems'
+ Display comprehensive list of specific details of all supported
+ coding systems.
+
+ The command `C-x RET C' (`describe-coding-system') displays
+information about particular coding systems. You can specify a coding
+system name as argument; alternatively, with an empty argument, it
+describes the coding systems currently selected for various purposes,
+both in the current buffer and as the defaults, and the priority list
+for recognizing coding systems (*note Recognize Coding::).
+
+ To display a list of all the supported coding systems, type `M-x
+list-coding-systems'. The list gives information about each coding
+system, including the letter that stands for it in the mode line (*note
+Mode Line::).
+
+ Each of the coding systems that appear in this list--except for
+`binary', which means no conversion of any kind--specifies how and
+whether to convert printing characters, but leaves the choice of
+end-of-line conversion to be decided based on the contents of each file.
+For example, if the file appears to use carriage-return linefeed between
+lines, that end-of-line conversion will be used.
+
+ Each of the listed coding systems has three variants which specify
+exactly what to do for end-of-line conversion:
+
+`...-unix'
+ Don't do any end-of-line conversion; assume the file uses newline
+ to separate lines. (This is the convention normally used on Unix
+ and GNU systems.)
+
+`...-dos'
+ Assume the file uses carriage-return linefeed to separate lines,
+ and do the appropriate conversion. (This is the convention
+ normally used on Microsoft systems.)
+
+`...-mac'
+ Assume the file uses carriage-return to separate lines, and do the
+ appropriate conversion. (This is the convention normally used on
+ the Macintosh system.)
+
+ These variant coding systems are omitted from the
+`list-coding-systems' display for brevity, since they are entirely
+predictable. For example, the coding system `iso-8859-1' has variants
+`iso-8859-1-unix', `iso-8859-1-dos' and `iso-8859-1-mac'.
+
+ In contrast, the coding system `binary' specifies no character code
+conversion at all--none for non-Latin-1 byte values and none for end of
+line. This is useful for reading or writing binary files, tar files,
+and other files that must be examined verbatim.
+
+ The easiest way to edit a file with no conversion of any kind is with
+the `M-x find-file-literally' command. This uses `binary', and also
+suppresses other XEmacs features that might convert the file contents
+before you see them. *Note Visiting::.
+
+ The coding system `no-conversion' means that the file contains
+non-Latin-1 characters stored with the internal XEmacs encoding. It
+handles end-of-line conversion based on the data encountered, and has
+the usual three variants to specify the kind of end-of-line conversion.
+
+\1f
+File: xemacs.info, Node: Recognize Coding, Next: Specify Coding, Prev: Coding Systems, Up: Mule
+
+Recognizing Coding Systems
+==========================
+
+Most of the time, XEmacs can recognize which coding system to use for
+any given file-once you have specified your preferences.
+
+ Some coding systems can be recognized or distinguished by which byte
+sequences appear in the data. However, there are coding systems that
+cannot be distinguished, not even potentially. For example, there is no
+way to distinguish between Latin-1 and Latin-2; they use the same byte
+values with different meanings.
+
+ XEmacs handles this situation by means of a priority list of coding
+systems. Whenever XEmacs reads a file, if you do not specify the coding
+system to use, XEmacs checks the data against each coding system,
+starting with the first in priority and working down the list, until it
+finds a coding system that fits the data. Then it converts the file
+contents assuming that they are represented in this coding system.
+
+ The priority list of coding systems depends on the selected language
+environment (*note Language Environments::). For example, if you use
+French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
+use Czech, you probably want Latin-2 to be preferred. This is one of
+the reasons to specify a language environment.
+
+ However, you can alter the priority list in detail with the command
+`M-x prefer-coding-system'. This command reads the name of a coding
+system from the minibuffer, and adds it to the front of the priority
+list, so that it is preferred to all others. If you use this command
+several times, each use adds one element to the front of the priority
+list.
+
+ Sometimes a file name indicates which coding system to use for the
+file. The variable `file-coding-system-alist' specifies this
+correspondence. There is a special function
+`modify-coding-system-alist' for adding elements to this list. For
+example, to read and write all `.txt' using the coding system
+`china-iso-8bit', you can execute this Lisp expression:
+
+ (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
+
+The first argument should be `file', the second argument should be a
+regular expression that determines which files this applies to, and the
+third argument says which coding system to use for these files.
+
+ You can specify the coding system for a particular file using the
+`-*-...-*-' construct at the beginning of a file, or a local variables
+list at the end (*note File Variables::). You do this by defining a
+value for the "variable" named `coding'. XEmacs does not really have a
+variable `coding'; instead of setting a variable, it uses the specified
+coding system for the file. For example, `-*-mode: C; coding:
+iso-8859-1;-*-' specifies use of the iso-8859-1 coding system, as well
+as C mode.
+
+ Once XEmacs has chosen a coding system for a buffer, it stores that
+coding system in `buffer-file-coding-system' and uses that coding
+system, by default, for operations that write from this buffer into a
+file. This includes the commands `save-buffer' and `write-region'. If
+you want to write files from this buffer using a different coding
+system, you can specify a different coding system for the buffer using
+`set-buffer-file-coding-system' (*note Specify Coding::).
+
+\1f
+File: xemacs.info, Node: Specify Coding, Prev: Recognize Coding, Up: Mule
+
+Specifying a Coding System
+==========================
+
+In cases where XEmacs does not automatically choose the right coding
+system, you can use these commands to specify one:
+
+`C-x <RET> f CODING <RET>'
+ Use coding system CODING for the visited file in the current
+ buffer.
+
+`C-x <RET> c CODING <RET>'
+ Specify coding system CODING for the immediately following command.
+
+`C-x <RET> k CODING <RET>'
+ Use coding system CODING for keyboard input. (This feature is
+ non-functional and is temporarily disabled.)
+
+`C-x <RET> t CODING <RET>'
+ Use coding system CODING for terminal output.
+
+`C-x <RET> p CODING <RET>'
+ Use coding system CODING for subprocess input and output in the
+ current buffer.
+
+ The command `C-x RET f' (`set-buffer-file-coding-system') specifies
+the file coding system for the current buffer--in other words, which
+coding system to use when saving or rereading the visited file. You
+specify which coding system using the minibuffer. Since this command
+applies to a file you have already visited, it affects only the way the
+file is saved.
+
+ Another way to specify the coding system for a file is when you visit
+the file. First use the command `C-x <RET> c'
+(`universal-coding-system-argument'); this command uses the minibuffer
+to read a coding system name. After you exit the minibuffer, the
+specified coding system is used for _the immediately following command_.
+
+ So if the immediately following command is `C-x C-f', for example,
+it reads the file using that coding system (and records the coding
+system for when the file is saved). Or if the immediately following
+command is `C-x C-w', it writes the file using that coding system.
+Other file commands affected by a specified coding system include `C-x
+C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'.
+
+ In addition, if you run some file input commands with the precedent
+`C-u', you can specify coding system to read from minibuffer. So if
+the immediately following command is `C-x C-f', for example, it reads
+the file using that coding system (and records the coding system for
+when the file is saved). Other file commands affected by a specified
+coding system include `C-x C-i' and `C-x C-v', as well as the
+other-window variants of `C-x C-f'.
+
+ The variable `default-buffer-file-coding-system' specifies the
+choice of coding system to use when you create a new file. It applies
+when you find a new file, and when you create a buffer and then save it
+in a file. Selecting a language environment typically sets this
+variable to a good choice of default coding system for that language
+environment.
+
+ The command `C-x <RET> t' (`set-terminal-coding-system') specifies
+the coding system for terminal output. If you specify a character code
+for terminal output, all characters output to the terminal are
+translated into that coding system.
+
+ This feature is useful for certain character-only terminals built to
+support specific languages or character sets--for example, European
+terminals that support one of the ISO Latin character sets.
+
+ By default, output to the terminal is not translated at all.
+
+ The command `C-x <RET> k' (`set-keyboard-coding-system') specifies
+the coding system for keyboard input. Character-code translation of
+keyboard input is useful for terminals with keys that send non-ASCII
+graphic characters--for example, some terminals designed for ISO
+Latin-1 or subsets of it.
+
+ By default, keyboard input is not translated at all.
+
+ There is a similarity between using a coding system translation for
+keyboard input, and using an input method: both define sequences of
+keyboard input that translate into single characters. However, input
+methods are designed to be convenient for interactive use by humans, and
+the sequences that are translated are typically sequences of ASCII
+printing characters. Coding systems typically translate sequences of
+non-graphic characters.
+
+ (This feature is non-functional and is temporarily disabled.)
+
+ The command `C-x <RET> p' (`set-buffer-process-coding-system')
+specifies the coding system for input and output to a subprocess. This
+command applies to the current buffer; normally, each subprocess has its
+own buffer, and thus you can use this command to specify translation to
+and from a particular subprocess by giving the command in the
+corresponding buffer.
+
+ By default, process input and output are not translated at all.
+
+ The variable `file-name-coding-system' specifies a coding system to
+use for encoding file names. If you set the variable to a coding
+system name (as a Lisp symbol or a string), XEmacs encodes file names
+using that coding system for all file operations. This makes it
+possible to use non-Latin-1 characters in file names--or, at least,
+those non-Latin-1 characters which the specified coding system can
+encode. By default, this variable is `nil', which implies that you
+cannot use non-Latin-1 characters in file names.
+
+\1f
+File: xemacs.info, Node: Major Modes, Next: Indentation, Prev: Mule, Up: Top
+
+Major Modes
+***********
+
+Emacs has many different "major modes", each of which customizes Emacs
+for editing text of a particular sort. The major modes are mutually
+exclusive; at any time, each buffer has one major mode. The mode line
+normally contains the name of the current major mode in parentheses.
+*Note Mode Line::.
+
+ The least specialized major mode is called "Fundamental mode". This
+mode has no mode-specific redefinitions or variable settings. Each
+Emacs command behaves in its most general manner, and each option is in
+its default state. For editing any specific type of text, such as Lisp
+code or English text, you should switch to the appropriate major mode,
+such as Lisp mode or Text mode.
+
+ Selecting a major mode changes the meanings of a few keys to become
+more specifically adapted to the language being edited. <TAB>, <DEL>,
+and <LFD> are changed frequently. In addition, commands which handle
+comments use the mode to determine how to delimit comments. Many major
+modes redefine the syntactical properties of characters appearing in
+the buffer. *Note Syntax::.
+
+ The major modes fall into three major groups. Lisp mode (which has
+several variants), C mode, and Muddle mode are for specific programming
+languages. Text mode, Nroff mode, TeX mode, and Outline mode are for
+editing English text. The remaining major modes are not intended for
+use on users' files; they are used in buffers created by Emacs for
+specific purposes and include Dired mode for buffers made by Dired
+(*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending
+Mail::), and Shell mode for buffers used for communicating with an
+inferior shell process (*note Interactive Shell::).
+
+ Most programming language major modes specify that only blank lines
+separate paragraphs. This is so that the paragraph commands remain
+useful. *Note Paragraphs::. They also cause Auto Fill mode to use the
+definition of <TAB> to indent the new lines it creates. This is
+because most lines in a program are usually indented. *Note
+Indentation::.
+
+* Menu:
+
+* Choosing Modes:: How major modes are specified or chosen.
+
+\1f
+File: xemacs.info, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes
+
+Choosing Major Modes
+====================
+
+You can select a major mode explicitly for the current buffer, but most
+of the time Emacs determines which mode to use based on the file name
+or some text in the file.
+
+ Use a `M-x' command to explicitly select a new major mode. Add
+`-mode' to the name of a major mode to get the name of a command to
+select that mode. For example, to enter Lisp mode, execute `M-x
+lisp-mode'.
+
+ When you visit a file, Emacs usually chooses the right major mode
+based on the file's name. For example, files whose names end in `.c'
+are edited in C mode. The variable `auto-mode-alist' controls the
+correspondence between file names and major mode. Its value is a list
+in which each element has the form:
+
+ (REGEXP . MODE-FUNCTION)
+
+For example, one element normally found in the list has the form
+`("\\.c$" . c-mode)'. It is responsible for selecting C mode for files
+whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to
+include a `\' in the string, which is needed to suppress the special
+meaning of `.' in regexps.) The only practical way to change this
+variable is with Lisp code.
+
+ You can specify which major mode should be used for editing a certain
+file by a special sort of text in the first non-blank line of the file.
+The mode name should appear in this line both preceded and followed by
+`-*-'. Other text may appear on the line as well. For example,
+
+ ;-*-Lisp-*-
+
+tells Emacs to use Lisp mode. Note how the semicolon is used to make
+Lisp treat this line as a comment. Such an explicit specification
+overrides any default mode based on the file name.
+
+ Another format of mode specification is:
+
+ -*-Mode: MODENAME;-*-
+
+which allows other things besides the major mode name to be specified.
+However, Emacs does not look for anything except the mode name.
+
+ The major mode can also be specified in a local variables list.
+*Note File Variables::.
+
+ When you visit a file that does not specify a major mode to use, or
+when you create a new buffer with `C-x b', Emacs uses the major mode
+specified by the variable `default-major-mode'. Normally this value is
+the symbol `fundamental-mode', which specifies Fundamental mode. If
+`default-major-mode' is `nil', the major mode is taken from the
+previously selected buffer.
+
+\1f
+File: xemacs.info, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top
+
+Indentation
+***********
+
+`<TAB>'
+ Indent current line "appropriately" in a mode-dependent fashion.
+
+`<LFD>'
+ Perform <RET> followed by <TAB> (`newline-and-indent').
+
+`M-^'
+ Merge two lines (`delete-indentation'). This would cancel out the
+ effect of <LFD>.
+
+`C-M-o'
+ Split line at point; text on the line after point becomes a new
+ line indented to the same column that it now starts in
+ (`split-line').
+
+`M-m'
+ Move (forward or back) to the first non-blank character on the
+ current line (`back-to-indentation').
+
+`C-M-\'
+ Indent several lines to same column (`indent-region').
+
+`C-x <TAB>'
+ Shift block of lines rigidly right or left (`indent-rigidly').
+
+`M-i'
+ Indent from point to the next prespecified tab stop column
+ (`tab-to-tab-stop').
+
+`M-x indent-relative'
+ Indent from point to under an indentation point in the previous
+ line.
+
+ Most programming languages have some indentation convention. For
+Lisp code, lines are indented according to their nesting in
+parentheses. The same general idea is used for C code, though details
+differ.
+
+ Use the <TAB> command to indent a line whatever the language. Each
+major mode defines this command to perform indentation appropriate for
+the particular language. In Lisp mode, <TAB> aligns a line according
+to its depth in parentheses. No matter where in the line you are when
+you type <TAB>, it aligns the line as a whole. In C mode, <TAB>
+implements a subtle and sophisticated indentation style that knows
+about many aspects of C syntax.
+
+ In Text mode, <TAB> runs the command `tab-to-tab-stop', which
+indents to the next tab stop column. You can set the tab stops with
+`M-x edit-tab-stops'.
+
+* Menu:
+
+* Indentation Commands:: Various commands and techniques for indentation.
+* Tab Stops:: You can set arbitrary "tab stops" and then
+ indent to the next tab stop when you want to.
+* Just Spaces:: You can request indentation using just spaces.
+
+\1f
+File: xemacs.info, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation
+
+Indentation Commands and Techniques
+===================================
+
+If you just want to insert a tab character in the buffer, you can type
+`C-q <TAB>'.
+
+ To move over the indentation on a line, type `Meta-m'
+(`back-to-indentation'). This command, given anywhere on a line,
+positions point at the first non-blank character on the line.
+
+ To insert an indented line before the current line, type `C-a C-o
+<TAB>'. To make an indented line after the current line, use `C-e
+<LFD>'.
+
+ `C-M-o' (`split-line') moves the text from point to the end of the
+line vertically down, so that the current line becomes two lines.
+`C-M-o' first moves point forward over any spaces and tabs. Then it
+inserts after point a newline and enough indentation to reach the same
+column point is on. Point remains before the inserted newline; in this
+regard, `C-M-o' resembles `C-o'.
+
+ To join two lines cleanly, use the `Meta-^' (`delete-indentation')
+command to delete the indentation at the front of the current line, and
+the line boundary as well. Empty spaces are replaced by a single
+space, or by no space if at the beginning of a line, before a close
+parenthesis, or after an open parenthesis. To delete just the
+indentation of a line, go to the beginning of the line and use `Meta-\'
+(`delete-horizontal-space'), which deletes all spaces and tabs around
+the cursor.
+
+ There are also commands for changing the indentation of several
+lines at once. `Control-Meta-\' (`indent-region') gives each line which
+begins in the region the "usual" indentation by invoking <TAB> at the
+beginning of the line. A numeric argument specifies the column to
+indent to. Each line is shifted left or right so that its first
+non-blank character appears in that column. `C-x <TAB>'
+(`indent-rigidly') moves all the lines in the region right by its
+argument (left, for negative arguments). The whole group of lines moves
+rigidly sideways, which is how the command gets its name.
+
+ `M-x indent-relative' indents at point based on the previous line
+(actually, the last non-empty line.) It inserts whitespace at point,
+moving point, until it is underneath an indentation point in the
+previous line. An indentation point is the end of a sequence of
+whitespace or the end of the line. If point is farther right than any
+indentation point in the previous line, the whitespace before point is
+deleted and the first indentation point then applicable is used. If no
+indentation point is applicable even then, `tab-to-tab-stop' is run
+(see next section).
+
+ `indent-relative' is the definition of <TAB> in Indented Text mode.
+*Note Text::.
+
+\1f
+File: xemacs.info, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation
+
+Tab Stops
+=========
+
+For typing in tables, you can use Text mode's definition of <TAB>,
+`tab-to-tab-stop'. This command inserts indentation before point,
+enough to reach the next tab stop column. Even if you are not in Text
+mode, this function is associated with `M-i' anyway.
+
+ You can arbitrarily set the tab stops used by `M-i'. They are
+stored as a list of column-numbers in increasing order in the variable
+`tab-stop-list'.
+
+ The convenient way to set the tab stops is using `M-x
+edit-tab-stops', which creates and selects a buffer containing a
+description of the tab stop settings. You can edit this buffer to
+specify different tab stops, and then type `C-c C-c' to make those new
+tab stops take effect. In the tab stop buffer, `C-c C-c' runs the
+function `edit-tab-stops-note-changes' rather than the default
+`save-buffer'. `edit-tab-stops' records which buffer was current when
+you invoked it, and stores the tab stops in that buffer. Normally all
+buffers share the same tab stops and changing them in one buffer
+affects all. If you make `tab-stop-list' local in one buffer
+`edit-tab-stops' in that buffer edits only the local settings.
+
+ Below is the text representing ordinary tab stops every eight
+columns:
+
+ : : : : : :
+ 0 1 2 3 4
+ 0123456789012345678901234567890123456789012345678
+ To install changes, type C-c C-c
+
+ The first line contains a colon at each tab stop. The remaining
+lines help you see where the colons are and tell you what to do.
+
+ Note that the tab stops that control `tab-to-tab-stop' have nothing
+to do with displaying tab characters in the buffer. *Note Display
+Vars::, for more information on that.
+
+\1f
+File: xemacs.info, Node: Just Spaces, Prev: Tab Stops, Up: Indentation
+
+Tabs vs. Spaces
+===============
+
+Emacs normally uses both tabs and spaces to indent lines. If you
+prefer, all indentation can be made from spaces only. To request this,
+set `indent-tabs-mode' to `nil'. This 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::.
+
+ There are also commands to convert tabs to spaces or vice versa,
+always preserving the columns of all non-blank text. `M-x tabify'
+scans the region for sequences of spaces, and converts sequences of at
+least three spaces to tabs if that is possible without changing
+indentation. `M-x untabify' changes all tabs in the region to
+corresponding numbers of spaces.
+
+\1f
+File: xemacs.info, Node: Text, Next: Programs, Prev: Indentation, Up: Top
+
+Commands for Human Languages
+****************************
+
+The term "text" has two widespread meanings in our area of the computer
+field. One is data that is a sequence of characters. In this sense of
+the word any file that you edit with Emacs is text. The other meaning
+is more restrictive: a sequence of characters in a human language for
+humans to read (possibly after processing by a text formatter), as
+opposed to a program or commands for a program.
+
+ Human languages have syntactic and stylistic conventions that editor
+commands should support or use to advantage: conventions involving
+words, sentences, paragraphs, and capital letters. This chapter
+describes Emacs commands for all these things. There are also commands
+for "filling", or rearranging paragraphs into lines of approximately
+equal length. The commands for moving over and killing words,
+sentences, and paragraphs, while intended primarily for editing text,
+are also often useful for editing programs.
+
+ Emacs has several major modes for editing human language text. If a
+file contains plain text, use Text mode, which customizes Emacs in
+small ways for the syntactic conventions of text. For text which
+contains embedded commands for text formatters, Emacs has other major
+modes, each for a particular text formatter. Thus, for input to TeX,
+you can use TeX mode; for input to nroff, Nroff mode.
+
+* Menu:
+
+* Text Mode:: The major modes for editing text files.
+* Nroff Mode:: The major mode for editing input to the formatter nroff.
+* TeX Mode:: The major modes for editing input to the formatter TeX.
+* Outline Mode:: The major mode for editing outlines.
+* Words:: Moving over and killing words.
+* Sentences:: Moving over and killing sentences.
+* Paragraphs:: Moving over paragraphs.
+* Pages:: Moving over pages.
+* Filling:: Filling or justifying text
+* Case:: Changing the case of text
+
+\1f
+File: xemacs.info, Node: Text Mode, Next: Words, Prev: Text, Up: Text
+
+Text Mode
+=========
+
+You should use Text mode--rather than Fundamental or Lisp mode--to edit
+files of text in a human language. Invoke `M-x text-mode' to enter
+Text mode. In Text mode, <TAB> runs the function `tab-to-tab-stop',
+which allows you to use arbitrary tab stops set with `M-x
+edit-tab-stops' (*note Tab Stops::). Features concerned with comments
+in programs are turned off unless they are explicitly invoked. The
+syntax table is changed so that periods are not considered part of a
+word, while apostrophes, backspaces and underlines are.
+
+ A similar variant mode is Indented Text mode, intended for editing
+text in which most lines are indented. This mode defines <TAB> to run
+`indent-relative' (*note Indentation::), and makes Auto Fill indent the
+lines it creates. As a result, a line made by Auto Filling, or by
+<LFD>, is normally indented just like the previous line. Use `M-x
+indented-text-mode' to select this mode.
+
+ Entering Text mode or Indented Text mode calls the value of the
+variable `text-mode-hook' with no arguments, if that value exists and
+is not `nil'. This value is also called when modes related to Text
+mode are entered; this includes Nroff mode, TeX mode, Outline mode, and
+Mail mode. Your hook can look at the value of `major-mode' to see
+which of these modes is actually being entered.
+
+ Two modes similar to Text mode are of use for editing text that is to
+be passed through a text formatter before achieving its final readable
+form.
+
+* Menu:
+
+* Nroff Mode:: The major mode for editing input to the formatter nroff.
+* TeX Mode:: The major modes for editing input to the formatter TeX.
+
+
+ Another similar mode is used for editing outlines. It allows you
+to view the text at various levels of detail. You can view either
+the outline headings alone or both headings and text; you can also
+hide some of the headings at lower levels from view to make the high
+level structure more visible.
+
+
+* Outline Mode:: The major mode for editing outlines.
+
+\1f
+File: xemacs.info, Node: Nroff Mode, Next: TeX Mode, Prev: Text Mode, Up: Text Mode
+
+Nroff Mode
+----------
+
+Nroff mode is a mode like Text mode but modified to handle nroff
+commands present in the text. Invoke `M-x nroff-mode' to enter this
+mode. Nroff mode differs from Text mode in only a few ways. All nroff
+command lines are considered paragraph separators, so that filling never
+garbles the nroff commands. Pages are separated by `.bp' commands.
+Comments start with backslash-doublequote. There are also three special
+commands that are not available in Text mode:
+
+`M-n'
+ Move to the beginning of the next line that isn't an nroff command
+ (`forward-text-line'). An argument is a repeat count.
+
+`M-p'
+ Like `M-n' but move up (`backward-text-line').
+
+`M-?'
+ Prints in the echo area the number of text lines (lines that are
+ not nroff commands) in the region (`count-text-lines').
+
+ The other feature of Nroff mode is Electric Nroff newline mode.
+This is a minor mode that you can turn on or off with `M-x
+electric-nroff-mode' (*note Minor Modes::). When the mode is on and
+you use <RET> to end a line containing an nroff command that opens a
+kind of grouping, Emacs automatically inserts the matching nroff
+command to close that grouping on the following line. For example, if
+you are at the beginning of a line and type `.(b <RET>', the matching
+command `.)b' will be inserted on a new line following point.
+
+ Entering Nroff mode calls the value of the variable `text-mode-hook'
+with no arguments, if that value exists and is not `nil'; then it does
+the same with the variable `nroff-mode-hook'.
+
+\1f
+File: xemacs.info, Node: TeX Mode, Next: Outline Mode, Prev: Nroff Mode, Up: Text Mode
+
+TeX Mode
+--------
+
+TeX is a powerful text formatter written by Donald Knuth; like GNU
+Emacs, it is free. LaTeX is a simplified input format for TeX,
+implemented by TeX macros. It is part of TeX.
+
+ Emacs has a special TeX mode for editing TeX input files. It
+provides facilities for checking the balance of delimiters and for
+invoking TeX on all or part of the file.
+
+ TeX mode has two variants, Plain TeX mode and LaTeX mode, which are
+two distinct major modes that differ only slightly. These modes are
+designed for editing the two different input formats. The command `M-x
+tex-mode' looks at the contents of a buffer to determine whether it
+appears to be LaTeX input or not; it then selects the appropriate mode.
+If it can't tell which is right (e.g., the buffer is empty), the
+variable `tex-default-mode' controls which mode is used.
+
+ The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly
+select one of the variants of TeX mode. Use these commands when `M-x
+tex-mode' does not guess right.
+
+* Menu:
+
+* Editing: TeX Editing. Special commands for editing in TeX mode.
+* Printing: TeX Print. Commands for printing part of a file with TeX.
+
+ TeX for Unix systems can be obtained from the University of
+Washington for a distribution fee.
+
+ To order a full distribution, send $140.00 for a 1/2 inch 9-track
+tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites
+$150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra
+postage) payable to the University of Washington to:
+
+ The Director
+ Northwest Computer Support Group, DW-10
+ University of Washington
+ Seattle, Washington 98195
+
+Purchase orders are acceptable, but there is an extra charge of $10.00
+to pay for processing charges. (The total cost comes to $150 for
+domestic sites, $175 for foreign sites).
+
+ The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
+industry standard 2400 foot half-inch reel. The physical format for
+the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
+serpentine recording for the SUN. Also, SystemV tapes can be written
+in cpio format, blocked 5120 bytes, ASCII headers.
+
+\1f
+File: xemacs.info, Node: TeX Editing, Next: TeX Print, Prev: TeX Mode, Up: TeX Mode
+
+TeX Editing Commands
+....................
+
+Here are the special commands provided in TeX mode for editing the text
+of the file.
+
+`"'
+ Insert, according to context, either ```' or `"' or `'''
+ (`TeX-insert-quote').
+
+`<LFD>'
+ Insert a paragraph break (two newlines) and check the previous
+ paragraph for unbalanced braces or dollar signs (`tex-terminate-
+ paragraph').
+
+`M-x validate-tex-buffer'
+ Check each paragraph in the buffer for unbalanced braces or dollar
+ signs.
+
+`C-c {'
+ Insert `{}' and position point between them (`tex-insert-braces').
+
+`C-c }'
+ Move forward past the next unmatched close brace (`up-list').
+
+`C-c C-e'
+ Close a block for LaTeX (`tex-close-latex-block').
+
+ In TeX, the character `"' is not normally used; you use ```' to
+start a quotation and `''' to end one. TeX mode defines the key `"' to
+insert ```' after whitespace or an open brace, `"' after a backslash,
+or `''' otherwise. This is done by the command `tex-insert-quote'. If
+you need the character `"' itself in unusual contexts, use `C-q' to
+insert it. Also, `"' with a numeric argument always inserts that
+number of `"' characters.
+
+ In TeX mode, `$' has a special syntax code which attempts to
+understand the way TeX math mode delimiters match. When you insert a
+`$' that is meant to exit math mode, the position of the matching `$'
+that entered math mode is displayed for a second. This is the same
+feature that displays the open brace that matches a close brace that is
+inserted. However, there is no way to tell whether a `$' enters math
+mode or leaves it; so when you insert a `$' that enters math mode, the
+previous `$' position is shown as if it were a match, even though they
+are actually unrelated.
+
+ If you prefer to keep braces balanced at all times, you can use `C-c
+{' (`tex-insert-braces') to insert a pair of braces. It leaves point
+between the two braces so you can insert the text that belongs inside.
+Afterward, use the command `C-c }' (`up-list') to move forward past the
+close brace.
+
+ There are two commands for checking the matching of braces. <LFD>
+(`tex-terminate-paragraph') checks the paragraph before point, and
+inserts two newlines to start a new paragraph. It prints a message in
+the echo area if any mismatch is found. `M-x validate-tex-buffer'
+checks the entire buffer, paragraph by paragraph. When it finds a
+paragraph that contains a mismatch, it displays point at the beginning
+of the paragraph for a few seconds and pushes a mark at that spot.
+Scanning continues until the whole buffer has been checked or until you
+type another key. The positions of the last several paragraphs with
+mismatches can be found in the mark ring (*note Mark Ring::).
+
+ Note that square brackets and parentheses, not just braces, are
+matched in TeX mode. This is wrong if you want to check TeX syntax.
+However, parentheses and square brackets are likely to be used in text
+as matching delimiters and it is useful for the various motion commands
+and automatic match display to work with them.
+
+ In LaTeX input, `\begin' and `\end' commands must balance. After
+you insert a `\begin', use `C-c C-f' (`tex-close-latex-block') to
+insert automatically a matching `\end' (on a new line following the
+`\begin'). A blank line is inserted between the two, and point is left
+there.
+
+\1f
+File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode
+
+TeX Printing Commands
+.....................
+
+You can invoke TeX as an inferior of Emacs on either the entire
+contents of the buffer or just a region at a time. Running TeX in this
+way on just one chapter is a good way to see what your changes look
+like without taking the time to format the entire file.
+
+`C-c C-r'
+ Invoke TeX on the current region, plus the buffer's header
+ (`tex-region').
+
+`C-c C-b'
+ Invoke TeX on the entire current buffer (`tex-buffer').
+
+`C-c C-l'
+ Recenter the window showing output from the inferior TeX so that
+ the last line can be seen (`tex-recenter-output-buffer').
+
+`C-c C-k'
+ Kill the inferior TeX (`tex-kill-job').
+
+`C-c C-p'
+ Print the output from the last `C-c C-r' or `C-c C-b' command
+ (`tex-print').
+
+`C-c C-q'
+ Show the printer queue (`tex-show-print-queue').
+
+ You can pass the current buffer through an inferior TeX using `C-c
+C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp';
+to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q'
+(`tex-show-print-queue') to view the progress of your output towards
+being printed.
+
+ The console output from TeX, including any error messages, appears
+in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
+to this buffer and feed it input (this works as in Shell mode; *note
+Interactive Shell::). Without switching to this buffer, you can scroll
+it so that its last line is visible by typing `C-c C-l'.
+
+ Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
+that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
+kills any TeX process still running.
+
+ You can pass an arbitrary region through an inferior TeX by typing
+`C-c C-r' (`tex-region'). This is tricky, however, because most files
+of TeX input contain commands at the beginning to set parameters and
+define macros. Without them, no later part of the file will format
+correctly. To solve this problem, `C-c C-r' allows you to designate a
+part of the file as containing essential commands; it is included
+before the specified region as part of the input to TeX. The
+designated part of the file is called the "header".
+
+ To indicate the bounds of the header in Plain TeX mode, insert two
+special strings in the file: `%**start of header' before the header,
+and `%**end of header' after it. Each string must appear entirely on
+one line, but there may be other text on the line before or after. The
+lines containing the two strings are included in the header. If
+`%**start of header' does not appear within the first 100 lines of the
+buffer, `C-c C-r' assumes there is no header.
+
+ In LaTeX mode, the header begins with `\documentstyle' and ends with
+`\begin{document}'. These are commands that LaTeX requires you to use,
+so you don't need to do anything special to identify the header.
+
+ When you enter either kind of TeX mode, Emacs calls with no
+arguments the value of the variable `text-mode-hook', if that value
+exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook'
+and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
+conditions.
+
+\1f
+File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode
+
+Outline Mode
+------------
+
+Outline mode is a major mode similar to Text mode but intended for
+editing outlines. It allows you to make parts of the text temporarily
+invisible so that you can see just the overall structure of the
+outline. Type `M-x outline-mode' to turn on Outline mode in the
+current buffer.
+
+ When you enter Outline mode, Emacs calls with no arguments the value
+of the variable `text-mode-hook', if that value exists and is not
+`nil'; then it does the same with the variable `outline-mode-hook'.
+
+ When a line is invisible in outline mode, it does not appear on the
+screen. The screen appears exactly as if the invisible line were
+deleted, except that an ellipsis (three periods in a row) appears at
+the end of the previous visible line (only one ellipsis no matter how
+many invisible lines follow).
+
+ All editing commands treat the text of the invisible line as part of
+the previous visible line. For example, `C-n' moves onto the next
+visible line. Killing an entire visible line, including its
+terminating newline, really kills all the following invisible lines as
+well; yanking everything back yanks the invisible lines and they remain
+invisible.
+
+* Menu:
+
+* Format: Outline Format. What the text of an outline looks like.
+* Motion: Outline Motion. Special commands for moving through outlines.
+* Visibility: Outline Visibility. Commands to control what is visible.
+
+\1f
+File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
+
+Format of Outlines
+..................
+
+Outline mode assumes that the lines in the buffer are of two types:
+"heading lines" and "body lines". A heading line represents a topic in
+the outline. Heading lines start with one or more stars; the number of
+stars determines the depth of the heading in the outline structure.
+Thus, a heading line with one star is a major topic; all the heading
+lines with two stars between it and the next one-star heading are its
+subtopics; and so on. Any line that is not a heading line is a body
+line. Body lines belong to the preceding heading line. Here is an
+example:
+
+ * Food
+
+ This is the body,
+ which says something about the topic of food.
+
+ ** Delicious Food
+
+ This is the body of the second-level header.
+
+ ** Distasteful Food
+
+ This could have
+ a body too, with
+ several lines.
+
+ *** Dormitory Food
+
+ * Shelter
+
+ A second first-level topic with its header line.
+
+ A heading line together with all following body lines is called
+collectively an "entry". A heading line together with all following
+deeper heading lines and their body lines is called a "subtree".
+
+ You can customize the criterion for distinguishing heading lines by
+setting the variable `outline-regexp'. Any line whose beginning has a
+match for this regexp is considered a heading line. Matches that start
+within a line (not at the beginning) do not count. The length of the
+matching text determines the level of the heading; longer matches make
+a more deeply nested level. Thus, for example, if a text formatter has
+commands `@chapter', `@section' and `@subsection' to divide the
+document into chapters and sections, you can make those lines count as
+heading lines by setting `outline-regexp' to
+`"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
+`chapter' and `section' are the same length, but by defining the regexp
+to match only `chap' we ensure that the length of the text matched on a
+chapter heading is shorter, so that Outline mode will know that
+sections are contained in chapters. This works as long as no other
+command starts with `@chap'.
+
+ Outline mode makes a line invisible by changing the newline before it
+into an ASCII Control-M (code 015). Most editing commands that work on
+lines treat an invisible line as part of the previous line because,
+strictly speaking, it is part of that line, since there is no longer a
+newline in between. When you save the file in Outline mode, Control-M
+characters are saved as newlines, so the invisible lines become ordinary
+lines in the file. Saving does not change the visibility status of a
+line inside Emacs.
+
+\1f
+File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
+
+Outline Motion Commands
+.......................
+
+Some special commands in Outline mode move backward and forward to
+heading lines.
+
+`C-c C-n'
+ Move point to the next visible heading line
+ (`outline-next-visible-heading').
+
+`C-c C-p'
+ Move point to the previous visible heading line
+ (`outline-previous-visible-heading').
+
+`C-c C-f'
+ Move point to the next visible heading line at the same level as
+ the one point is on (`outline-forward-same-level').
+
+`C-c C-b'
+ Move point to the previous visible heading line at the same level
+ (`outline-backward-same-level').
+
+`C-c C-u'
+ Move point up to a lower-level (more inclusive) visible heading
+ line (`outline-up-heading').
+
+ `C-c C-n' (`next-visible-heading') moves down to the next heading
+line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
+Both accept numeric arguments as repeat counts. The names emphasize
+that invisible headings are skipped, but this is not really a special
+feature. All editing commands that look for lines ignore the invisible
+lines automatically.
+
+ More advanced motion commands understand the levels of headings.
+The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
+(`outline-backward-same-level') move from one heading line to another
+visible heading at the same depth in the outline. `C-c C-u'
+(`outline-up-heading') moves backward to another heading that is less
+deeply nested.
+
+\1f
+File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
+
+Outline Visibility Commands
+...........................
+
+The other special commands of outline mode are used to make lines
+visible or invisible. Their names all start with `hide' or `show'.
+Most of them exist as pairs of opposites. They are not undoable;
+instead, you can undo right past them. Making lines visible or
+invisible is simply not recorded by the undo mechanism.
+
+`M-x hide-body'
+ Make all body lines in the buffer invisible.
+
+`M-x show-all'
+ Make all lines in the buffer visible.
+
+`C-c C-d'
+ Make everything under this heading invisible, not including this
+ heading itself (`hide-subtree').
+
+`C-c C-s'
+ Make everything under this heading visible, including body,
+ subheadings, and their bodies (`show-subtree').
+
+`M-x hide-leaves'
+ Make the body of this heading line, and of all its subheadings,
+ invisible.
+
+`M-x show-branches'
+ Make all subheadings of this heading line, at all levels, visible.
+
+`C-c C-i'
+ Make immediate subheadings (one level down) of this heading line
+ visible (`show-children').
+
+`M-x hide-entry'
+ Make this heading line's body invisible.
+
+`M-x show-entry'
+ Make this heading line's body visible.
+
+ Two commands that are exact opposites are `M-x hide-entry' and `M-x
+show-entry'. They are used with point on a heading line, and apply
+only to the body lines of that heading. The subtopics and their bodies
+are not affected.
+
+ Two more powerful opposites are `C-c C-d' (`hide-subtree') and `C-c
+C-s' (`show-subtree'). Both should be used when point is on a heading
+line, and both apply to all the lines of that heading's "subtree": its
+body, all its subheadings, both direct and indirect, and all of their
+bodies. In other words, the subtree contains everything following this
+heading line, up to and not including the next heading of the same or
+higher rank.
+
+ Intermediate between a visible subtree and an invisible one is having
+all the subheadings visible but none of the body. There are two
+commands for doing this, one that hides the bodies and one that makes
+the subheadings visible. They are `M-x hide-leaves' and `M-x
+show-branches'.
+
+ A little weaker than `show-branches' is `C-c C-i' (`show-children').
+It makes just the direct subheadings visible--those one level down.
+Deeper subheadings remain invisible.
+
+ Two commands have a blanket effect on the whole file. `M-x
+hide-body' makes all body lines invisible, so that you see just the
+outline structure. `M-x show-all' makes all lines visible. You can
+think of these commands as a pair of opposites even though `M-x
+show-all' applies to more than just body lines.
+
+ You can turn off the use of ellipses at the ends of visible lines by
+setting `selective-display-ellipses' to `nil'. The result is no
+visible indication of the presence of invisible lines.
+
+\1f
+File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
+
+Words
+=====
+
+Emacs has commands for moving over or operating on words. By
+convention, the keys for them are all `Meta-' characters.
+
+`M-f'
+ Move forward over a word (`forward-word').
+
+`M-b'
+ Move backward over a word (`backward-word').
+
+`M-d'
+ Kill up to the end of a word (`kill-word').
+
+`M-<DEL>'
+ Kill back to the beginning of a word (`backward-kill-word').
+
+`M-@'
+ Mark the end of the next word (`mark-word').
+
+`M-t'
+ Transpose two words; drag a word forward or backward across other
+ words (`transpose-words').
+
+ Notice how these keys form a series that parallels the
+character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
+to `C-@', which is an alias for `C-<SPC>'.
+
+ The commands `Meta-f' (`forward-word') and `Meta-b'
+(`backward-word') move forward and backward over words. They are
+analogous to `Control-f' and `Control-b', which move over single
+characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
+move several words if given an argument. `Meta-f' with a negative
+argument moves backward, and `Meta-b' with a negative argument moves
+forward. Forward motion stops after the last letter of the word, while
+backward motion stops before the first letter.
+
+ `Meta-d' (`kill-word') kills the word after point. To be precise,
+it kills everything from point to the place `Meta-f' would move to.
+Thus, if point is in the middle of a word, `Meta-d' kills just the part
+after point. If some punctuation comes between point and the next
+word, it is killed along with the word. (To kill only the next word
+but not the punctuation before it, simply type `Meta-f' to get to the
+end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
+arguments just like `Meta-f'.
+
+ `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
+kills everything from point back to where `Meta-b' would move to. If
+point is after the space in `FOO, BAR', then `FOO, ' is killed. To
+kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
+
+ `Meta-t' (`transpose-words') exchanges the word before or containing
+point with the following word. The delimiter characters between the
+words do not move. For example, transposing `FOO, BAR' results in
+`BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
+transposition and on arguments to transposition commands.
+
+ To operate on the next N words with an operation which applies
+between point and mark, you can either set the mark at point and then
+move over the words, or you can use the command `Meta-@' (`mark-word')
+which does not move point but sets the mark where `Meta-f' would move
+to. It can be given arguments just like `Meta-f'.
+
+ The word commands' understanding of syntax is completely controlled
+by the syntax table. For example, any character can be declared to be
+a word delimiter. *Note Syntax::.
+
+\1f
+File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
+
+Sentences
+=========
+
+The Emacs commands for manipulating sentences and paragraphs are mostly
+on `Meta-' keys, and therefore are like the word-handling commands.
- XEmacs can be used with the X Window System and a window manager like
-MWM or TWM. In that case, the X window manager opens, closes, and
-resizes XEmacs frames. You use the window manager's mouse gestures to
-perform the operations. Consult your window manager guide or reference
-manual for information on manipulating X windows.
+`M-a'
+ Move back to the beginning of the sentence (`backward-sentence').
- When you are working under X, each X window (that is, each XEmacs
-frame) has a menu bar for mouse-controlled operations (*note Pull-down
-Menus::).
+`M-e'
+ Move forward to the end of the sentence (`forward-sentence').
- XEmacs under X is also a multi-frame XEmacs. You can use the New
-Frame menu item from the File menu to create a new XEmacs frame in a
-new X window from the same process. The different frames will share the
-same buffer list, but you can look at different buffers in the different
-frames.
+`M-k'
+ Kill forward to the end of the sentence (`kill-sentence').
- The function `find-file-other-frame' is just like `find-file', but
-creates a new frame to display the buffer in first. This is normally
-bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
-does.
+`C-x <DEL>'
+ Kill back to the beginning of the sentence
+ (`backward-kill-sentence').
- The function `switch-to-buffer-other-frame' is just like
-`switch-to-buffer', but creates a new frame to display the buffer in
-first. This is normally bound to `C-x 5 b'.
+ The commands `Meta-a' and `Meta-e' (`backward-sentence' and
+`forward-sentence') move to the beginning and end of the current
+sentence, respectively. They resemble `Control-a' and `Control-e',
+which move to the beginning and end of a line. Unlike their
+counterparts, `Meta-a' and `Meta-e' move over successive sentences if
+repeated or given numeric arguments. Emacs assumes the typist's
+convention is followed, and thus considers a sentence to end wherever
+there is a `.', `?', or `!' followed by the end of a line or two
+spaces, with any number of `)', `]', `'', or `"' characters allowed in
+between. A sentence also begins or ends wherever a paragraph begins or
+ends.
- You can specify a different default frame size other than the one
-provided. Use the variable `default-frame-alist', which is an alist of
-default values for frame creation other than the first one. These may
-be set in your init file, like this:
+ Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
+sentence edge at which it is stopping.
- (setq default-frame-alist '((width . 80) (height . 55)))
+ `M-a' and `M-e' have a corresponding kill command, just like `C-a'
+and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
+kills from point to the end of the sentence. With minus one as an
+argument it kills back to the beginning of the sentence. Larger
+arguments serve as repeat counts.
- For values specific to the first XEmacs frame, you must use X
-resources. The variable `x-frame-defaults' takes an alist of default
-frame creation parameters for X window frames. These override what is
-specified in `~/.Xdefaults' but are overridden by the arguments to the
-particular call to `x-create-frame'.
+ There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
+for killing back to the beginning of a sentence, which is useful when
+you change your mind in the middle of composing text.
- When you create a new frame, the variable `create-frame-hook' is
-called with one argument, the frame just created.
+ The variable `sentence-end' controls recognition of the end of a
+sentence. It is a regexp that matches the last few characters of a
+sentence, together with the whitespace following the sentence. Its
+normal value is:
- If you want to close one or more of the X windows you created using
-New Frame, use the Delete Frame menu item from the File menu.
+ "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
- If you are working with multiple frames, some special information
-applies:
- * Two variables, `frame-title-format' and `frame-icon-title-format'
- determine the title of the frame and the title of the icon that
- results if you shrink the frame.
+This example is explained in the section on regexps. *Note Regexps::.
- * The variables `auto-lower-frame' and `auto-raise-frame' position a
- frame. If true, `auto-lower-frame' lowers a frame to the bottom
- when it is no longer selected. If true, `auto-raise-frame' raises
- a frame to the top when it is selected. Under X, most
- ICCCM-compliant window managers will have options to do this for
- you, but these variables are provided in case you are using a
- broken window manager.
+\1f
+File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
+
+Paragraphs
+==========
+
+The Emacs commands for manipulating paragraphs are also `Meta-' keys.
+
+`M-{'
+ Move back to previous paragraph beginning
+ (`backward-paragraph').
+
+`M-}'
+ Move forward to next paragraph end (`forward-paragraph').
+
+`M-h'
+ Put point and mark around this or next paragraph
+ (`mark-paragraph').
+
+ `Meta-{' moves to the beginning of the current or previous paragraph,
+while `Meta-}' moves to the end of the current or next paragraph.
+Blank lines and text formatter command lines separate paragraphs and are
+not part of any paragraph. An indented line starts a new paragraph.
+
+ In major modes for programs (as opposed to Text mode), paragraphs
+begin and end only at blank lines. As a result, the paragraph commands
+continue to be useful even though there are no paragraphs per se.
+
+ When there is a fill prefix, paragraphs are delimited by all lines
+which don't start with the fill prefix. *Note Filling::.
+
+ To operate on a paragraph, you can use the command `Meta-h'
+(`mark-paragraph') to set the region around it. This command puts
+point at the beginning and mark at the end of the paragraph point was
+in. If point is between paragraphs (in a run of blank lines or at a
+boundary), the paragraph following point is surrounded by point and
+mark. If there are blank lines preceding the first line of the
+paragraph, one of the blank lines is included in the region. Thus, for
+example, `M-h C-w' kills the paragraph around or after point.
+
+ The precise definition of a paragraph boundary is controlled by the
+variables `paragraph-separate' and `paragraph-start'. The value of
+`paragraph-start' is a regexp that matches any line that either starts
+or separates paragraphs. The value of `paragraph-separate' is another
+regexp that matches only lines that separate paragraphs without being
+part of any paragraph. Lines that start a new paragraph and are
+contained in it must match both regexps. For example, normally
+`paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
+\t\f]*$"'.
+
+ Normally it is desirable for page boundaries to separate paragraphs.
+The default values of these variables recognize the usual separator for
+pages.
- * There is a new frame/modeline format directive, %S, which expands
- to the name of the current frame (a frame's name is distinct from
- its title; the name is used for resource lookup, among other
- things, and the title is simply what appears above the window.)
+\1f
+File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
+
+Pages
+=====
+
+Files are often thought of as divided into "pages" by the "formfeed"
+character (ASCII Control-L, octal code 014). For example, if a file is
+printed on a line printer, each "page" of the file starts on a new page
+of paper. Emacs treats a page-separator character just like any other
+character. It can be inserted with `C-q C-l' or deleted with <DEL>.
+You are free to paginate your file or not. However, since pages are
+often meaningful divisions of the file, commands are provided to move
+over them and operate on them.
+
+`C-x ['
+ Move point to previous page boundary (`backward-page').
+
+`C-x ]'
+ Move point to next page boundary (`forward-page').
+
+`C-x C-p'
+ Put point and mark around this page (or another page)
+ (`mark-page').
+
+`C-x l'
+ Count the lines in this page (`count-lines-page').
+
+ The `C-x [' (`backward-page') command moves point to immediately
+after the previous page delimiter. If point is already right after a
+page delimiter, the command skips that one and stops at the previous
+one. A numeric argument serves as a repeat count. The `C-x ]'
+(`forward-page') command moves forward past the next page delimiter.
+
+ The `C-x C-p' command (`mark-page') puts point at the beginning of
+the current page and the mark at the end. The page delimiter at the end
+is included (the mark follows it). The page delimiter at the front is
+excluded (point follows it). You can follow this command by `C-w' to
+kill a page you want to move elsewhere. If you insert the page after a
+page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
+page will be properly delimited before and after once again.
+
+ A numeric argument to `C-x C-p' is used to specify which page to go
+to, relative to the current one. Zero means the current page. One
+means the next page, and -1 means the previous one.
+
+ The `C-x l' command (`count-lines-page') can help you decide where
+to break a page in two. It prints the total number of lines in the
+current page in the echo area, then divides the lines into those
+preceding the current line and those following it, for example
+
+ Page has 96 (72+25) lines
+
+Notice that the sum is off by one; this is correct if point is not at
+the beginning of a line.
+
+ The variable `page-delimiter' should have as its value a regexp that
+matches the beginning of a line that separates pages. This defines
+where pages begin. The normal value of this variable is `"^\f"', which
+matches a formfeed character at the beginning of a line.
\1f
-File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
+File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
-Keystrokes, Key Sequences, and Key Bindings
-*******************************************
+Filling Text
+============
+
+If you use Auto Fill mode, Emacs "fills" text (breaks it up into lines
+that fit in a specified width) as you insert it. When you alter
+existing text it is often no longer be properly filled afterwards and
+you can use explicit commands for filling.
* Menu:
-* Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
-* Representing Keystrokes:: Using lists of modifiers and keysyms to
- represent keystrokes.
-* Key Sequences:: Combine key strokes into key sequences you can
- bind to commands.
-* String Key Sequences:: Available for upward compatibility.
-* Meta Key:: Using <ESC> to represent <Meta>
-* Super and Hyper Keys:: Adding modifier keys on certain keyboards.
-* Character Representation:: How characters appear in Emacs buffers.
-* Commands:: How commands are bound to key sequences.
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling when every line is indented or in a comment, etc.
+
+\1f
+File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
+
+Auto Fill Mode
+--------------
+
+"Auto Fill" mode is a minor mode in which lines are broken
+automatically when they become too wide. Breaking happens only when
+you type a <SPC> or <RET>.
+
+`M-x auto-fill-mode'
+ Enable or disable Auto Fill mode.
+
+`<SPC>'
+`<RET>'
+ In Auto Fill mode, break lines when appropriate.
+
+ `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
+if it was on. With a positive numeric argument the command always turns
+Auto Fill mode on, and with a negative argument it always turns it off.
+The presence of the word `Fill' in the mode line, inside the
+parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
+is a minor mode; you can turn it on or off for each buffer individually.
+*Note Minor Modes::.
+
+ In Auto Fill mode, lines are broken automatically at spaces when
+they get longer than desired. Line breaking and rearrangement takes
+place only when you type <SPC> or <RET>. To insert a space or newline
+without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
+(recall that a newline is really a linefeed). `C-o' inserts a newline
+without line breaking.
+
+ Auto Fill mode works well with Lisp mode: when it makes a new line in
+Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
+comment gets too long, the text of the comment is split into two
+comment lines. Optionally, new comment delimiters are inserted at the
+end of the first line and the beginning of the second, so that each line
+is a separate comment. The variable `comment-multi-line' controls the
+choice (*note Comments::).
+
+ Auto Fill mode does not refill entire paragraphs. It can break
+lines but cannot merge lines. Editing in the middle of a paragraph can
+result in a paragraph that is not correctly filled. The easiest way to
+make the paragraph properly filled again is using an explicit fill
+commands.
+
+ Many users like Auto Fill mode and want to use it in all text files.
+The section on init files explains how you can arrange this permanently
+for yourself. *Note Init File::.
\1f
-File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
+File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
-Keystrokes as Building Blocks of Key Sequences
-==============================================
+Explicit Fill Commands
+----------------------
- Earlier versions of Emacs used only the ASCII character set, which
-defines 128 different character codes. Some of these codes are
-assigned graphic symbols like `a' and `='; the rest are control
-characters, such as `Control-a' (also called `C-a'). `C-a' means you
-hold down the <CTRL> key and then press `a'.
+`M-q'
+ Fill current paragraph (`fill-paragraph').
- Keybindings in XEmacs are not restricted to the set of keystrokes
-that can be represented in ASCII. XEmacs can tell the difference
-between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
+`M-g'
+ Fill each paragraph in the region (`fill-region').
- A keystroke is like a piano chord: you get it by simultaneously
-striking several keys. To be more precise, a keystroke consists of a
-possibly empty set of modifiers followed by a single "keysym". The set
-of modifiers is small; it consists of `Control', `Meta', `Super',
-`Hyper', and `Shift'.
+`C-x f'
+ Set the fill column (`set-fill-column').
- The rest of the keys on your keyboard, along with the mouse buttons,
-make up the set of keysyms. A keysym is usually what is printed on the
-keys on your keyboard. Here is a table of some of the symbolic names
-for keysyms:
-`a,b,c...'
- alphabetic keys
+`M-x fill-region-as-paragraph'
+ Fill the region, considering it as one paragraph.
-`f1,f2...'
- function keys
+`M-s'
+ Center a line.
-`button1'
- left mouse button
+ To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
+It causes the paragraph containing point, or the one after point if
+point is between paragraphs, to be refilled. All line breaks are
+removed, and new ones are inserted where necessary. `M-q' can be
+undone with `C-_'. *Note Undo::.
-`button2'
- middle mouse button
+ To refill many paragraphs, use `M-g' (`fill-region'), which divides
+the region into paragraphs and fills each of them.
-`button3'
- right mouse button
+ `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
+paragraph boundaries (*note Paragraphs::). For more control, you can
+use `M-x fill-region-as-paragraph', which refills everything between
+point and mark. This command recognizes only blank lines as paragraph
+separators.
-`button1up'
- upstroke on the left mouse button
+ A numeric argument to `M-g' or `M-q' causes it to "justify" the text
+as well as filling it. Extra spaces are inserted to make the right
+margin line up exactly at the fill column. To remove the extra spaces,
+use `M-q' or `M-g' with no argument.
-`button2up'
- upstroke on the middle mouse button
+ The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
+match lines that should not be auto-filled.
-`button3up'
- upstroke on the right mouse button
+ The command `Meta-s' (`center-line') centers the current line within
+the current fill column. With an argument, it centers several lines
+individually and moves past them.
-`return'
- Return key
+ The maximum line width for filling is in the variable `fill-column'.
+Altering the value of `fill-column' makes it local to the current
+buffer; until then, the default value--initially 70--is in effect.
+*Note Locals::.
- Use the variable `keyboard-translate-table' only if you are on a
-dumb tty, as it cannot handle input that cannot be represented as ASCII.
-The value of this variable is a string used as a translate table for
-keyboard input or `nil'. Each character is looked up in this string
-and the contents used instead. If the string is of length `n',
-character codes `N' and up are untranslated. If you are running Emacs
-under X, you should do the translations with the `xmodmap' program
-instead.
+ The easiest way to set `fill-column' is to use the command `C-x f'
+(`set-fill-column'). With no argument, it sets `fill-column' to the
+current horizontal position of point. With a numeric argument, it uses
+that number as the new fill column.
\1f
-File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
+File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
+
+The Fill Prefix
+---------------
+
+To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), use the
+"fill prefix" feature. The fill prefix is a string which is not
+included in filling. Emacs expects every line to start with a fill
+prefix.
+
+`C-x .'
+ Set the fill prefix (`set-fill-prefix').
+
+`M-q'
+ Fill a paragraph using current fill prefix (`fill-paragraph').
+
+`M-x fill-individual-paragraphs'
+ Fill the region, considering each change of indentation as
+ starting a new paragraph.
+
+ To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
+off the fill prefix, specify an empty prefix: type `C-x .' with point
+at the beginning of a line.
+
+ When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling. Auto Fill mode also inserts the fill prefix inserted on new
+lines it creates. Lines that do not start with the fill prefix are
+considered to start paragraphs, both in `M-q' and the paragraph
+commands; this is just right if you are using paragraphs with hanging
+indentation (every line indented except the first one). Lines which are
+blank or indented once the prefix is removed also separate or start
+paragraphs; this is what you want if you are writing multi-paragraph
+comments with a comment delimiter on each line.
+
+ The fill prefix is stored in the variable `fill-prefix'. Its value
+is a string, or `nil' when there is no fill prefix. This 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::.
+
+ Another way to use fill prefixes is through `M-x
+fill-individual-paragraphs'. This function divides the region into
+groups of consecutive lines with the same amount and kind of
+indentation and fills each group as a paragraph, using its indentation
+as a fill prefix.
-Representing Keystrokes
------------------------
+\1f
+File: xemacs.info, Node: Case, Prev: Filling, Up: Text
+
+Case Conversion Commands
+========================
+
+Emacs has commands for converting either a single word or any arbitrary
+range of text to upper case or to lower case.
+
+`M-l'
+ Convert following word to lower case (`downcase-word').
+
+`M-u'
+ Convert following word to upper case (`upcase-word').
- XEmacs represents keystrokes as lists. Each list consists of an
-arbitrary combination of modifiers followed by a single keysym at the
-end of the list. If the keysym corresponds to an ASCII character, you
-can use its character code. (A keystroke may also be represented by an
-event object, as returned by the `read-key-sequence' function;
-non-programmers need not worry about this.)
+`M-c'
+ Capitalize the following word (`capitalize-word').
- The following table gives some examples of how to list
-representations for keystrokes. Each list consists of sets of
-modifiers followed by keysyms:
+`C-x C-l'
+ Convert region to lower case (`downcase-region').
-`(control a)'
- Pressing <CTRL> and `a' simultaneously.
+`C-x C-u'
+ Convert region to upper case (`upcase-region').
-`(control ?a)'
- Another way of writing the keystroke `C-a'.
+ The word conversion commands are used most frequently. `Meta-l'
+(`downcase-word') converts the word after point to lower case, moving
+past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
+(`upcase-word') converts to all capitals instead, while `Meta-c'
+(`capitalize-word') puts the first letter of the word into upper case
+and the rest into lower case. The word conversion commands convert
+several words at once if given an argument. They are especially
+convenient for converting a large amount of text from all upper case to
+mixed case: you can move through the text using `M-l', `M-u', or `M-c'
+on each word as appropriate, occasionally using `M-f' instead to skip a
+word.
-`(control 65)'
- Yet another way of writing the keystroke `C-a'.
+ When given a negative argument, the word case conversion commands
+apply to the appropriate number of words before point, but do not move
+point. This is convenient when you have just typed a word in the wrong
+case: you can give the case conversion command and continue typing.
-`(break)'
- Pressing the <BREAK> key.
+ If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point. This is
+just like what `Meta-d' (`kill-word') does. With a negative argument,
+case conversion applies only to the part of the word before point.
-`(control meta button2up)'
- Release the middle mouse button, while pressing <CTRL> and <META>.
- Note: As you define keystrokes, you can use the `shift' key only as a
-modifier with characters that do not have a second keysym on the same
-key, such as `backspace' and `tab'. It is an error to define a
-keystroke using the <shift> modifier with keysyms such as `a' and `='.
-The correct forms are `A' and `+'.
+ The other case conversion commands are `C-x C-u' (`upcase-region')
+and `C-x C-l' (`downcase-region'), which convert everything between
+point and mark to the specified case. Point and mark do not move.
\1f
-File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
+File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
-Representing Key Sequences
---------------------------
+Editing Programs
+****************
+
+Emacs has many commands designed to understand the syntax of programming
+languages such as Lisp and C. These commands can:
+
+ * Move over or kill balanced expressions or "sexps" (*note Lists::).
+
+ * Move over or mark top-level balanced expressions ("defuns", in
+ Lisp; functions, in C).
- A "complete key sequence" is a sequence of keystrokes that Emacs
-understands as a unit. Key sequences are significant because you can
-bind them to commands. Note that not all sequences of keystrokes are
-possible key sequences. In particular, the initial keystrokes in a key
-sequence must make up a "prefix key sequence".
+ * Show how parentheses balance (*note Matching::).
- Emacs represents a key sequence as a vector of keystrokes. Thus, the
-schematic representation of a complete key sequence is as follows:
+ * Insert, kill, or align comments (*note Comments::).
- [(modifier .. modifer keysym) ... (modifier .. modifier keysym)]
+ * Follow the usual indentation conventions of the language (*note
+ Grinding::).
- Here are some examples of complete key sequences:
+ The commands available for words, sentences, and paragraphs are
+useful in editing code even though their canonical application is for
+editing human language text. Most symbols contain words (*note
+Words::); sentences can be found in strings and comments (*note
+Sentences::). Paragraphs per se are not present in code, but the
+paragraph commands are useful anyway, because Lisp mode and C mode
+define paragraphs to begin and end at blank lines (*note Paragraphs::).
+Judicious use of blank lines to make the program clearer also provides
+interesting chunks of text for the paragraph commands to work on.
-`[(control c) (control a)]'
- Typing `C-c' followed by `C-a'
+ The selective display feature is useful for looking at the overall
+structure of a function (*note Selective Display::). This feature
+causes only the lines that are indented less than a specified amount to
+appear on the screen.
-`[(control c) (control 65)]'
- Typing `C-c' followed by `C-a'. (Using the ASCII code for the
- character `a')
+* Menu:
+
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+ There are editing commands to operate on them.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Grinding:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, filling and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Lisp Completion:: Completion on symbol names in Lisp code.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
+
+\1f
+File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
+
+Major Modes for Programming Languages
+=====================================
+
+Emacs has several major modes for the programming languages Lisp,
+Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
+mode should be implemented for each programming language you might want
+to edit with Emacs; but often the mode for one language can serve for
+other syntactically similar languages. The language modes that exist
+are those that someone decided to take the trouble to write.
+
+ There are several variants of Lisp mode, which differ in the way they
+interface to Lisp execution. *Note Lisp Modes::.
+
+ Each of the programming language modes defines the <TAB> key to run
+an indentation function that knows the indentation conventions of that
+language and updates the current line's indentation accordingly. For
+example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
+normally defined to do <RET> followed by <TAB>; thus it, too, indents
+in a mode-specific fashion.
+
+ In most programming languages, indentation is likely to vary from
+line to line. So the major modes for those languages rebind <DEL> to
+treat a tab as if it were the equivalent number of spaces (using the
+command `backward-delete-char-untabify'). This makes it possible to
+rub out indentation one column at a time without worrying whether it is
+made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
+tab character before point.
+
+ Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful. Auto Fill
+mode, if enabled in a programming language major mode, indents the new
+lines which it creates.
+
+ Turning on a major mode calls a user-supplied function called the
+"mode hook", which is the value of a Lisp variable. For example,
+turning on C mode calls the value of the variable `c-mode-hook' if that
+value exists and is non-`nil'. Mode hook variables for other
+programming language modes include `lisp-mode-hook',
+`emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
+`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
+receives no arguments.
-`[(control c) (break)]'
- Typing `C-c' followed by the `break' character.
+\1f
+File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
+
+Lists and Sexps
+===============
+
+By convention, Emacs keys for dealing with balanced expressions are
+usually `Control-Meta-' characters. They tend to be analogous in
+function to their `Control-' and `Meta-' equivalents. These commands
+are usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including English).
+
+ The commands fall into two classes. Some commands deal only with
+"lists" (parenthetical groupings). They see nothing except
+parentheses, brackets, braces (depending on what must balance in the
+language you are working with), and escape characters that might be used
+to quote those.
+
+ The other commands deal with expressions or "sexps". The word `sexp'
+is derived from "s-expression", the term for a symbolic expression in
+Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
+refers to an expression in the language your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+ Sexps typically include symbols, numbers, and string constants, as
+well as anything contained in parentheses, brackets, or braces.
+
+ In languages that use prefix and infix operators, such as C, it is
+not possible for all expressions to be sexps. For example, C mode does
+not recognize `foo + bar' as an sexp, even though it is a C expression;
+it recognizes `foo' as one sexp and `bar' as another, with the `+' as
+punctuation between them. This is a fundamental ambiguity: both `foo +
+bar' and `foo' are legitimate choices for the sexp to move over if
+point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
+
+ Some languages have obscure forms of syntax for expressions that
+nobody has bothered to make Emacs understand properly.
+
+`C-M-f'
+ Move forward over an sexp (`forward-sexp').
+
+`C-M-b'
+ Move backward over an sexp (`backward-sexp').
+
+`C-M-k'
+ Kill sexp forward (`kill-sexp').
+
+`C-M-u'
+ Move up and backward in list structure (`backward-up-list').
+
+`C-M-d'
+ Move down and forward in list structure (`down-list').
+
+`C-M-n'
+ Move forward over a list (`forward-list').
+
+`C-M-p'
+ Move backward over a list (`backward-list').
+
+`C-M-t'
+ Transpose expressions (`transpose-sexps').
+
+`C-M-@'
+ Put mark after following expression (`mark-sexp').
+
+ To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
+first significant character after point is an opening delimiter (`(' in
+Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
+delimiter. If the character begins a symbol, string, or number,
+`C-M-f' moves over that. If the character after point is a closing
+delimiter, `C-M-f' just moves past it. (This last is not really moving
+across an sexp; it is an exception which is included in the definition
+of `C-M-f' because it is as useful a behavior as anyone can think of
+for that situation.)
+
+ The command `C-M-b' (`backward-sexp') moves backward over a sexp.
+The detailed rules are like those above for `C-M-f', but with
+directions reversed. If there are any prefix characters (single quote,
+back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
+over them as well.
+
+ `C-M-f' or `C-M-b' with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+ In languages such as C where the comment-terminator can be
+recognized, the sexp commands move across comments as if they were
+whitespace. In Lisp and other languages where comments run until the
+end of a line, it is very difficult to ignore comments when parsing
+backwards; therefore, in such languages the sexp commands treat the
+text of comments as if it were code.
+
+ Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
+`C-M-k' kills the characters that `C-M-f' would move over.
+
+ The "list commands", `C-M-n' (`forward-list') and `C-M-p'
+(`backward-list'), move over lists like the sexp commands but skip over
+any number of other kinds of sexps (symbols, strings, etc). In some
+situations, these commands are useful because they usually ignore
+comments, since the comments usually do not contain any lists.
+
+ `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
+is possible. To move up one (or N) levels, use `C-M-u'
+(`backward-up-list'). `C-M-u' moves backward up past one unmatched
+opening delimiter. A positive argument serves as a repeat count; a
+negative argument reverses direction of motion and also requests
+repetition, so it moves forward and up one or more levels.
+
+ To move down in list structure, use `C-M-d' (`down-list'). In Lisp
+mode, where `(' is the only opening delimiter, this is nearly the same
+as searching for a `('. An argument specifies the number of levels of
+parentheses to go down.
+
+ `C-M-t' (`transpose-sexps') drags the previous sexp across the next
+one. An argument serves as a repeat count, and a negative argument
+drags backwards (thus canceling out the effect of `C-M-t' with a
+positive argument). An argument of zero, rather than doing nothing,
+transposes the sexps ending after point and the mark.
+
+ To make the region be the next sexp in the buffer, use `C-M-@'
+(`mark-sexp') which sets the mark at the same place that `C-M-f' would
+move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
+negative argument is useful for putting the mark at the beginning of
+the previous sexp.
+
+ The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table. Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+*Note Syntax::.
- A "prefix key sequence" is the beginning of a series of longer
-sequences that are valid key sequences; adding any single keystroke to
-the end of a prefix results in a valid key sequence. For example,
-`control-x' is standardly defined as a prefix. Thus there is a
-two-character key sequence starting with `C-x' for each valid
-keystroke, giving numerous possibilities. Here are some samples:
+\1f
+File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
+
+Defuns
+======
+
+In Emacs, a parenthetical grouping at the top level in the buffer is
+called a "defun". The name derives from the fact that most top-level
+lists in Lisp are instances of the special form `defun', but Emacs
+calls any top-level parenthetical grouping counts a defun regardless of
+its contents or the programming language. For example, in C, the body
+of a function definition is a defun.
+
+`C-M-a'
+ Move to beginning of current or preceding defun
+ (`beginning-of-defun').
+
+`C-M-e'
+ Move to end of current or following defun (`end-of-defun').
+
+`C-M-h'
+ Put region around whole current or following defun (`mark-defun').
+
+ The commands to move to the beginning and end of the current defun
+are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
+
+ To operate on the current defun, use `C-M-h' (`mark-defun') which
+puts point at the beginning and the mark at the end of the current or
+next defun. This is the easiest way to prepare for moving the defun to
+a different place. In C mode, `C-M-h' runs the function
+`mark-c-function', which is almost the same as `mark-defun', but which
+backs up over the argument declarations, function name, and returned
+data type so that the entire C function is inside the region.
+
+ To compile and evaluate the current defun, use `M-x compile-defun'.
+This function prints the results in the minibuffer. If you include an
+argument, it inserts the value in the current buffer after the defun.
+
+ Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun. Therefore, never put an open-parenthesis at
+the left margin in a Lisp file unless it is the start of a top level
+list. Never put an open-brace or other opening delimiter at the
+beginning of a line of C code unless it starts the body of a function.
+The most likely problem case is when you want an opening delimiter at
+the start of a line inside a string. To avoid trouble, put an escape
+character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
+before the opening delimiter. It will not affect the contents of the
+string.
+
+ The original Emacs found defuns by moving upward a level of
+parentheses until there were no more levels to go up. This required
+scanning back to the beginning of the buffer for every function. To
+speed this up, Emacs was changed to assume that any `(' (or other
+character assigned the syntactic class of opening-delimiter) at the
+left margin is the start of a defun. This heuristic is nearly always
+right; however, it mandates the convention described above.
- * `[(control x) (c)]'
+\1f
+File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
- * `[(control x) (control c)]'
+Indentation for Programs
+========================
- Adding one character to a prefix key does not have to form a complete
-key. It could make another, longer prefix. For example, `[(control x)
-(\4)]' is itself a prefix that leads to any number of different
-three-character keys, including `[(control x) (\4) (f)]', `[(control x)
-(\4) (b)]' and so on. It would be possible to define one of those
-three-character sequences as a prefix, creating a series of
-four-character keys, but we did not define any of them this way.
+The best way to keep a program properly indented ("ground") is to use
+Emacs to re-indent it as you change the program. Emacs has commands to
+indent properly either a single line, a specified number of lines, or
+all of the lines inside a single parenthetical grouping.
- By contrast, the two-character sequence `[(control f) (control k)]'
-is not a key, because the `(control f)' is a complete key sequence in
-itself. You cannot give `[(control f (control k)]' an independent
-meaning as a command while `(control f)' is a complete sequence,
-because Emacs would understand <C-f C-k> as two commands.
+* Menu:
- The predefined prefix key sequences in Emacs are `(control c)',
-`(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
-can customize Emacs and could make new prefix keys or eliminate the
-default key sequences. *Note Key Bindings::. For example, if you
-redefine `(control f)' as a prefix, `[(control f) (control k)]'
-automatically becomes a valid key sequence (complete, unless you define
-it as a prefix as well). Conversely, if you remove the prefix
-definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
-`[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
+* Basic Indent::
+* Multi-line Indent:: Commands to reindent many lines at once.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Choosing an indentation style for C code.
- Note that the above paragraphs uses \4 instead of simply 4, because
-\4 is the symbol whose name is "4", and plain 4 is the integer 4, which
-would have been interpreted as the ASCII value. Another way of
-representing the symbol whose name is "4" is to write ?4, which would be
-interpreted as the number 52, which is the ASCII code for the character
-"4". We could therefore actually have written 52 directly, but that is
-far less clear.
+\1f
+File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
+
+Basic Program Indentation Commands
+----------------------------------
+
+`<TAB>'
+ Adjust indentation of current line.
+
+`<LFD>'
+ Equivalent to <RET> followed by <TAB> (`newline-and-indent').
+
+ The basic indentation command is <TAB>, which gives the current line
+the correct indentation as determined from the previous lines. The
+function that <TAB> runs depends on the major mode; it is
+`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
+functions understand different syntaxes for different languages, but
+they all do about the same thing. <TAB> in any programming language
+major mode inserts or deletes whitespace at the beginning of the
+current line, independent of where point is in the line. If point is
+inside the whitespace at the beginning of the line, <TAB> leaves it at
+the end of that whitespace; otherwise, <TAB> leaves point fixed with
+respect to the characters around it.
+
+ Use `C-q <TAB>' to insert a tab at point.
+
+ When entering a large amount of new code, use <LFD>
+(`newline-and-indent'), which is equivalent to a <RET> followed by a
+<TAB>. <LFD> creates a blank line, then gives it the appropriate
+indentation.
+
+ <TAB> indents the second and following lines of the body of a
+parenthetical grouping each under the preceding one; therefore, if you
+alter one line's indentation to be nonstandard, the lines below tend to
+follow it. This is the right behavior in cases where the standard
+result of <TAB> does not look good.
+
+ Remember that Emacs assumes that an open-parenthesis, open-brace, or
+other opening delimiter at the left margin (including the indentation
+routines) is the start of a function. You should therefore never have
+an opening delimiter in column zero that is not the beginning of a
+function, not even inside a string. This restriction is vital for
+making the indentation commands fast. *Note Defuns::, for more
+information on this behavior.
\1f
-File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
+File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
-String Key Sequences
---------------------
+Indenting Several Lines
+-----------------------
+
+Several commands are available to re-indent several lines of code which
+have been altered or moved to a different level in a list structure.
- For backward compatibility, you may also represent a key sequence
-using strings. For example, we have the following equivalent
-representations:
+`C-M-q'
+ Re-indent all the lines within one list (`indent-sexp').
-`"\C-c\C-c"'
- `[(control c) (control c)]'
+`C-u <TAB>'
+ Shift an entire list rigidly sideways so that its first line is
+ properly indented.
-`"\e\C-c"'
- `[(meta control c)]'
+`C-M-\'
+ Re-indent all lines in the region (`indent-region').
+
+ To re-indent the contents of a single list, position point before the
+beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
+Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
+functions in other modes. The indentation of the line the sexp starts
+on is not changed; therefore, only the relative indentation within the
+list, and not its position, is changed. To correct the position as
+well, type a <TAB> before `C-M-q'.
+
+ If the relative indentation within a list is correct but the
+indentation of its beginning is not, go to the line on which the list
+begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
+it moves all the lines in the group, starting on the current line,
+sideways the same amount that the current line moves. The command does
+not move lines that start inside strings, or C preprocessor lines when
+in C mode.
+
+ Another way to specify a range to be re-indented is with point and
+mark. The command `C-M-\' (`indent-region') applies <TAB> to every
+line whose first character is between point and mark.
\1f
-File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
+File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
-Assignment of the <META> Key
+Customizing Lisp Indentation
----------------------------
- Not all terminals have the complete set of modifiers. Terminals
-that have a <Meta> key allow you to type Meta characters by just
-holding that key down. To type `Meta-a', hold down <META> and press
-`a'. On those terminals, the <META> key works like the <SHIFT> key.
-Such a key is not always labeled <META>, however, as this function is
-often a special option for a key with some other primary purpose.
+The indentation pattern for a Lisp expression can depend on the function
+called by the expression. For each Lisp function, you can choose among
+several predefined patterns of indentation, or define an arbitrary one
+with a Lisp program.
+
+ The standard pattern of indentation is as follows: the second line
+of the expression is indented under the first argument, if that is on
+the same line as the beginning of the expression; otherwise, the second
+line is indented underneath the function name. Each following line is
+indented under the previous line whose nesting depth is the same.
+
+ If the variable `lisp-indent-offset' is non-`nil', it overrides the
+usual indentation pattern for the second line of an expression, so that
+such lines are always indented `lisp-indent-offset' more columns than
+the containing list.
+
+ Certain functions override the standard pattern. Functions whose
+names start with `def' always indent the second line by
+`lisp-body-indention' extra columns beyond the open-parenthesis
+starting the expression.
+
+ Individual functions can override the standard pattern in various
+ways, according to the `lisp-indent-function' property of the function
+name. (Note: `lisp-indent-function' was formerly called
+`lisp-indent-hook'). There are four possibilities for this property:
+
+`nil'
+ This is the same as no property; the standard indentation pattern
+ is used.
+
+`defun'
+ The pattern used for function names that start with `def' is used
+ for this function also.
+
+a number, NUMBER
+ The first NUMBER arguments of the function are "distinguished"
+ arguments; the rest are considered the "body" of the expression.
+ A line in the expression is indented according to whether the
+ first argument on it is distinguished or not. If the argument is
+ part of the body, the line is indented `lisp-body-indent' more
+ columns than the open-parenthesis starting the containing
+ expression. If the argument is distinguished and is either the
+ first or second argument, it is indented twice that many extra
+ columns. If the argument is distinguished and not the first or
+ second argument, the standard pattern is followed for that line.
+
+a symbol, SYMBOL
+ SYMBOL should be a function name; that function is called to
+ calculate the indentation of a line within this expression. The
+ function receives two arguments:
+ STATE
+ The value returned by `parse-partial-sexp' (a Lisp primitive
+ for indentation and nesting computation) when it parses up to
+ the beginning of this line.
+
+ POS
+ The position at which the line being indented begins.
+
+ It should return either a number, which is the number of columns of
+ indentation for that line, or a list whose first element is such a
+ number. The difference between returning a number and returning a
+ list is that a number says that all following lines at the same
+ nesting level should be indented just like this one; a list says
+ that following lines might call for different indentations. This
+ makes a difference when the indentation is computed by `C-M-q'; if
+ the value is a number, `C-M-q' need not recalculate indentation
+ for the following lines until the end of the list.
+
+\1f
+File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
+
+Customizing C Indentation
+-------------------------
+
+Two variables control which commands perform C indentation and when.
+
+ If `c-auto-newline' is non-`nil', newlines are inserted both before
+and after braces that you insert and after colons and semicolons.
+Correct C indentation is done on all the lines that are made this way.
+
+ If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
+does indentation only if point is at the left margin or within the
+line's indentation. If there is non-whitespace to the left of point,
+<TAB> just inserts a tab character in the buffer. Normally, this
+variable is `nil', and <TAB> always reindents the current line.
+
+ C does not have anything analogous to particular function names for
+which special forms of indentation are desirable. However, it has a
+different need for customization facilities: many different styles of C
+indentation are in common use.
+
+ There are six variables you can set to control the style that Emacs C
+mode will use.
+
+`c-indent-level'
+ Indentation of C statements within surrounding block. The
+ surrounding block's indentation is the indentation of the line on
+ which the open-brace appears.
+
+`c-continued-statement-offset'
+ Extra indentation given to a substatement, such as the then-clause
+ of an `if' or body of a `while'.
+
+`c-brace-offset'
+ Extra indentation for lines that start with an open brace.
+
+`c-brace-imaginary-offset'
+ An open brace following other text is treated as if it were this
+ far to the right of the start of its line.
+
+`c-argdecl-indent'
+ Indentation level of declarations of C function arguments.
+
+`c-label-offset'
+ Extra indentation for a line that is a label, case, or default.
+
+ The variable `c-indent-level' controls the indentation for C
+statements with respect to the surrounding block. In the example:
+
+ {
+ foo ();
+
+the difference in indentation between the lines is `c-indent-level'.
+Its standard value is 2.
+
+ If the open-brace beginning the compound statement is not at the
+beginning of its line, the `c-indent-level' is added to the indentation
+of the line, not the column of the open-brace. For example,
+
+ if (losing) {
+ do_this ();
+
+One popular indentation style is that which results from setting
+`c-indent-level' to 8 and putting open-braces at the end of a line in
+this way. Another popular style prefers to put the open-brace on a
+separate line.
+
+ In fact, the value of the variable `c-brace-imaginary-offset' is
+also added to the indentation of such a statement. Normally this
+variable is zero. Think of this variable as the imaginary position of
+the open brace, relative to the first non-blank character on the line.
+By setting the variable to 4 and `c-indent-level' to 0, you can get
+this style:
+
+ if (x == y) {
+ do_it ();
+ }
+
+ When `c-indent-level' is zero, the statements inside most braces
+line up exactly under the open brace. An exception are braces in column
+zero, like those surrounding a function's body. The statements inside
+those braces are not placed at column zero. Instead, `c-brace-offset'
+and `c-continued-statement-offset' (see below) are added to produce a
+typical offset between brace levels, and the statements are indented
+that far.
+
+ `c-continued-statement-offset' controls the extra indentation for a
+line that starts within a statement (but not within parentheses or
+brackets). These lines are usually statements inside other statements,
+like the then-clauses of `if' statements and the bodies of `while'
+statements. The `c-continued-statement-offset' parameter determines
+the difference in indentation between the two lines in:
+
+ if (x == y)
+ do_it ();
+
+The default value for `c-continued-statement-offset' is 2. Some
+popular indentation styles correspond to a value of zero for
+`c-continued-statement-offset'.
+
+ `c-brace-offset' is the extra indentation given to a line that
+starts with an open-brace. Its standard value is zero; compare:
+
+ if (x == y)
+ {
+
+with:
- If there is no <META> key, you can still type Meta characters using
-two-character sequences starting with <ESC>. To enter `M-a', you could
-type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
-allowed on terminals with Meta keys, too, in case you have formed a
-habit of using it.
+ if (x == y)
+ do_it ();
- If you are running under X and do not have a <META> key, it is
-possible to reconfigure some other key to be a <META> key. *Note Super
-and Hyper Keys::.
+If you set `c-brace-offset' to 4, the first example becomes:
- Emacs believes the terminal has a <META> key if the variable
-`meta-flag' is non-`nil'. Normally this is set automatically according
-to the termcap entry for your terminal type. However, sometimes the
-termcap entry is wrong, and then it is useful to set this variable
-yourself. *Note Variables::, for how to do this.
+ if (x == y)
+ {
- Note: If you are running under the X window system, the setting of
-the `meta-flag' variable is irrelevant.
+ `c-argdecl-indent' controls the indentation of declarations of the
+arguments of a C function. It is absolute: argument declarations
+receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
+results in code like this:
+
+ char *
+ index (string, char)
+ char *string;
+ int char;
+
+ `c-label-offset' is the extra indentation given to a line that
+contains a label, a case statement, or a `default:' statement. Its
+standard value is -2 and results in code like this:
+
+ switch (c)
+ {
+ case 'x':
+
+If `c-label-offset' were zero, the same code would be indented as:
+
+ switch (c)
+ {
+ case 'x':
+
+This example assumes that the other variables above also have their
+default values.
+
+ Using the indentation style produced by the default settings of the
+variables just discussed and putting open braces on separate lines
+produces clear and readable files. For an example, look at any of the C
+source files of XEmacs.
\1f
-File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
+File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
+
+Automatic Display of Matching Parentheses
+=========================================
+
+The Emacs parenthesis-matching feature shows you automatically how
+parentheses match in the text. Whenever a self-inserting character that
+is a closing delimiter is typed, the cursor moves momentarily to the
+location of the matching opening delimiter, provided that is visible on
+the screen. If it is not on the screen, some text starting with that
+opening delimiter is displayed in the echo area. Either way, you see
+the grouping you are closing off.
+
+ In Lisp, automatic matching applies only to parentheses. In C, it
+also applies to braces and brackets. Emacs knows which characters to
+regard as matching delimiters based on the syntax table set by the major
+mode. *Note Syntax::.
+
+ If the opening delimiter and closing delimiter are mismatched--as in
+`[x)'--the echo area displays a warning message. The correct matches
+are specified in the syntax table.
+
+ Two variables control parenthesis matching displays.
+`blink-matching-paren' turns the feature on or off. The default is `t'
+(match display is on); `nil' turns it off.
+`blink-matching-paren-distance' specifies how many characters back
+Emacs searches to find a matching opening delimiter. If the match is
+not found in the specified region, scanning stops, and nothing is
+displayed. This prevents wasting lots of time scanning when there is no
+match. The default is 4000.
-Assignment of the <SUPER> and <HYPER> Keys
-------------------------------------------
+\1f
+File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
+
+Manipulating Comments
+=====================
+
+The comment commands insert, kill and align comments.
+
+`M-;'
+ Insert or align comment (`indent-for-comment').
+
+`C-x ;'
+ Set comment column (`set-comment-column').
+
+`C-u - C-x ;'
+ Kill comment on current line (`kill-comment').
+
+`M-<LFD>'
+ Like <RET> followed by inserting and aligning a comment
+ (`indent-new-comment-line').
+
+ The command that creates a comment is `Meta-;'
+(`indent-for-comment'). If there is no comment already on the line, a
+new comment is created and aligned at a specific column called the
+"comment column". Emacs creates the comment by inserting the string at
+the value of `comment-start'; see below. Point is left after that
+string. If the text of the line extends past the comment column,
+indentation is done to a suitable boundary (usually, at least one space
+is inserted). If the major mode has specified a string to terminate
+comments, that string is inserted after point, to keep the syntax valid.
+
+ You can also use `Meta-;' to align an existing comment. If a line
+already contains the string that starts comments, `M-;' just moves
+point after it and re-indents it to the conventional place. Exception:
+comments starting in column 0 are not moved.
+
+ Some major modes have special rules for indenting certain kinds of
+comments in certain contexts. For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column. Comments which start with three
+semicolons are supposed to start at the left margin. Emacs understands
+these conventions by indenting a double-semicolon comment using <TAB>
+and by not changing the indentation of a triple-semicolon comment at
+all.
+
+ ;; This function is just an example.
+ ;;; Here either two or three semicolons are appropriate.
+ (defun foo (x)
+ ;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+
+ In C code, a comment preceded on its line by nothing but whitespace
+is indented like a line of code.
+
+ Even when an existing comment is properly aligned, `M-;' is still
+useful for moving directly to the start of the comment.
+
+ `C-u - C-x ;' (`kill-comment') kills the comment on the current
+line, if there is one. The indentation before the start of the comment
+is killed as well. If there does not appear to be a comment in the
+line, nothing happens. To reinsert the comment on another line, move
+to the end of that line, type first `C-y', and then `M-;' to realign
+the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
+;' (`set-comment-column') with a negative argument. That command is
+programmed to call `kill-comment' when called with a negative argument.
+However, `kill-comment' is a valid command which you could bind
+directly to a key if you wanted to.
+
+Multiple Lines of Comments
+--------------------------
- Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
-keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
-to bind keys to sequences using `super' and `hyper'. You can use the
-`xmodmap' program to do this.
-
- For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
-following:
-
- Create a file called `~/.xmodmap'. In this file, place the lines
-
- remove Lock = Caps_Lock
- keysym Caps_Lock = Super_L
- add Mod2 = Super_L
-
- The first line says that the key that is currently called `Caps_Lock'
-should no longer behave as a "lock" key. The second line says that
-this should now be called `Super_L' instead. The third line says that
-the key called `Super_L' should be a modifier key, which produces the
-`Mod2' modifier.
-
- To create a <META> or <HYPER> key instead of a <SUPER> key, replace
-the word `Super' above with `Meta' or `Hyper'.
-
- Just after you start up X, execute the command `xmodmap /.xmodmap'.
-You can add this command to the appropriate initialization file to have
-the command executed automatically.
-
- If you have problems, see the documentation for the `xmodmap'
-program. The X keyboard model is quite complicated, and explaining it
-is beyond the scope of this manual. However, we reprint the following
-description from the X Protocol document for your convenience:
-
- A list of keysyms is associated with each keycode. If that list
-(ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
-list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
-the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
-`K1 K2', then the list is treated as if it were the list ```K1 K2 K1
-K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
-of keysyms `K1 K2 K3', then the list is treated as if it were the list
-```K1 K2 K3 NoSymbol'''.
-
- The first four elements of the list are split into two groups of
-keysyms. Group 1 contains the first and second keysyms; Group 2 contains
-third and fourth keysyms. Within each group, if the second element of
-the group is NoSymbol, then the group should be treated as if the second
-element were the same as the first element, except when the first
-element is an alphabetic keysym `K' for which both lowercase and
-uppercase forms are defined. In that case, the group should be treated
-as if the first element were the lowercase form of `K' and the second
-element were the uppercase form of `K'.
-
- The standard rules for obtaining a keysym from a KeyPress event make
-use of only the Group 1 and Group 2 keysyms; no interpretation of other
-keysyms in the list is given here. (That is, the last four keysyms are
-unused.)
-
- Which group to use is determined by modifier state. Switching between
-groups is controlled by the keysym named `Mode_switch'. Attach that
-keysym to some keycode and attach that keycode to any one of the
-modifiers Mod1 through Mod5. This modifier is called the "group
-modifier". For any keycode, Group 1 is used when the group modifier is
-off, and Group 2 is used when the group modifier is on.
-
- Within a group, which keysym to use is also determined by modifier
-state. The first keysym is used when the `Shift' and `Lock' modifiers
-are off. The second keysym is used when the `Shift' modifier is on, or
-when the `Lock' modifier is on and the second keysym is uppercase
-alphabetic, or when the `Lock' modifier is on and is interpreted as
-`ShiftLock'. Otherwise, when the `Lock' modifier is on and is
-interpreted as `CapsLock', the state of the `Shift' modifier is applied
-first to select a keysym, but if that keysym is lower-case alphabetic,
-then the corresponding upper-case keysym is used instead.
-
- In addition to the above information on keysyms, we also provide the
-following description of modifier mapping from the InterClient
-Communications Conventions Manual:
-
- X11 supports 8 modifier bits, of which 3 are pre-assigned to
-`Shift', `Lock', and `Control'. Each modifier bit is controlled by the
-state of a set of keys, and these sets are specified in a table
-accessed by `GetModifierMapping()' and `SetModifierMapping()'.
-
- A client needing to use one of the pre-assigned modifiers should
-assume that the modifier table has been set up correctly to control
-these modifiers. The `Lock' modifier should be interpreted as `Caps
-Lock' or `Shift Lock' according to whether the keycodes in its
-controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
-
- Clients should determine the meaning of a modifier bit from the
-keysyms being used to control it.
-
- A client needing to use an extra modifier, for example `Meta',
-should:
-
- 1. Scan the existing modifier mappings.
-
- 1. If it finds a modifier that contains a keycode whose set of
- keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
- that modifier bit.
-
- 2. If there is no existing modifier controlled by `XK_Meta_L' or
- `XK_Meta_R', it should select an unused modifier bit (one with
- an empty controlling set) and:
-
- 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
- that keycode to the set for the chosen modifier, and then:
-
- 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
- add that keycode to the set for the chosen modifier, and then:
-
- 2. If the controlling set is still empty, interact with the user
- to select one or more keys to be `Meta'.
-
- 3. If there are no unused modifier bits, ask the user to take
- corrective action.
-
- This means that the `Mod1' modifier does not necessarily mean
-`Meta', although some applications (such as twm and emacs 18) assume
-that. Any of the five unassigned modifier bits could mean `Meta'; what
-matters is that a modifier bit is generated by a keycode which is bound
-to the keysym `Meta_L' or `Meta_R'.
-
- Therefore, if you want to make a <META> key, the right way is to
-make the keycode in question generate both a `Meta' keysym and some
-previously-unassigned modifier bit.
-
-\1f
-File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
-
-Representation of Characters
-============================
+If you are typing a comment and want to continue it on another line,
+use the command `Meta-<LFD>' (`indent-new-comment-line'), which
+terminates the comment you are typing, creates a new blank line
+afterward, and begins a new comment indented under the old one. If
+Auto Fill mode is on and you go past the fill column while typing, the
+comment is continued in just this fashion. If point is not at the end
+of the line when you type `M-<LFD>', the text on the rest of the line
+becomes part of the new comment line.
+
+Options Controlling Comments
+----------------------------
+
+The comment column is stored in the variable `comment-column'. You can
+explicitly set it to a number. Alternatively, the command `C-x ;'
+(`set-comment-column') sets the comment column to the column point is
+at. `C-u C-x ;' sets the comment column to match the last comment
+before point in the buffer, and then calls `Meta-;' to align the
+current line's comment under the previous one. Note that `C-u - C-x ;'
+runs the function `kill-comment' as described above.
+
+ `comment-column' is a per-buffer variable; altering the variable
+affects only the current buffer. You can also change the default value.
+*Note Locals::. Many major modes initialize this variable for the
+current buffer.
+
+ The comment commands recognize comments based on the regular
+expression that is the value of the variable `comment-start-skip'.
+This regexp should not match the null string. It may match more than
+the comment starting delimiter in the strictest sense of the word; for
+example, in C mode the value of the variable is `"/\\*+ *"', which
+matches extra stars and spaces after the `/*' itself. (Note that `\\'
+is needed in Lisp syntax to include a `\' in the string, which is needed
+to deny the first star its special meaning in regexp syntax. *Note
+Regexps::.)
+
+ When a comment command makes a new comment, it inserts the value of
+`comment-start' to begin it. The value of `comment-end' is inserted
+after point and will follow the text you will insert into the comment.
+In C mode, `comment-start' has the value `"/* "' and `comment-end' has
+the value `" */"'.
+
+ `comment-multi-line' controls how `M-<LFD>'
+(`indent-new-comment-line') behaves when used inside a comment. If
+`comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
+terminates the comment on the starting line and starts a new comment on
+the new following line. If `comment-multi-line' is not `nil', then
+`M-<LFD>' sets up the new following line as part of the same comment
+that was found on the starting line. This is done by not inserting a
+terminator on the old line and not inserting a starter on the new line.
+In languages where multi-line comments are legal, the value you choose
+for this variable is a matter of taste.
+
+ The variable `comment-indent-hook' should contain a function that is
+called to compute the indentation for a newly inserted comment or for
+aligning an existing comment. Major modes set this variable
+differently. The function is called with no arguments, but with point
+at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted. The function should return the column in
+which the comment ought to start. For example, in Lisp mode, the
+indent hook function bases its decision on the number of semicolons
+that begin an existing comment and on the code in the preceding lines.
+
+\1f
+File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
- This section briefly discusses how characters are represented in
-Emacs buffers. *Note Key Sequences::, for information on representing
-key sequences to create key bindings.
+Editing Without Unbalanced Parentheses
+======================================
+
+`M-('
+ Put parentheses around next sexp(s) (`insert-parentheses').
- ASCII graphic characters in Emacs buffers are displayed with their
-graphics. <LFD> is the same as a newline character; it is displayed by
-starting a new line. <TAB> is displayed by moving to the next tab stop
-column (usually every 8 spaces). Other control characters are
-displayed as a caret (`^') followed by the non-control version of the
-character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
-and up are displayed with octal escape sequences; thus, character code
-243 (octal), also called `M-#' when used as an input character, is
-displayed as `\243'.
+`M-)'
+ Move past next close parenthesis and re-indent
+ (`move-over-close-and-reindent').
- The variable `ctl-arrow' may be used to alter this behavior. *Note
-Display Vars::.
+ The commands `M-(' (`insert-parentheses') and `M-)'
+(`move-over-close-and-reindent') are designed to facilitate a style of
+editing which keeps parentheses balanced at all times. `M-(' inserts a
+pair of parentheses, either together as in `()', or, if given an
+argument, around the next several sexps, and leaves point after the open
+parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
+which has the same effect except for leaving the cursor before the
+close parenthesis. You can then type `M-)', which moves past the close
+parenthesis, deletes any indentation preceding it (in this example
+there is none), and indents with <LFD> after it.
\1f
-File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
+File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
-Keys and Commands
-=================
+Completion for Lisp Symbols
+===========================
+
+Completion usually happens in the minibuffer. An exception is
+completion for Lisp symbol names, which is available in all buffers.
+
+ The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
+Lisp symbol before point to be an abbreviation, and compares it against
+all non-trivial Lisp symbols currently known to Emacs. Any additional
+characters that they all have in common are inserted at point.
+Non-trivial symbols are those that have function definitions, values, or
+properties.
+
+ If there is an open-parenthesis immediately before the beginning of
+the partial symbol, only symbols with function definitions are
+considered as completions.
+
+ If the partial name in the buffer has more than one possible
+completion and they have no additional characters in common, a list of
+all possible completions is displayed in another window.
+
+\1f
+File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
- This manual is full of passages that tell you what particular keys
-do. But Emacs does not assign meanings to keys directly. Instead,
-Emacs assigns meanings to "functions", and then gives keys their
-meanings by "binding" them to functions.
-
- A function is a Lisp object that can be executed as a program.
-Usually it is a Lisp symbol that has been given a function definition;
-every symbol has a name, usually made of a few English words separated
-by dashes, such as `next-line' or `forward-word'. It also has a
-"definition", which is a Lisp program. Only some functions can be the
-bindings of keys; these are functions whose definitions use
-`interactive' to specify how to call them interactively. Such
-functions are called "commands", and their names are "command names".
-More information on this subject will appear in the XEmacs Lisp
-Reference Manual.
-
- The bindings between keys and functions are recorded in various
-tables called "keymaps". *Note Key Bindings::, for more information on
-key sequences you can bind commands to. *Note Keymaps::, for
-information on creating keymaps.
-
- When we say "`C-n' moves down vertically one line" we are glossing
-over a distinction that is irrelevant in ordinary use but is vital in
-understanding how to customize Emacs. The function `next-line' is
-programmed to move down vertically. `C-n' has this effect because it
-is bound to that function. If you rebind `C-n' to the function
-`forward-word' then `C-n' will move forward by words instead.
-Rebinding keys is a common method of customization.
-
- The rest of this manual usually ignores this subtlety to keep things
-simple. To give the customizer the information needed, we often state
-the name of the command that really does the work in parentheses after
-mentioning the key that runs it. For example, we will say that "The
-command `C-n' (`next-line') moves point vertically down," meaning that
-`next-line' is a command that moves vertically down and `C-n' is a key
-that is standardly bound to it.
-
- While we are on the subject of information for customization only,
-it's a good time to tell you about "variables". Often the description
-of a command will say, "To change this, set the variable `mumble-foo'."
-A variable is a name used to remember a value. Most of the variables
-documented in this manual exist just to facilitate customization: some
-command or other part of Emacs uses the variable and behaves
-differently depending on its setting. Until you are interested in
-customizing, you can ignore the information about variables. When you
-are ready to be interested, read the basic information on variables, and
-then the information on individual variables will make sense. *Note
-Variables::.
-
-\1f
-File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
-
-XEmacs Pull-down Menus
+Documentation Commands
======================
- If you are running XEmacs under X, a menu bar on top of the Emacs
-frame provides access to pull-down menus of file, edit, and
-help-related commands. The menus provide convenient shortcuts and an
-easy interface for novice users. They do not provide additions to the
-functionality available via key commands; you can still invoke commands
-from the keyboard as in previous versions of Emacs.
+As you edit Lisp code to be run in Emacs, you can use the commands `C-h
+f' (`describe-function') and `C-h v' (`describe-variable') to print
+documentation of functions and variables you want to call. These
+commands use the minibuffer to read the name of a function or variable
+to document, and display the documentation in a window.
+
+ For extra convenience, these commands provide default arguments
+based on the code in the neighborhood of point. `C-h f' sets the
+default to the function called in the innermost list containing point.
+`C-h v' uses the symbol name around or adjacent to point as its default.
+
+ The `M-x manual-entry' command gives you access to documentation on
+Unix commands, system calls, and libraries. The command reads a topic
+as an argument, and displays the Unix manual page for that topic.
+`manual-entry' always searches all 8 sections of the manual and
+concatenates all the entries it finds. For example, the topic
+`termcap' finds the description of the termcap library from section 3,
+followed by the description of the termcap data base from section 5.
+
+\1f
+File: xemacs.info, 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 a directory.
+
+ A change log entry starts with a header line that contains your name
+and the current date. Except for 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 be indented. *Note Text Mode::.
+
+ 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.
+
+\1f
+File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
-File
- Perform file and buffer-related operations, such as opening and
- closing files, saving and printing buffers, as well as exiting
- Emacs.
+Tags Tables
+===========
-Edit
- Perform standard editing operations, such as cutting, copying,
- pasting, and killing selected text.
+A "tags 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 (or other named subunits) 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 `M-.' command which finds the
+definition of a function by looking up which of the files it is in.
-Apps
- Access to sub-applications implemented within XEmacs, such as the
- mail reader, the World Wide Web browser, the spell-checker, and
- the calendar program.
+ Tags tables are stored in files called "tags table files". The
+conventional name for a tags table file is `TAGS'.
-Options
- Control various options regarding the way XEmacs works, such as
- controlling which elements of the frame are visible, selecting the
- fonts to be used for text, specifying whether searches are
- case-sensitive, etc.
+ Each entry in the tags 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.
-Buffers
- Present a menu of buffers for selection as well as the option to
- display a buffer list.
+ Just what names from the described files are recorded in the tags
+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. Each name
+recorded is called a "tag".
-Tools
- Perform various actions designed to automate software development
- and similar technical work, such as searching through many files,
- compiling a program, and comparing or merging two or three files.
+ The Ebrowse is a separate facility tailored for C++, with tags and a
+class browser. *Note Top: (ebrowse)Top.
-Help
- Access to Emacs Info.
+* Menu:
- There are two ways of selecting an item from a pull-down menu:
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with `etags'.
+* Etags Regexps:: Create arbitrary tags using regular expressions.
+* Select Tags Table:: How to visit a tags table.
+* Find Tag:: Commands to find the definition of a specific tag.
+* Tags Search:: Using a tags table for searching and replacing.
+* List Tags:: Listing and finding tags defined in a file.
- * Select an item in the menu bar by moving the cursor over it and
- click the left mouse-button. Then move the cursor over the menu
- item you want to choose and click left again.
+\1f
+File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
- * Select an item in the menu bar by moving the cursor over it and
- click and hold the left mouse-button. With the mouse-button
- depressed, move the cursor over the menu item you want, then
- release it to make your selection.
+Source File Tag Syntax
+----------------------
- If a command in the pull-down menu is not applicable in a given
-situation, the command is disabled and its name appears faded. You
-cannot invoke items that are faded. For example, many commands on the
-Edit menu appear faded until you select text on which they are to
-operate; after you select a block of text, edit commands are enabled.
-*Note Mouse Selection::, for information on using the mouse to select
-text. *Note Using X Selections::, for related information.
+Here is how tag syntax is defined for the most popular languages:
- There are also `M-x' equivalents for each menu item. To find the
-equivalent for any left-button menu item, do the following:
+ * In C code, any C function or typedef is a tag, and so are
+ definitions of `struct', `union' and `enum'. You can tag function
+ declarations and external variables in addition to function
+ definitions by giving the `--declarations' option to `etags'.
+ `#define' macro definitions and `enum' constants are also tags,
+ unless you specify `--no-defines' when making the tags table.
+ Similarly, global variables are tags, unless you specify
+ `--no-globals'. Use of `--no-globals' and `--no-defines' can make
+ the tags table file much smaller.
- 1. Type `C-h k' to get the `Describe Key' prompt.
+ * In C++ code, in addition to all the tag constructs of C code,
+ member functions are also recognized, and optionally member
+ variables if you use the `--members' option. Tags for variables
+ and functions in classes are named `CLASS::VARIABLE' and
+ `CLASS::FUNCTION'. `operator' functions tags are named, for
+ example `operator+'.
- 2. Select the menu item and click.
+ * In Java code, tags include all the constructs recognized in C++,
+ plus the `interface', `extends' and `implements' constructs. Tags
+ for variables and functions in classes are named `CLASS.VARIABLE'
+ and `CLASS.FUNCTION'.
- Emacs displays the function associated with the menu item in a
-separate window, usually together with some documentation.
+ * In LaTeX text, the argument of any of the commands `\chapter',
+ `\section', `\subsection', `\subsubsection', `\eqno', `\label',
+ `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
+ `\index', is a tag.
-* Menu:
+ Other commands can make tags as well, if you specify them in the
+ environment variable `TEXTAGS' before invoking `etags'. The value
+ of this environment variable should be a colon-separated list of
+ command names. For example,
-* File Menu:: Items on the File menu.
-* Edit Menu:: Items on the Edit menu.
-* Apps Menu:: Items on the Apps menu.
-* Options Menu:: Items on the Options menu.
-* Buffers Menu:: Information about the Buffers menu.
-* Tools Menu:: Items on the Tools menu.
-* Help Menu:: Items on the Help menu.
-* Menu Customization:: Adding and removing menu items and related
- operations.
+ TEXTAGS="def:newcommand:newenvironment"
+ export TEXTAGS
+
+ specifies (using Bourne shell syntax) that the commands `\def',
+ `\newcommand' and `\newenvironment' also define tags.
+
+ * 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 Scheme code, tags include anything defined with `def' or with a
+ construct whose name starts with `def'. They also include
+ variables set with `set!' at top level in the file.
+
+ Several other languages are also supported:
+
+ * In Ada code, functions, procedures, packages, tasks, and types are
+ tags. Use the `--packages-only' option to create tags for
+ packages only.
+
+ With Ada, it is possible to have the same name used for different
+ entity kinds (e.g. the same name for a procedure and a function).
+ Also, for things like packages, procedures and functions, there is
+ the spec (i.e. the interface) and the body (i.e. the
+ implementation). To facilitate the choice to the user, a tag
+ value is appended with a qualifier:
+
+ function
+ `/f'
+
+ procedure
+ `/p'
+
+ package spec
+ `/s'
+
+ package body
+ `/b'
+
+ type
+ `/t'
+
+ task
+ `/k'
+
+ So, as an example, `M-x find-tag bidule/b' will go directly to the
+ body of the package BIDULE while `M-x find-tag bidule' will just
+ search for any tag BIDULE.
+
+ * In assembler code, labels appearing at the beginning of a line,
+ followed by a colon, are tags.
+
+ * In Bison or Yacc input files, each rule defines as a tag the
+ nonterminal it constructs. The portions of the file that contain
+ C code are parsed as C code.
+
+ * In Cobol code, tags are paragraph names; that is, any word
+ starting in column 8 and followed by a period.
+
+ * In Erlang code, the tags are the functions, records, and macros
+ defined in the file.
+
+ * In Fortran code, functions, subroutines and blockdata are tags.
+
+ * In makefiles, targets are tags.
+
+ * In Objective C code, tags include Objective C definitions for
+ classes, class categories, methods, and protocols.
+
+ * In Pascal code, the tags are the functions and procedures defined
+ in the file.
+
+ * In Perl code, the tags are the procedures defined by the `sub',
+ `my' and `local' keywords. Use `--globals' if you want to tag
+ global variables.
+
+ * In PostScript code, the tags are the functions.
+
+ * In Prolog code, a tag name appears at the left margin.
+
+ * In Python code, `def' or `class' at the beginning of a line
+ generate a tag.
+
+ You can also generate tags based on regexp matching (*note Etags
+Regexps::) to handle other formats and languages.
\1f
-File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
-The File Menu
--------------
+Creating Tags Tables
+--------------------
- The File menu bar item contains the items New Frame, Open File...,
-Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
-Frame, Kill Buffer and Exit Emacs on the pull-down menu. If you select
-a menu item, Emacs executes the equivalent command.
-
-Open File, New Frame...
- Prompts you for a filename and loads that file into a new buffer
- in a new Emacs frame, that is, a new X window running under the
- same Emacs process. You can remove the frame using the Delete
- Frame menu item. When you remove the last frame, you exit Emacs
- and are prompted for confirmation.
-
-Open File...
- Prompts you for a filename and loads that file into a new buffer.
- Open File... is equivalent to the Emacs command `find-file' (`C-x
- C-f').
-
-Insert File...
- Prompts you for a filename and inserts the contents of that file
- into the current buffer. The file associated with the current
- buffer is not changed by this command. This is equivalent to the
- Emacs command `insert-file' (`C-x i').
-
-Save Buffer
- Writes and saves the current Emacs buffer as the latest version of
- the current visited file. Save Buffer is equivalent to the Emacs
- command `save-buffer' (`C-x C-s').
-
-Save Buffer As...
- Writes and saves the current Emacs buffer to the filename you
- specify. Save Buffer As... is equivalent to the Emacs command
- `write-file' (`C-x C-w').
-
-Revert Buffer
- Restores the last saved version of the file to the current buffer.
- When you edit a buffer containing a text file, you must save the
- buffer before your changes become effective. Use Revert Buffer if
- you do not want to keep the changes you have made in the buffer.
- Revert Buffer is equivalent to the Emacs command `revert-file'
- (`M-x revert-buffer').
-
-Kill Buffer
- Kills the current buffer, prompting you first if there are unsaved
- changes. This is roughly equivalent to the Emacs command
- `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
- name of a buffer to kill.
-
-Print Buffer
- Prints a hardcopy of the current buffer. Equivalent to the Emacs
- command `print-buffer' (`M-x print-buffer').
-
-New Frame
- Creates a new Emacs frame displaying the `*scratch*' buffer. This
- is like the Open File, New Frame... menu item, except that it does
- not prompt for or load a file.
-
-Delete Frame
- Allows you to close all but one of the frames created by New Frame.
- If you created several Emacs frames belonging to the same Emacs
- process, you can close all but one of them. When you attempt to
- close the last frame, Emacs informs you that you are attempting to
- delete the last frame. You have to choose Exit Emacs for that.
-
-Split Frame
- Divides the current window on the current frame into two
- equal-sized windows, both displaying the same buffer. Equivalent
- to the Emacs command `split-window-vertically' (`C-x 2').
-
-Un-split (Keep This)
- If the frame is divided into multiple windows, this removes all
- windows other than the selected one. Equivalent to the Emacs
- command `delete-other-windows' (`C-x 1').
-
-Un-split (Keep Others)
- If the frame is divided into multiple windows, this removes the
- selected window from the frame, giving the space back to one of the
- other windows. Equivalent to the Emacs command `delete-window'
- (`C-x 0').
-
-Exit Emacs
- Shuts down (kills) the Emacs process. Equivalent to the Emacs
- command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
- Emacs process, the system asks which unsaved buffers to save by
- going through the list of all buffers in that Emacs process.
-
-\1f
-File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
-
-The Edit Menu
+The `etags' program is used to create a tags table file. It knows the
+syntax of several languages, as described in *Note Tag Syntax::. Here
+is how to run `etags':
+
+ etags INPUTFILES...
+
+The `etags' program reads the specified files, and writes a tags table
+named `TAGS' in the current working directory. You can intermix
+compressed and plain text source file names. `etags' knows about the
+most common compression formats, and does the right thing. So you can
+compress all your source files and have `etags' look for compressed
+versions of its file name arguments, if it does not find uncompressed
+versions. Under MS-DOS, `etags' also looks for file names like
+`mycode.cgz' if it is given `mycode.c' on the command line and
+`mycode.c' does not exist.
+
+ `etags' recognizes the language used in an input file based on its
+file name and contents. You can specify the language with the
+`--language=NAME' option, described below.
+
+ If the tags table data become outdated due to changes in the files
+described in the table, the way to update the tags table is the same
+way it was made in the first place. It is not necessary to do this
+often.
+
+ If the tags 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 tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag. 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 tags 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 tags table after each edit, or even every day.
+
+ One tags table can effectively include another. Specify the included
+tags file name with the `--include=FILE' option when creating the file
+that is to include it. The latter file then acts as if it contained
+all the files specified in the included file, as well as the files it
+directly contains.
+
+ If you specify the source files with relative file names when you run
+`etags', the tags file will contain file names relative to the
+directory where the tags file was initially written. This way, you can
+move an entire directory tree containing both the tags file and the
+source files, and the tags file will still refer correctly to the source
+files.
+
+ If you specify absolute file names as arguments to `etags', then the
+tags file will contain absolute file names. This way, the tags file
+will still refer to the same files even if you move it, as long as the
+source files remain in the same place. Absolute file names start with
+`/', or with `DEVICE:/' on MS-DOS and MS-Windows.
+
+ When you want to make a tags table from a great number of files, you
+may have problems listing them on the command line, because some systems
+have a limit on its length. The simplest way to circumvent this limit
+is to tell `etags' to read the file names from its standard input, by
+typing a dash in place of the file names, like this:
+
+ find . -name "*.[chCH]" -print | etags -
+
+ Use the option `--language=NAME' to specify the language explicitly.
+You can intermix these options with file names; each one applies to
+the file names that follow it. Specify `--language=auto' to tell
+`etags' to resume guessing the language from the file names and file
+contents. Specify `--language=none' to turn off language-specific
+processing entirely; then `etags' recognizes tags by regexp matching
+alone (*note Etags Regexps::).
+
+ `etags --help' prints the list of the languages `etags' knows, and
+the file name rules for guessing the language. It also prints a list of
+all the available `etags' options, together with a short explanation.
+
+\1f
+File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
+
+Etags Regexps
-------------
- The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
-Clear menu items. When you select a menu item, Emacs executes the
-equivalent command. Most commands on the Edit menu work on a block of
-text, the X selection. They appear faded until you select a block of
-text (activate a region) with the mouse. *Note Using X Selections::,
-*note Killing::, and *note Yanking:: for more information.
-
-Undo
- Undoes the previous command. Undo is equivalent to the Emacs
- command `undo' (`C-x u').
-
-Cut
- Removes the selected text block from the current buffer, makes it
- the X clipboard selection, and places it in the kill ring. Before
- executing this command, you have to select a region using Emacs
- region selection commands or with the mouse.
-
-Copy
- Makes a selected text block the X clipboard selection, and places
- it in the kill ring. You can select text using one of the Emacs
- region selection commands or by selecting a text region with the
- mouse.
-
-Paste
- Inserts the current value of the X clipboard selection in the
- current buffer. Note that this is not necessarily the same as the
- Emacs `yank' command, because the Emacs kill ring and the X
- clipboard selection are not the same thing. You can paste in text
- you have placed in the clipboard using Copy or Cut. You can also
- use Paste to insert text that was pasted into the clipboard from
- other applications.
-
-Clear
- Removes the selected text block from the current buffer but does
- not place it in the kill ring or the X clipboard selection.
-
-Start Macro Recording
- After selecting this, Emacs will remember every keystroke you type
- until End Macro Recording is selected. This is the same as the
- Emacs command `start-kbd-macro' (`C-x (').
-
-End Macro Recording
- Selecting this tells emacs to stop remembering your keystrokes.
- This is the same as the Emacs command `end-kbd-macro' (`C-x )').
-
-Execute Last Macro
- Selecting this item will cause emacs to re-interpret all of the
- keystrokes which were saved between selections of the Start Macro
- Recording and End Macro Recording menu items. This is the same as
- the Emacs command `call-last-kbd-macro' (`C-x e').
-
-\1f
-File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
-
-The Apps Menu
+The `--regex' option provides a general way of recognizing tags based
+on regexp matching. You can freely intermix it with file names. Each
+`--regex' option adds to the preceding ones, and applies only to the
+following files. The syntax is:
+
+ --regex=/TAGREGEXP[/NAMEREGEXP]/
+
+where TAGREGEXP is used to match the lines to tag. It is always
+anchored, that is, it behaves as if preceded by `^'. If you want to
+account for indentation, just match any initial number of blanks by
+beginning your regular expression with `[ \t]*'. In the regular
+expressions, `\' quotes the next character, and `\t' stands for the tab
+character. Note that `etags' does not handle the other C escape
+sequences for special characters.
+
+ The syntax of regular expressions in `etags' is the same as in
+Emacs, augmented with the "interval operator", which works as in `grep'
+and `ed'. The syntax of an interval operator is `\{M,N\}', and its
+meaning is to match the preceding expression at least M times and up to
+N times.
+
+ You should not match more characters with TAGREGEXP than that needed
+to recognize what you want to tag. If the match is such that more
+characters than needed are unavoidably matched by TAGREGEXP (as will
+usually be the case), you should add a NAMEREGEXP, to pick out just the
+tag. This will enable Emacs to find tags more accurately and to do
+completion on tag names more reliably. You can find some examples
+below.
+
+ The option `--ignore-case-regex' (or `-c') is like `--regex', except
+that the regular expression provided will be matched without regard to
+case, which is appropriate for various programming languages.
+
+ The `-R' option deletes all the regexps defined with `--regex'
+options. It applies to the file names following it, as you can see
+from the following example:
+
+ etags --regex=/REG1/ voo.doo --regex=/REG2/ \
+ bar.ber -R --lang=lisp los.er
+
+Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
+according to their contents. `etags' also uses REG1 to recognize
+additional tags in `voo.doo', and both REG1 and REG2 to recognize
+additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
+regexp matching, to recognize tags in `los.er'.
+
+ A regular expression can be bound to a given language, by prepending
+it with `{lang}'. When you do this, `etags' will use the regular
+expression only for files of that language. `etags --help' prints the
+list of languages recognised by `etags'. The following example tags
+the `DEFVAR' macros in the Emacs source files. `etags' applies this
+regular expression to C files only:
+
+ --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+
+This feature is particularly useful when storing a list of regular
+expressions in a file. The following option syntax instructs `etags'
+to read two files of regular expressions. The regular expressions
+contained in the second file are matched without regard to case.
+
+ --regex=@first-file --ignore-case-regex=@second-file
+
+A regex file contains one regular expressions per line. Empty lines,
+and lines beginning with space or tab are ignored. When the first
+character in a line is `@', `etags' assumes that the rest of the line
+is the name of a file of regular expressions. This means that such
+files can be nested. All the other lines are taken to be regular
+expressions. For example, one can create a file called `emacs.tags'
+with the following contents (the first line in the file is a comment):
+
+ -- This is for GNU Emacs source files
+ {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+
+and then use it like this:
+
+ etags --regex=@emacs.tags *.[ch] */*.[ch]
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
+
+ * Tag Octave files:
+
+ etags --language=none \
+ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+ --regex='/###key \(.*\)/\1/' \
+ --regex='/[ \t]*global[ \t].*/' \
+ *.m
+
+ Note that tags are not generated for scripts so that you have to
+ add a line by yourself of the form `###key <script-name>' if you
+ want to jump to it.
+
+ * Tag Tcl files:
+
+ etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+
+ * Tag VHDL files:
+
+ --language=none \
+ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+
+\1f
+File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
+
+Selecting a Tags Table
+----------------------
+
+At any time Emacs has one "selected" tags table, and all the commands
+for working with tags tables use the selected one. To select a tags
+table, use the variable `tag-table-alist'.
+
+ The value of `tag-table-alist' is a list that determines which
+`TAGS' files should be active for a given buffer. This is not really
+an association list, in that all elements are checked. The car of each
+element of this list is a pattern against which the buffers file name
+is compared; if it matches, then the cdr of the list should be the name
+of the tags table to use. If more than one element of this list
+matches the buffers file name, all of the associated tags tables are
+used. Earlier ones are searched first.
+
+ If the car of elements of this list are strings, they are treated as
+regular-expressions against which the file is compared (like the
+`auto-mode-alist'). If they are not strings, they are evaluated. If
+they evaluate to non-`nil', the current buffer is considered to match.
+
+ If the cdr of the elements of this list are strings, they are
+assumed to name a tags file. If they name a directory, the string
+`tags' is appended to them to get the file name. If they are not
+strings, they are evaluated and must return an appropriate string.
+
+ For example:
+
+ (setq tag-table-alist
+ '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
+ ("\\.el$" . "/usr/local/emacs/src/")
+ ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
+ ("" . "/usr/local/emacs/src/")
+ ))
+
+ The example defines the tags table alist in the following way:
+
+ * Anything in the directory `/usr/src/public/perl/' should use the
+ `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
+
+ * Files ending in `.el' should use the `TAGS' file
+ `/usr/local/emacs/src/TAGS'.
+
+ * Anything in or below the directory `/jbw/gnu/' should use the
+ `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
+
+ If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
+files,
+`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
+that order), because it matches both patterns.
+
+ If the buffer-local variable `buffer-tag-table' is set, it names a
+tags table that is searched before all others when `find-tag' is
+executed from this buffer.
+
+ If there is a file called `TAGS' in the same directory as the file
+in question, then that tags file will always be used as well (after the
+`buffer-tag-table' but before the tables specified by this list).
+
+ If the variable `tags-file-name' is set, the `TAGS' file it names
+will apply to all buffers (for backwards compatibility.) It is searched
+first.
+
+ If the value of the variable `tags-always-build-completion-table' is
+`t', the tags file will always be added to the completion table without
+asking first, regardless of the size of the tags file.
+
+ The function `M-x visit-tags-table', is largely made obsolete by the
+variable `tag-table-alist', tells tags commands to use the tags table
+file FILE first. The FILE should be the name of a file created with
+the `etags' program. A directory name is also acceptable; it means the
+file `TAGS' in that directory. The function only stores the file name
+you provide in the variable `tags-file-name'. Emacs does not actually
+read in the tags table contents until you try to use them. You can set
+the variable explicitly instead of using `visit-tags-table'. The value
+of the variable `tags-file-name' is the name of the tags table used by
+all buffers. This is for backward compatibility, and is largely
+supplanted by the variable `tag-table-alist'.
+
+\1f
+File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
+
+Finding a Tag
-------------
- The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
-(MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
-Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
-When you select a menu item, Emacs executes the equivalent command.
-For some of the menu items, there are sub-menus which you will need to
-select.
+The most important thing that a tags table enables you to do is to find
+the definition of a specific tag.
+
+`M-. TAG &OPTIONAL OTHER-WINDOW'
+ 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 tags table for that tag, as a
+string, then uses the tags table information to determine the file in
+which the definition is used and the approximate character position of
+the definition in the file. Then `find-tag' visits the file, moves
+point to the approximate character position, and starts searching
+ever-increasing distances away for the text that should appear at the
+beginning of the definition.
+
+ If an empty argument is given (by typing <RET>), the sexp in the
+buffer before or around point is used as the name of the tag to find.
+*Note Lists::, for information 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 tags table, it finds the first tag in the
+table that the specified substring appears in. To find other tags that
+match the substring, 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 your keyboard has a real <META> key, `M-0 M-.' is an easier
+alternative to `C-u M-.'.
+
+ If the optional second argument OTHER-WINDOW is non-`nil', it uses
+another window to display the tag. Multiple active tags tables and
+completion are supported.
+
+ Variables of note include the following:
+
+`tag-table-alist'
+ Controls which tables apply to which buffers.
+
+`tags-file-name'
+ Stores a default tags table.
+
+`tags-build-completion-table'
+ Controls completion behavior.
+
+`buffer-tag-table'
+ Specifies a buffer-local table.
+
+`make-tags-files-invisible'
+ Sets whether tags tables should be very hidden.
+
+`tag-mark-stack-max'
+ Specifies how many tags-based hops to remember.
+
+ 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 tags table file `TAGS' (in the directory
+containing Lisp libraries) that 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.
\1f
-File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags
+
+Searching and Replacing with Tags Tables
+----------------------------------------
+
+The commands in this section visit and search all the files listed in
+the selected tags table, one by one. For these commands, the tags
+table serves only to specify a sequence of files to search. A related
+command is `M-x grep' (*note Compilation::).
+
+`M-x tags-search <RET> REGEXP <RET>'
+ Search for REGEXP through the files in the selected tags table.
+
+`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
+ Perform a `query-replace-regexp' on each file in the selected tags
+ 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 searches
+for matches in all the files in the selected tags table, one file at a
+time. It displays the name of the file being searched so you can
+follow its progress. As soon as it finds an occurrence, `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 tags table.
+
+ `M-x tags-query-replace' performs a single `query-replace-regexp'
+through all the files in the tags table. It reads a regexp to search
+for and a string to replace with, just like ordinary `M-x
+query-replace-regexp'. 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 tags table with a
+single invocation of `M-x tags-query-replace'. But often it is useful
+to exit temporarily, which you can do with any input event that has no
+special query replace meaning. You can resume the query replace
+subsequently by typing `M-,'; this command resumes the last tags search
+or replace command that you did.
+
+ The commands in this section carry out much broader searches than the
+`find-tag' family. The `find-tag' commands search only for definitions
+of tags that match your substring or regexp. The commands
+`tags-search' and `tags-query-replace' find every occurrence of the
+regexp, as ordinary search commands and replace commands do in the
+current buffer.
+
+ These commands create buffers only temporarily for the files that
+they have to search (those which are not already visited in Emacs
+buffers). Buffers in which no match is found are quickly killed; the
+others continue to exist.
+
+ 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 much like running a
+compilation; finding the source locations of the `grep' matches works
+like finding the compilation errors. *Note Compilation::.
+
+ If you wish to process all the files in a selected tags table, but
+`M-x tags-search' and `M-x tags-query-replace' are not giving you the
+desired result, 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 tags table and prepare to advance sequentially by
+ files.
+
+`M-x next-file'
+ Visit the next file in the selected tags table.
-The Options Menu
-----------------
+\1f
+File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags
- The Options pull-down menu contains the Read Only, Case Sensitive
-Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
-Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
-Menu Length..., Buffers Sub-Menus and Save Options menu items. When
-you select a menu item, Emacs executes the equivalent command. For
-some of the menu items, there are sub-menus which you will need to
-select.
-
-Read Only
- Selecting this item will cause the buffer to visit the file in a
- read-only mode. Changes to the file will not be allowed. This is
- equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
-
-Case Sensitive Search
- Selecting this item will cause searches to be case-sensitive. If
- its not selected then searches will ignore case. This option is
- local to the buffer.
-
-Overstrike
- After selecting this item, when you type letters they will replace
- existing text on a one-to-one basis, rather than pushing it to the
- right. At the end of a line, such characters extend the line.
- Before a tab, such characters insert until the tab is filled in.
- This is the same as Emacs command `quoted-insert' (`C-q').
-
-Auto Delete Selection
- Selecting this item will cause automatic deletion of the selected
- region. The typed text will replace the selection if the selection
- is active (i.e. if its highlighted). If the option is not selected
- then the typed text is just inserted at the point.
-
-Teach Extended Commands
- After you select this item, any time you execute a command with
- `M-x'which has a shorter keybinding, you will be shown the
- alternate binding before the command executes.
-
-Syntax Highlighting
- You can customize your `.emacs' file to include the font-lock mode
- so that when you select this item, the comments will be displayed
- in one face, strings in another, reserved words in another, and so
- on. When Fonts is selected, different parts of the program will
- appear in different Fonts. When Colors is selected, then the
- program will be displayed in different colors. Selecting None
- causes the program to appear in just one Font and Color. Selecting
- Less resets the Fonts and Colors to a fast, minimal set of
- decorations. Selecting More resets the Fonts and Colors to a larger
- set of decorations. For example, if Less is selected (which is the
- default setting) then you might have all comments in green color.
- Whereas, if More is selected then a function name in the comments
- themselves might appear in a different Color or Font.
-
-Paren Highlighting
- After selecting Blink from this item, if you place the cursor on a
- parenthesis, the matching parenthesis will blink. If you select
- Highlight and place the cursor on a parenthesis, the whole
- expression of the parenthesis under the cursor will be highlighted.
- Selecting None will turn off the options (regarding Paren
- Highlighting) which you had selected earlier.
-
-Font
- You can select any Font for your program by choosing from one of
- the available Fonts.
-
-Size
- You can select any size ranging from 2 to 24 by selecting the
- appropriate option.
-
-Weight
- You can choose either Bold or Medium for the weight.
-
-Buffers Menu Length...
- Prompts you for the number of buffers to display. Then it will
- display that number of most recently selected buffers.
-
-Buffers Sub-Menus
- After selection of this item the Buffers menu will contain several
- commands, as submenus of each buffer line. If this item is
- unselected, then there are no submenus for each buffer line, the
- only command available will be selecting that buffer.
-
-Save Options
- Selecting this item will save the current settings of your Options
- menu to your `.emacs' file.
-
-\1f
-File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
-
-The Buffers Menu
-----------------
+Tags Table Inquiries
+--------------------
- The Buffers menu provides a selection of up to ten buffers and the
-item List All Buffers, which provides a Buffer List. *Note List
-Buffers::, for more information.
+`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 tags 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 tags table; it is read as a string
+rather than 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 tags table contains that directory.
+
+ `M-x tags-apropos' is like `apropos' for tags. It reads a regexp,
+then finds all the tags in the selected tags table whose entries match
+that regexp, and displays the tag names found.
\1f
-File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Fortran, Next: Asm Mode, Prev: Tags, Up: Programs
-The Tools Menu
---------------
+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 non-`nil' value.
- The Tools pull-down menu contains the Grep..., Compile..., Shell
-Command..., Shell Command on Region..., Debug(GDB)... and
-Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
-sub-menus. When you select a menu item, Emacs executes the equivalent
-command. For some of the menu items, there are sub-menus which you
-will need to select.
+* 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.
\1f
-File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran
-The Help Menu
--------------
+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, which is 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').
- The Help Menu gives you access to Emacs Info and provides a menu
-equivalent for each of the choices you have when using `C-h'. *Note
-Help::, for more information.
+`C-c C-n'
+ Move to beginning of current or next statement (`fortran-next-
+ statement').
- The Help menu also gives access to UNIX online manual pages via the
-UNIX Manual Page option.
+`C-c C-p'
+ Move to beginning of current or previous statement (`fortran-
+ previous-statement').
\1f
-File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran
-Customizing XEmacs Menus
-------------------------
+Fortran Indentation
+-------------------
- You can customize any of the pull-down menus by adding or removing
-menu items and disabling or enabling existing menu items.
+Special commands and features are available for indenting Fortran code.
+They make sure various syntactic entities (line numbers, comment line
+indicators, and continuation line flags) appear in the columns that are
+required for standard Fortran.
- The following functions are available:
-`add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
- Add a menu to the menu bar or one of its submenus.
+* 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.
+
+\1f
+File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
-`add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
- ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
- the menu first if necessary.
+Fortran Indentation Commands
+............................
-`delete-menu-item: (PATH)'
- Remove the menu item defined by PATH from the menu hierarchy.
+`<TAB>'
+ Indent the current line (`fortran-indent-line').
-`disable-menu-item: (PATH)'
- Disable the specified menu item.
+`M-<LFD>'
+ Break the current line and set up a continuation line.
-`enable-menu-item: (PATH)'
- Enable the specified previously disabled menu item.
+`C-M-q'
+ Indent all the lines of the subprogram point is in
+ (`fortran-indent-subprogram').
-`relabel-menu-item: (PATH NEW-NAME)'
- Change the string of the menu item specified by PATH to NEW-NAME.
+ <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 that reindents 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.
+
+\1f
+File: xemacs.info, 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 XEmacs.) 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 the 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.
- Use the function `add-menu' to add a new menu or submenu. If a menu
-or submenu of the given name exists already, it is changed.
+\1f
+File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
- MENU-PATH identifies the menu under which the new menu should be
-inserted. It is a list of strings; for example, `("File")' names the
-top-level File menu. `("File" "Foo")' names a hypothetical submenu of
-File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
+Syntactic Conventions
+.....................
- MENU-NAME is the string naming the menu to be added.
+Fortran mode assumes that you follow certain conventions that simplify
+the task of understanding a Fortran program well enough to indent it
+properly:
- MENU-ITEMS is a list of menu item descriptions. Each menu item
-should be a vector of three elements:
+ * Two nested `do' loops never share a `continue' statement.
- * A string, which is the name of the menu item
+ * The same character appears in column 5 of all continuation lines.
+ It is the value of the variable `fortran-continuation-char'. By
+ default, this character is `$'.
- * A symbol naming a command, or a form to evaluate
+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.
- * `t' or `nil' to indicate whether the item is selectable
+\1f
+File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
- The optional argument BEFORE is the name of the menu before which
-the new menu or submenu should be added. If the menu is already
-present, it is not moved.
+Variables for Fortran Indentation
+.................................
- The function `add-menu-item' adds a menu item to the specified menu,
-creating the menu first if necessary. If the named item already
-exists, the menu remains unchanged.
+Several additional variables control how Fortran indentation works.
- MENU-PATH identifies the menu into which the new menu item should be
-inserted. It is a list of strings; for example, `("File")' names the
-top-level File menu. `("File" "Foo")' names a hypothetical submenu of
-File.
+`fortran-do-indent'
+ Extra indentation within each level of `do' statement (the default
+ is 3).
- ITEM-NAME is the string naming the menu item to add.
+`fortran-if-indent'
+ Extra indentation within each level of `if' statement (the default
+ is 3).
- FUNCTION is the command to invoke when this menu item is selected.
-If it is a symbol, it is invoked with `call-interactively', in the same
-way that functions bound to keys are invoked. If it is a list, the
-list is simply evaluated.
+`fortran-continuation-indent'
+ Extra indentation for bodies of continuation lines (the default is
+ 5).
- ENABLED-P controls whether the item is selectable or not. It should
-be `t', `nil', or a form to evaluate to decide. This form will be
-evaluated just before the menu is displayed, and the menu item will be
-selectable if that form returns non-`nil'.
+`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'.
- For example, to make the `rename-file' command available from the
-File menu, use the following code:
+`fortran-minimum-statement-indent'
+ Minimum indentation for Fortran statements. For standard Fortran,
+ this is 6. Statement bodies are always indented at least this
+ much.
- (add-menu-item '("File") "Rename File" 'rename-file t)
+\1f
+File: xemacs.info, 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 non-standard 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 specified to do so in advance by setting 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, it recognizes
+an existing comment and aligns its text appropriately. If there is no
+existing comment, a comment is inserted and aligned.
+
+ Inserting and aligning comments is not the same in Fortran mode as in
+other modes. When a new comment must be inserted, a full-line comment
+is inserted if the current line is blank. On a non-blank line, a
+non-standard `!' comment is inserted if you previously specified you
+wanted to use them. Otherwise a full-line comment is inserted on a new
+line before the current line.
+
+ Non-standard `!' comments are aligned like comments in other
+languages, but full-line comments are aligned differently. 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.
+
+ You can also 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 two variables `comment-line-start' and
+`comment-line-start-skip', which do for full-line comments what
+`comment-start' and `comment-start-skip' do 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. It
+can therefore be used if you use `!' comments, but is useless in
+Fortran mode otherwise.
+
+ 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. You can control
+the string used for the comments by setting the variable
+`fortran-comment-region'. Note that here we have an example of a
+command and a variable with the same name; the two uses of the name
+never conflict because in Lisp and in Emacs it is always clear from the
+context which one is referred to.
- To add a submenu of file management commands using a File Management
-item, use the following code:
+\1f
+File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
- (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
- (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
- (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
+Columns
+-------
- The optional BEFORE argument is the name of a menu item before which
-the new item should be added. If the item is already present, it is
-not moved.
+`C-c C-r'
+ Displays a "column ruler" momentarily above the current line
+ (`fortran-column-ruler').
- To remove a specified menu item from the menu hierarchy, use
-`delete-menu-item'.
+`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').
- PATH is a list of strings that identify the position of the menu
-item in the menu hierarchy. `("File" "Save")' means the menu item
-called Save under the top level File menu. `("Menu" "Foo" "Item")'
-means the menu item called Item under the Foo submenu of Menu.
+ The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
+above the current line. The comment ruler consists of 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.
- To disable a menu item, use `disable-menu-item'. The disabled menu
-item is grayed and can no longer be selected. To make the item
-selectable again, use `enable-menu-item'. `disable-menu-item' and
-`enable-menu-item' both have the argument PATH.
+ Note that the column numbers count from zero, as always in XEmacs.
+As a result, the numbers may not be those you are familiar with; but the
+actual positions in the line are standard Fortran.
- To change the string of the specified menu item, use
-`relabel-menu-item'. This function also takes the argument PATH.
+ 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.
- NEW-NAME is the string to which the menu item will be changed.
+ For even more help, use `C-c C-w' (`fortran-window-create'), a
+command which splits the current window horizontally, resulting in a
+window 72 columns wide. When you edit in this window, you can
+immediately see when a line gets too wide to be correct Fortran.
\1f
-File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
+File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran
-Entering and Exiting Emacs
-**************************
+Fortran Keyword Abbrevs
+-----------------------
- The usual way to invoke XEmacs is to type `xemacs <RET>' at the
-shell. XEmacs clears the screen and then displays an initial advisory
-message and copyright notice. You can begin typing XEmacs commands
-immediately afterward.
+Fortran mode provides many built-in abbrevs for common keywords and
+declarations. These are the same sort of abbrevs that you can define
+yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::.
- Some operating systems insist on discarding all type-ahead when
-XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
-it is advisable to wait until XEmacs clears the screen before typing
-your first editing command.
+ The built-in abbrevs are unusual in one way: they all start with a
+semicolon. You cannot normally use semicolon in an abbrev, but Fortran
+mode makes this possible by changing the syntax of semicolon to "word
+constituent".
- If you run XEmacs from a shell window under the X Window System, run
-it in the background with `xemacs&'. This way, XEmacs does not tie up
-the shell window, so you can use that to run other shell commands while
-XEmacs operates its own X windows. You can begin typing XEmacs commands
-as soon as you direct your keyboard input to the XEmacs frame.
+ 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' changes automatically to `continue', provided
+Abbrev mode is enabled.
- Before Emacs reads the first command, you have not had a chance to
-give a command to specify a file to edit. Since Emacs must always have
-a current buffer for editing, it presents a buffer, by default, a buffer
-named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
-it to type Lisp expressions and evaluate them, or you can ignore that
-capability and simply doodle. (You can specify a different major mode
-for this buffer by setting the variable `initial-major-mode' in your
-init file. *Note Init File::.)
+ Type `;?' or `;C-h' to display a list of all built-in Fortran
+abbrevs and what they stand for.
- It is possible to specify files to be visited, Lisp files to be
-loaded, and functions to be called, by giving Emacs arguments in the
-shell command line. *Note Command Switches::. But we don't recommend
-doing this. The feature exists mainly for compatibility with other
-editors.
-
- Many other editors are designed to be started afresh each time you
-want to edit. You edit one file and then exit the editor. The next
-time you want to edit either another file or the same one, you must run
-the editor again. With these editors, it makes sense to use a
-command-line argument to say which file to edit.
-
- But starting a new Emacs each time you want to edit a different file
-does not make sense. For one thing, this would be annoyingly slow. For
-another, this would fail to take advantage of Emacs's ability to visit
-more than one file in a single editing session. And it would lose the
-other accumulated context, such as registers, undo history, and the mark
-ring.
-
- The recommended way to use XEmacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs session.
-Each time you want to edit a different file, you visit it with the
-existing Emacs, which eventually comes to have many files in it ready
-for editing. Usually you do not kill the Emacs until you are about to
-log out. *Note Files::, for more information on visiting more than one
-file.
+\1f
+File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs
+
+Asm Mode
+========
+
+Asm mode is a major mode for editing files of assembler code. It
+defines these commands:
+
+`<TAB>'
+ `tab-to-tab-stop'.
+
+`<LFD>'
+ Insert a newline and then indent using `tab-to-tab-stop'.
+
+`:'
+ Insert a colon and then remove the indentation from before the
+ label preceding colon. Then do `tab-to-tab-stop'.
+
+`;'
+ Insert or align a comment.
+
+ The variable `asm-comment-char' specifies which character starts
+comments in assembler syntax.
+
+\1f
+File: xemacs.info, Node: Running, 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.
+* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
+* Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
+* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
+* External Lisp:: Communicating through Emacs with a separate Lisp.
+
+\1f
+File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running
+
+Running "make", or Compilers Generally
+======================================
+
+Emacs can run compilers for non-interactive languages like 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 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'
+ Kill the process made by the `M-x compile' command.
+
+`M-x kill-grep'
+ Kill the running compilation or `grep' subprocess.
+
+`C-x `'
+ Visit the next compiler error message or `grep' match.
+
+ To run `make' or another compiler, type `M-x compile'. This command
+reads a shell command line using the minibuffer, then executes the
+specified command line in an inferior shell with output going to the
+buffer named `*compilation*'. By default, the current buffer's default
+directory is used as the working directory for the execution of the
+command; therefore, the makefile comes from this directory.
+
+ When the shell command line is read, the minibuffer appears
+containing a default command line (the command you used the last time
+you typed `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::).
+
+ When you start a compilation, the buffer `*compilation*' is
+displayed in another window but not selected. Its mode line displays
+the word `run' or `exit' in the parentheses to tell you whether
+compilation is finished. You do not have to keep this buffer visible;
+compilation continues in any case.
+
+ To kill the compilation process, type `M-x kill-compilation'. 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 occur at any time. Starting a new
+compilation prompts for confirmation before actually killing a
+compilation that is running.
+
+ To parse the compiler error messages, type `C-x `' (`next-error').
+The character following `C-x' is the grave accent, not the single
+quote. The 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 you use `C-x `' after the start of a compilation, it
+parses all the error messages, visits all the files that have error
+messages, and creates markers pointing at the lines the error messages
+refer to. It then 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 compiler errors while compilation is still going on.
+If no additional 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 again, then displays 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 to
+`grep': a `grep'-style regexp (usually in single quotes to quote the
+shell's special characters) followed by filenames, which may use
+wildcard characters. The output from `grep' goes in the
+`*compilation*' buffer. You can use `C-x `' to find the lines that
+match as if they were compilation errors.
+
+ Note: a shell is used to run the compile command, but the shell is
+not run in interactive mode. In particular, this means 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 initialization file (`.cshrc' or `.shrc'
+or ...) by setting the prompt unconditionally. The shell
+initialization file should set the prompt only if there already is a
+prompt. Here's how to do it in `csh':
+
+ if ($?prompt) set prompt = ...
+
+\1f
+File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running
+
+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 other
+ dialects of Lisp 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.
+
+\1f
+File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
+
+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 XEmacs can run it.
+
+\1f
+File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
+
+Loading Libraries
+-----------------
+
+`M-x load-file FILE'
+ Load the file FILE of Lisp code.
+
+`M-x load-library LIBRARY'
+ Load the library named LIBRARY.
+
+`M-x locate-library LIBRARY &optional NOSUFFIX'
+ Show the full path name of Emacs library LIBRARY.
+
+ To execute a file of Emacs Lisp, use `M-x load-file'. This command
+reads the file name you provide in the minibuffer, then executes the
+contents of that file as Lisp code. It is not necessary to visit the
+file first; in fact, this command reads the file as found on disk, not
+the 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, the name with `.el' appended; third, the specified name alone.
+A `.elc' file would be the result of compiling the Lisp file into byte
+code; if possible, it is loaded in preference to the Lisp file itself
+because the compiled file loads and runs faster.
+
+ Because the argument to `load-library' is usually not in itself a
+valid file name, file name completion is not available. In fact, 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 elements of this list may not begin with "`~'",
+so you must call `expand-file-name' on them before adding them to the
+list. 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 start wishing that `nil' were in the list, you should probably
+use `M-x load-file' for this case.
+
+ The variable is initialized by the EMACSLOADPATH environment
+variable. If no value is specified, the variable takes the default value
+specified in the file `paths.h' when Emacs was built. If a path isn't
+specified in `paths.h', a default value is obtained from the file
+system, near the directory in which the Emacs executable resides.
+
+ Like `M-x load-library', `M-x locate-library' searches the
+directories in `load-path' to find the file that `M-x load-library'
+would load. If the optional second argument NOSUFFIX is non-`nil', the
+suffixes `.elc' or `.el' are not added to the specified name LIBRARY
+(like calling `load' instead of `load-library').
+
+ You often 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, the entire file is loaded a second time if you use one of
+the autoloadable commands again. This prevents problems when the
+command is no longer autoloading but is working incorrectly because the
+file was only partially loaded. Function definitions are undone only
+for autoloading; explicit calls to `load' do not undo anything if
+loading is not completed.
+
+ The variable `after-load-alist' takes an alist of expressions to be
+evaluated when particular files are loaded. Each element has the form
+`(FILENAME forms...)'. When `load' is run and the filename argument is
+FILENAME, the forms in the corresponding element are executed at the
+end of loading.
+
+ FILENAME must match exactly. Normally FILENAME is the name of a
+library, with no directory specified, since that is how load is
+normally called. An error in `forms' does not undo the load, but it
+does prevent execution of the rest of the `forms'.
+
+\1f
+File: xemacs.info, 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.
+
+`M-x batch-byte-compile'
+ Run byte-compile-file on the files remaining on the command line.
+
+`M-x byte-compile-buffer &optional BUFFER'
+ Byte-compile and evaluate contents of BUFFER (default is current
+ buffer).
+
+`M-x byte-compile-file'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code.
+
+`M-x byte-compile-and-load-file FILENAME'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code and load it.
+
+`M-x byte-recompile-directory DIRECTORY'
+ Recompile every `.el' file in DIRECTORY that needs recompilation.
+
+`M-x disassemble'
+ Print disassembled code for OBJECT on (optional) STREAM.
+
+`M-x make-obsolete FUNCTION NEW'
+ Make the byte-compiler warn that FUNCTION is obsolete and NEW
+ should be used instead.
+
+ `byte-compile-file' creates a byte-code compiled file from an
+Emacs-Lisp source file. The default argument for this function is the
+file visited in the current buffer. The function 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 compile a file of
+Lisp code named FILENAME into a file of byte code and then load it, use
+`byte-compile-and-load-file'. To compile and evaluate Lisp code in a
+given buffer, use `byte-compile-buffer'.
+
+ To recompile all 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 been compiled yet. You must answer `y' or `n'
+to each offer.
+
+ You can use the function `batch-byte-compile' to invoke Emacs
+non-interactively from the shell to do byte compilation. When you use
+this function, 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; in that case,
+`byte-recompile-directory' is invoked on each such directory.
+`batch-byte-compile' uses all 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.
+
+\1f
+File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
+
+Converting Mocklisp to Lisp
+---------------------------
+
+XEmacs 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.
+
+ You cannot currently byte-compile converted Mocklisp code. The
+reason is that 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".
+
+\1f
+File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
+
+Evaluating Emacs-Lisp Expressions
+=================================
+
+Lisp programs intended to be run in Emacs should be edited in
+Emacs-Lisp mode; this will happen automatically for file names ending in
+`.el'. By contrast, Lisp mode itself should be used for editing Lisp
+programs intended for other Lisp systems. Emacs-Lisp mode can be
+selected with the command `M-x emacs-lisp-mode'.
+
+ For testing of Lisp programs to run in Emacs, it is useful to be able
+to evaluate part of the program as it is found in the Emacs buffer. For
+example, if you change the text of a Lisp function definition and then
+evaluate the definition, Emacs installs the change for future calls to
+the function. Evaluation of Lisp expressions is also useful in any
+kind of editing task for invoking non-interactive functions (functions
+that are not commands).
+
+`M-:'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the minibuffer (`eval-expression').
+
+`C-x C-e'
+ Evaluate the Lisp expression before point, and print the value in
+ the minibuffer (`eval-last-sexp').
+
+`C-M-x'
+ Evaluate the defun containing point or after point, and print the
+ value in the minibuffer (`eval-defun').
+
+`M-x eval-region'
+ Evaluate all the Lisp expressions in the region.
+
+`M-x eval-current-buffer'
+ Evaluate all the Lisp expressions in the buffer.
+
+ `M-:' (`eval-expression') is the most basic command for evaluating a
+Lisp expression interactively. It reads the expression using the
+minibuffer, so you can execute any expression on a buffer regardless of
+what the buffer contains. When evaluation is complete, the current
+buffer is once again the buffer that was current when `M-:' was typed.
+
+ In Emacs-Lisp mode, the key `C-M-x' is bound to the function
+`eval-defun', which parses the defun containing point or following point
+as a Lisp expression and evaluates it. The value is printed in the echo
+area. This command is convenient for installing in the Lisp environment
+changes that you have just made in the text of a function definition.
+
+ The command `C-x C-e' (`eval-last-sexp') performs a similar job but
+is available in all major modes, not just Emacs-Lisp mode. It finds
+the sexp before point, reads it as a Lisp expression, evaluates it, and
+prints the value in the echo area. It is sometimes useful to type in an
+expression and then, with point still after it, type `C-x C-e'.
+
+ If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
+value by inserting it into the current buffer at point, rather than in
+the echo area. The argument value does not matter.
+
+ The most general command for evaluating Lisp expressions from a
+buffer is `eval-region'. `M-x eval-region' parses the text of the
+region as one or more Lisp expressions, evaluating them one by one.
+`M-x eval-current-buffer' is similar, but it evaluates the entire
+buffer. This is a reasonable way to install the contents of a file of
+Lisp code that you are just ready to test. After finding and fixing a
+bug, use `C-M-x' on each function that you change, to keep the Lisp
+world in step with the source file.
+
+\1f
+File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
+
+The Emacs-Lisp Debugger
+=======================
+
+XEmacs contains a debugger for Lisp programs executing inside it. This
+debugger is normally not used; many commands frequently get Lisp errors
+when invoked in inappropriate contexts (such as `C-f' at the end of the
+buffer) and it would be unpleasant to enter a special debugging mode in
+this case. When you want to make Lisp errors invoke the debugger, you
+must set the variable `debug-on-error' to non-`nil'. Quitting with
+`C-g' is not considered an error, and `debug-on-error' has no effect on
+the handling of `C-g'. However, if you set `debug-on-quit' to be
+non-`nil', `C-g' will invoke the debugger. This can be useful for
+debugging an infinite loop; type `C-g' once the loop has had time to
+reach its steady state. `debug-on-quit' has no effect on errors.
+
+ You can make Emacs enter the debugger when a specified function is
+called or at a particular place in Lisp code. Use `M-x debug-on-entry'
+with argument FUN-NAME to have Emacs enter the debugger as soon as
+FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
+function stop entering the debugger when called. (Redefining the
+function also does this.) To enter the debugger from some other place
+in Lisp code, you must insert the expression `(debug)' there and
+install the changed code with `C-M-x'. *Note Lisp Eval::.
+
+ When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named `*Backtrace*' in another
+window. The backtrace buffer contains one line for each level of Lisp
+function execution currently going on. At the beginning of the buffer
+is a message describing the reason that the debugger was invoked, for
+example, an error message if it was invoked due to an error.
+
+ The backtrace buffer is read-only and is in Backtrace mode, a special
+major mode in which letters are defined as debugger commands. The
+usual Emacs editing commands are available; you can switch windows to
+examine the buffer that was being edited at the time of the error, and
+you can switch buffers, visit files, and perform any other editing
+operations. However, the debugger is a recursive editing level (*note
+Recursive Edit::); it is a good idea to return to the backtrace buffer
+and explicitly exit the debugger when you don't want to use it any
+more. Exiting the debugger kills the backtrace buffer.
+
+ The contents of the backtrace buffer show you the functions that are
+executing and the arguments that were given to them. It also allows you
+to specify a stack frame by moving point to the line describing that
+frame. The frame whose line point is on is considered the "current
+frame". Some of the debugger commands operate on the current frame.
+Debugger commands are mainly used for stepping through code one
+expression at a time. Here is a list of them:
+
+`c'
+ Exit the debugger and continue execution. In most cases,
+ execution of the program continues as if the debugger had never
+ been entered (aside from the effect of any variables or data
+ structures you may have changed while inside the debugger). This
+ includes entry to the debugger due to function entry or exit,
+ explicit invocation, and quitting or certain errors. Most errors
+ cannot be continued; trying to continue an error usually causes
+ the same error to occur again.
+
+`d'
+ Continue execution, but enter the debugger the next time a Lisp
+ function is called. This allows you to step through the
+ subexpressions of an expression, and see what the subexpressions
+ do and what values they compute.
+
+ When you enter the debugger this way, Emacs flags the stack frame
+ for the function call from which you entered. The same function
+ is then called when you exit the frame. To cancel this flag, use
+ `u'.
+
+`b'
+ Set up to enter the debugger when the current frame is exited.
+ Frames that invoke the debugger on exit are flagged with stars.
+
+`u'
+ Don't enter the debugger when the current frame is exited. This
+ cancels a `b' command on a frame.
+
+`e'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the echo area. This is equivalent to the command
+ `M-:'.
+
+`q'
+ Terminate the program being debugged; return to top-level Emacs
+ command execution.
+
+ If the debugger was entered due to a `C-g' but you really want to
+ quit, not to debug, use the `q' command.
+
+`r'
+ Return a value from the debugger. The value is computed by
+ reading an expression with the minibuffer and evaluating it.
+
+ The value returned by the debugger makes a difference when the
+ debugger was invoked due to exit from a Lisp call frame (as
+ requested with `b'); then the value specified in the `r' command
+ is used as the value of that frame.
+
+ The debugger's return value also matters with many errors. For
+ example, `wrong-type-argument' errors will use the debugger's
+ return value instead of the invalid argument; `no-catch' errors
+ will use the debugger value as a throw tag instead of the tag that
+ was not found. If an error was signaled by calling the Lisp
+ function `signal', the debugger's return value is returned as the
+ value of `signal'.
projects / chise / xemacs-chise.git.1 / blobdiff