- The Emacs parenthesis-matching feature is designed to show
-automatically how parentheses match in the text. Whenever you type a
-self-inserting character that is a closing delimiter, the cursor moves
-momentarily to the location of the matching opening delimiter, provided
-that is on the screen. If it is not on the screen, some text near it is
-displayed in the echo area. Either way, you can tell what grouping is
-being closed off.
-
- In Lisp, automatic matching applies only to parentheses. In C, it
-applies to braces and brackets too. Emacs knows which characters to regard
-as matching delimiters based on the syntax table, which is set by the major
-mode. @xref{Syntax}.
-
- If the opening delimiter and closing delimiter are mismatched---such as
-in @samp{[x)}---a warning message is displayed in the echo area. The
-correct matches are specified in the syntax table.
-
-@vindex blink-matching-paren
-@vindex blink-matching-paren-distance
-@vindex blink-matching-delay
- Three variables control parenthesis match display.
-@code{blink-matching-paren} turns the feature on or off; @code{nil}
-turns it off, but the default is @code{t} to turn match display on.
-@code{blink-matching-delay} says how many seconds to wait; the default
-is 1, but on some systems it is useful to specify a fraction of a
-second. @code{blink-matching-paren-distance} specifies how many
-characters back to search to find the matching opening delimiter. If
-the match is not found in that far, scanning stops, and nothing is
-displayed. This is to prevent scanning for the matching delimiter from
-wasting lots of time when there is no match. The default is 12,000.
-
-@cindex Show Paren mode
-@findex show-paren-mode
- When using X Windows, you can request a more powerful alternative kind
-of automatic parenthesis matching by enabling Show Paren mode. This
-mode turns off the usual kind of matching parenthesis display and
-instead uses highlighting to show what matches. Whenever point is after
-a close parenthesis, the close parenthesis and its matching open
-parenthesis are both highlighted; otherwise, if point is before an open
-parenthesis, the matching close parenthesis is highlighted. (There is
-no need to highlight the open parenthesis after point because the cursor
-appears on top of that character.) Use the command @kbd{M-x
-show-paren-mode} to enable or disable this mode.
-
-@node Comments
-@section Manipulating Comments
-@cindex comments
-
- Because comments are such an important part of programming, Emacs
-provides special commands for editing and inserting comments.
-
-@menu
-* Comment Commands::
-* Multi-Line Comments::
-* Options for Comments::
-@end menu
-
-@node Comment Commands
-@subsection Comment Commands
-
-@kindex M-;
-@cindex indentation for comments
-@findex indent-for-comment
-
- The comment commands insert, kill and align comments.
-
-@c WideCommands
-@table @kbd
-@item M-;
-Insert or align comment (@code{indent-for-comment}).
-@item C-x ;
-Set comment column (@code{set-comment-column}).
-@item C-u - C-x ;
-Kill comment on current line (@code{kill-comment}).
-@item C-M-j
-Like @key{RET} followed by inserting and aligning a comment
-(@code{indent-new-comment-line}).
-@item M-x comment-region
-Add or remove comment delimiters on all the lines in the region.
-@end table
-
- The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}).
-If there is no comment already on the line, a new comment is created,
-aligned at a specific column called the @dfn{comment column}. The comment
-is created by inserting the string Emacs thinks comments should start with
-(the value of @code{comment-start}; see below). Point is left after that
-string. If the text of the line extends past the comment column, then the
-indentation is done to a suitable boundary (usually, at least one space is
-inserted). If the major mode has specified a string to terminate comments,
-that is inserted after point, to keep the syntax valid.
-
- @kbd{M-;} can also be used to align an existing comment. If a line
-already contains the string that starts comments, then @kbd{M-;} just moves
-point after it and reindents 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 @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
-
-@example
-;; 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.
-@end example
-
- 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, @kbd{M-;} is still
-useful for moving directly to the start of the comment.
-
-@kindex C-u - C-x ;
-@findex kill-comment
- @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
-if there is one. The indentation before the start of the comment is killed
-as well. If there does not appear to be a comment in the line, nothing is
-done. To reinsert the comment on another line, move to the end of that
-line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that
-@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
-with a negative argument. That command is programmed so that when it
-receives a negative argument it calls @code{kill-comment}. However,
-@code{kill-comment} is a valid command which you could bind directly to a
-key if you wanted to.
-
-@node Multi-Line Comments
-@subsection Multiple Lines of Comments
-
-@kindex C-M-j
-@cindex blank lines in programs
-@findex indent-new-comment-line
- If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}).
-This terminates the comment you are typing, creates a new blank line
-afterward, and begins a new comment indented under the old one. When
-Auto Fill mode is on, going past the fill column while typing a comment
-causes the comment to be continued in just this fashion. If point is
-not at the end of the line when @kbd{C-M-j} is typed, the text on
-the rest of the line becomes part of the new comment line.
-
-@findex comment-region
- To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command. It adds comment delimiters to the lines that start
-in the region, thus commenting them out. With a negative argument, it
-does the opposite---it deletes comment delimiters from the lines in the
-region.
-
- With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument specifies
-how many copies of the character to insert. Thus, in Lisp mode,
-@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
-the comment delimiter is a way of calling attention to the comment. It
-can also affect how the comment is indented. In Lisp, for proper
-indentation, you should use an argument of two, if between defuns, and
-three, if within a defun.
-
-@vindex comment-padding
- The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the
-comment delimiter and the line's original text. The default is 1.
-
-@node Options for Comments
-@subsection Options Controlling Comments
-
-@vindex comment-column
-@kindex C-x ;
-@findex set-comment-column
- The comment column is stored in the variable @code{comment-column}. You
-can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
-(@code{set-comment-column}) sets the comment column to the column point is
-at. @kbd{C-u C-x ;} sets the comment column to match the last comment
-before point in the buffer, and then does a @kbd{M-;} to align the
-current line's comment under the previous one. Note that @kbd{C-u - C-x ;}
-runs the function @code{kill-comment} as described above.
-
- The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
-@xref{Locals}. Many major modes initialize this variable for the
-current buffer.
-
-@vindex comment-start-skip
- The comment commands recognize comments based on the regular
-expression that is the value of the variable @code{comment-start-skip}.
-Make sure this regexp does 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 @code{@t{"/\\*+
-*"}}, which matches extra stars and spaces after the @samp{/*} itself.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax. @xref{Regexps}.)
-
-@vindex comment-start
-@vindex comment-end
- When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will insert
-into the comment. In C mode, @code{comment-start} has the value
-@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
-
-@vindex comment-multi-line
- The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment. If
-@code{comment-multi-line} is @code{nil}, as it normally is, then the
-comment on the starting line is terminated and a new comment is started
-on the new following line. If @code{comment-multi-line} is not
-@code{nil}, then the new following line is set up as part of the same
-comment that was found on the starting line. This is done by not
-inserting a terminator on the old line, and not inserting a starter on
-the new line. In languages where multi-line comments work, the choice
-of value for this variable is a matter of taste.
-
-@vindex comment-indent-function
- The variable @code{comment-indent-function} should contain a function
-that will be called to compute the indentation for a newly inserted
-comment or for aligning an existing comment. It is set differently by
-various major modes. The function is called with no arguments, but with
-point at the beginning of the comment, or at the end of a line if a new
-comment is to be inserted. It should return the column in which the
-comment ought to start. For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
-
-@node Balanced Editing
-@section Editing Without Unbalanced Parentheses
-
-@table @kbd
-@item M-(
-Put parentheses around next sexp(s) (@code{insert-parentheses}).
-@item M-)
-Move past next close parenthesis and reindent
-(@code{move-past-close-and-reindent}).
-@end table
-
-@kindex M-(
-@kindex M-)
-@findex insert-parentheses
-@findex move-past-close-and-reindent
- The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
-(@code{move-past-close-and-reindent}) are designed to facilitate a style
-of editing which keeps parentheses balanced at all times. @kbd{M-(}
-inserts a pair of parentheses, either together as in @samp{()}, or, if
-given an argument, around the next several sexps. It leaves point after
-the open parenthesis. The command @kbd{M-)} moves past the close
-parenthesis, deleting any indentation preceding it, and indenting with
-@kbd{C-j} after it.
-
- For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
-F O O}, which has the same effect except for leaving the cursor before
-the close parenthesis.
-
-@vindex parens-require-spaces
- @kbd{M-(} may insert a space before the open parenthesis, depending on
-the syntax class of the preceding character. Set
-@code{parens-require-spaces} to @code{nil} value if you wish to inhibit
-this.
-
-@findex check-parens
-You can use @kbd{M-x check-parens} to find any unbalanced parentheses in
-a buffer.
-
-@node Symbol Completion
-@section Completion for Symbol Names
-@cindex completion (symbol names)
-
- Usually completion happens in the minibuffer. But one kind of completion
-is available in all buffers: completion for symbol names.
-
-@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the partial
-symbol before point against the set of meaningful symbol names. Any
-additional characters determined by the partial name are inserted at
-point.
-
- 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.
-
-@cindex completion using tags
-@cindex tags completion
-@cindex Info index completion
-@findex complete-symbol
- In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language. Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
-@cindex Lisp symbol completion
-@cindex completion in Lisp
-@findex lisp-complete-symbol
- In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties. However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
-
- In Text mode and related modes, @kbd{M-@key{TAB}} completes words
-based on the spell-checker's dictionary. @xref{Spelling}.
-
-@node Which Function
-@section Which Function Mode
-
- Which Function mode is a minor mode that displays the current function
-name in the mode line, as you move around in a buffer.
-
-@findex which-function-mode
-@vindex which-func-modes
- To enable (or disable) Which Function mode, use the command @kbd{M-x
-which-function-mode}. This command is global; it applies to all
-buffers, both existing ones and those yet to be created. However, this
-only affects certain major modes, those listed in the value of
-@code{which-func-modes}. (If the value is @code{t}, then Which Function
-mode applies to all major modes that know how to support it---which are
-the major modes that support Imenu.)
-
-@node Hideshow
-@section Hideshow minor mode
-
-@findex hs-minor-mode
-Hideshow minor mode provides selective display of blocks. Use @kbd{M-x
-hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the
-hook for major modes with which you want to use it and which support it.
-
-Blocks are defined dependent on the mode. In C mode or C++ mode, they
-are delimited by braces, while in Lisp-ish modes they are delimited by
-parens. Multi-line comments can also be hidden.
-
-@findex hs-hide-all
-@findex hs-hide-block
-@findex hs-show-all
-@findex hs-show-block
-@findex hs-show-region
-@findex hs-hide-level
-@findex hs-minor-mode
-@kindex C-c h
-@kindex C-c s
-@kindex C-c H
-@kindex C-c S
-@kindex C-c R
-@kindex C-c L
-@kindex S-mouse-2
-The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}),
-@kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x
-hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R}
-(@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level})
-with obvious functions and @kbd{S-mouse-2} toggles hiding of a block
-with the mouse.
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-show-hidden-short-form
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
-Hideshow is customized by the variables
-@table @code
-@item hs-hide-comments-when-hiding-all
-Specifies whether @kbd{hs-hide-all} should hide comments too.
-@item hs-show-hidden-short-form
-Specifies whether or not the last line in a form is omitted (saving
-screen space).
-@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-@item hs-special-modes-alist
-Initializes Hideshow variables for different modes.
-@end table
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, unreadable
-@cindex StudlyCaps
-@findex glasses-mode
-
-Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable
-by displaying underscores between all the pairs of lower and upper
-English letters or by emboldening the capitals. The text is not
-altered, only the display, so that you can use this mode on code written
-with such a convention for separating words in identifiers without
-modifying the code. It can be customized under the group
-@samp{glasses}. You can use it by adding @code{glasses-mode} to the
-mode hook of appropriate programming modes.
-
-
-@node Documentation
-@section Documentation Commands
-
- As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
-(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
-be used to print documentation of functions and variables that you want to
-call. These commands use the minibuffer to read the name of a function or
-variable to document, and display the documentation in a window.
-
- For extra convenience, these commands provide default arguments based on
-the code in the neighborhood of point. @kbd{C-h f} sets the default to the
-function called in the innermost list containing point. @kbd{C-h v} uses
-the symbol name around or adjacent to point as its default.
-
-@cindex Eldoc mode
-@findex eldoc-mode
- For Emacs Lisp code, you can also use Eldoc mode. This minor mode
-constantly displays in the echo area the argument list for the function
-being called at point. (In other words, it finds the function call that
-point is contained in, and displays the argument list of that function.)
-Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
-the command @kbd{M-x eldoc-mode} to enable or disable this feature.
-
-@findex info-lookup-symbol
-@findex info-lookup-file
-@kindex C-h C-i
- For C, Lisp, and other languages, you can use @kbd{C-h C-i}
-(@code{info-lookup-symbol}) to view the Info documentation for a symbol.
-You specify the symbol with the minibuffer; by default, it uses the
-symbol that appears in the buffer at point. The major mode determines
-where to look for documentation for the symbol---which Info files and
-which indices. You can also use @kbd{M-x info-lookup-file} to look for
-documentation for a file name. Currently the modes supported by
-Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
-Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files
-mostly must be obtained separately, typically from the appropriate GNU
-package.
-
-@findex manual-entry
-@cindex manual pages
- You can read the ``man page'' for an operating system command, library
-function, or system call, with the @kbd{M-x manual-entry} command. It
-runs the @code{man} program to format the man page, and runs it
-asynchronously if your system permits, so that you can keep on editing
-while the page is being formatted. (MS-DOS and MS-Windows 3 do not
-permit asynchronous subprocesses, so on these systems you cannot edit
-while Emacs waits for @code{man} to exit.) The result goes in a buffer
-named @samp{*Man @var{topic}*}. These buffers use a special major mode,
-Man mode, that facilitates scrolling and examining other manual pages.
-For details, type @kbd{C-h m} while in a man page buffer.
-
-@cindex sections of manual pages
- Man pages are subdivided into @dfn{sections}, and some man pages have
-identical names, but belong to different sections. To read a man page
-from a certain section, type @kbd{@var{topic}(@var{section})} or
-@kbd{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts for
-the topic. For example, to read the man page for the C library function
-@code{chmod} (as opposed to a command by the same name), type @kbd{M-x
-manual-entry @key{RET} chmod(2v) @key{RET}} (assuming @code{chmod} is in
-section @code{2v}).
-
- If you do not specify a section, the results depend on how the
-@code{man} command works on your system. Some of them display only the
-first man page they find, others display all the man pages, and you can
-page between them with the @kbd{M-n} and @kbd{M-p} keys. The mode line
-shows how many manual pages are available in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- For a long man page, setting the faces properly can take substantial
-time. By default, Emacs uses faces in man pages if Emacs can display
-different fonts or colors. You can turn off use of faces in man pages
-by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
- If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
-
-@findex woman
-@cindex manual pages, on MS-DOS/MS-Windows
- An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man'', since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external programs
-to format and display the man pages, instead it does that entirely in
-Emacs Lisp. Thus, it is useful on systems such as MS-Windows, where the
-@code{man} program and the programs it runs are not readily available.
-When invoked, @kbd{M-x woman} prompts for a name of a manual page and
-provides completion based on the list of manual pages that are installed
-on your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}. The word at point
-in the current buffer is used to suggest the default name of the manual
-page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
-
- If you type a name of a manual page and @kbd{M-x woman} finds that
-several manual pages by the same name exist in different sections, it
-pops up a window with possible candidates asking you to choose one of
-them.
-
-@vindex woman-manpath
- By default, @kbd{M-x woman} looks up the manual pages in directories
-listed by the @code{MANPATH} environment variable. (If @code{MANPATH}
-is not set, @code{woman} uses a suitable default value, which can be
-customized.) More precisely, @code{woman} looks for subdirectories that
-match the shell wildcard @file{man*} in each one of these directories,
-and tries to find the manual pages in those subdirectories. When first
-invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
-of directory names and stores that list in the @code{woman-manpath}
-variable. By changing the value of this variable, you can customize the
-list of directories where @code{woman} looks for manual pages.
-
-@vindex woman-path
- In addition, you can augment the list of directories searched by
-@code{woman} by setting the value of the @code{woman-path} variable.
-This variable should hold a list of specific directories which
-@code{woman} should search, in addition to those in
-@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
-@code{woman-path} are searched for the manual pages, not for @file{man*}
-subdirectories.
-
-@findex woman-find-file
- Occasionally, you might need to display manual pages that are not in
-any of the directories listed by @code{woman-manpath} and
-@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
-name of a manual page file, with completion, and then formats and
-displays that file like @kbd{M-x woman} does.
-
-@vindex woman-dired-keys
- First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
-key to run the @code{woman-find-file} command on the current line's
-file. You can disable this by setting the variable
-@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the
-Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
-line's archive member.
-
- For more information about setting up and using @kbd{M-x woman}, see
-@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
-Manual}.
-
- Eventually the GNU project hopes to replace most man pages with
-better-organized manuals that you can browse with Info. @xref{Misc
-Help}. Since this process is only partially completed, it is still
-useful to read manual pages.
-
-@node Change Log
-@section Change Logs
-
-@cindex change log
-@kindex C-x 4 a
-@findex add-change-log-entry-other-window
- The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
-file for the file you are editing
-(@code{add-change-log-entry-other-window}). If that file is actually a
-backup file, it makes an entry appropriate for the file's parent. This
-is useful for making log entries by comparing a version with deleted
-functions.
-
- A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes. Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories. A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
-
- A change log entry starts with a header line that contains your name,
-your email address (taken from the variable @code{user-mail-address}),
-and the current date and time. Aside from these header lines, every
-line in the change log starts with a space or a tab. The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star. Here are two entries, both dated in May
-1993, each with two items:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-1993-05-25 Richard Stallman <rms@@gnu.org>
-
- * man.el: Rename symbols `man-*' to `Man-*'.
- (manual-entry): Make prompt string clearer.
-
- * simple.el (blink-matching-paren-distance):
- Change default to 12,000.
-
-1993-05-24 Richard Stallman <rms@@gnu.org>
-
- * vc.el (minor-mode-map-alist): Don't use it if it's void.
- (vc-cancel-version): Doc fix.
-@end smallexample
-
-@noindent
-(Previous Emacs versions used a different format for the date. You can
-convert old-style entries to the current format with
-@findex change-log-redate
-@kbd{M-x change-log-redate}.)
-
- One entry can describe several changes; each change should have its
-own item. Normally there should be a blank line between items. When
-items are related (parts of the same change, in different places), group
-them by leaving no blank line between them. The second entry above
-contains two items grouped in this way.
-
-@vindex add-log-keep-changes-together
- @kbd{C-x 4 a} visits the change log file and creates a new entry
-unless the most recent entry is for today's date and your name. It also
-creates a new item for the current file. For many languages, it can
-even guess the name of the function or other object that was changed.
-When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4
-a} adds to any existing entry for the file rather than starting a new
-entry.
-
-@cindex Change Log mode
-@findex change-log-mode
- The change log file is visited in Change Log mode. In this major
-mode, each bunch of grouped items counts as one paragraph, and each
-entry is considered a page. This facilitates editing the entries.
-@kbd{C-j} and auto-fill indent each new line like the previous line;
-this is convenient for entering the contents of an entry.
-
-@findex change-log-merge
-The command @kbd{M-x change-log-merge} can be used to merge other log
-files into a buffer in Change Log Mode, preserving the date ordering
-of entries with either the current or old-style date formats.
-
-@findex change-log-redate
-@cindex converting change log date style
- Versions of Emacs before 20.1 used a format for the time of the change
-log entry that was different from what it uses now:
-
-@smallexample
-Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
-@end smallexample
-
-@noindent
-The @kbd{M-x change-log-redate} command converts all the old-style date
-entries in the change log file visited in the current buffer to the new
-format, so that all entries are kept in unified format. This is handy
-when the entries are contributed by many different people some of whom
-still use old versions of Emacs.
-
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
-
-@node Authors
-@section @file{AUTHORS} files
-@cindex @file{AUTHORS} file
-
- Programs which have many contributors usually include a file named
-@file{AUTHORS} in their distribution, which lists the individual
-contributions. Emacs has a special command for maintaining the
-@file{AUTHORS} file that is part of the Emacs distribution.
-
-@findex authors
- The @kbd{M-x authors} command prompts for the name of the root of the
-Emacs source directory. It then scans @file{ChageLog} files and Lisp
-source files under that directory for information about authors of
-individual packages and people who made changes in source files, and
-puts the information it gleans into a buffer named @samp{*Authors*}.
-You can then edit the contents of that buffer and merge it with the
-exisiting @file{AUTHORS} file.
-
-@node Tags
-@section Tags Tables
-@cindex tags table
-
- A @dfn{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 @kbd{M-.} command which finds the
-definition of a function by looking up which of the files it is in.
-
- Tags tables are stored in files called @dfn{tags table files}. The
-conventional name for a tags table file is @file{TAGS}.
-
- 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.
-
- 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 @dfn{tag}.
-
-@cindex C++ class browser, tags
-@cindex tags, C++
-@cindex class browser, C++
-@cindex Ebrowse
-The Ebrowse is a separate facility tailored for C++, with tags and a
-class browser. @xref{,,, ebrowse, Ebrowse User's Manual}.
-
-@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{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.
-@end menu
-
-@node Tag Syntax
-@subsection Source File Tag Syntax
-
- Here is how tag syntax is defined for the most popular languages:
-
-@itemize @bullet
-@item
-In C code, any C function or typedef is a tag, and so are definitions of
-@code{struct}, @code{union} and @code{enum}. You can tag function
-declarations and external variables in addition to function definitions
-by giving the @samp{--declarations} option to @code{etags}.
-@code{#define} macro definitions and @code{enum} constants are also
-tags, unless you specify @samp{--no-defines} when making the tags table.
-Similarly, global variables are tags, unless you specify
-@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
-can make the tags table file much smaller.
-
-@item
-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 @samp{--members} option. Tags for variables and functions in
-classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}. @code{operator} functions tags are
-named, for example @samp{operator+}.
-
-@item
-In Java code, tags include all the constructs recognized in C++, plus
-the @code{interface}, @code{extends} and @code{implements} constructs.
-Tags for variables and functions in classes are named
-@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
-
-@item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
-@code{\section}, @code{\subsection}, @code{\subsubsection},
-@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
-@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
-tag.@refill
-
-Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}. The
-value of this environment variable should be a colon-separated list of
-command names. For example,
-
-@example
-TEXTAGS="def:newcommand:newenvironment"
-export TEXTAGS
-@end example
-
-@noindent
-specifies (using Bourne shell syntax) that the commands @samp{\def},
-@samp{\newcommand} and @samp{\newenvironment} also define tags.
-
-@item
-In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero, is
-a tag.
-
-@item
-In Scheme code, tags include anything defined with @code{def} or with a
-construct whose name starts with @samp{def}. They also include variables
-set with @code{set!} at top level in the file.
-@end itemize
-
- Several other languages are also supported:
-
-@itemize @bullet
-
-@item
-In Ada code, functions, procedures, packages, tasks, and types are
-tags. Use the @samp{--packages-only} option to create tags for packages
-only.
-
-@item
-In assembler code, labels appearing at the beginning of a line,
-followed by a colon, are tags.
-
-@item
-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.
-
-@item
-In Cobol code, tags are paragraph names; that is, any word starting in
-column 8 and followed by a period.
-
-@item
-In Erlang code, the tags are the functions, records, and macros defined
-in the file.
-
-@item
-In Fortran code, functions, subroutines and blockdata are tags.
-
-@item
-In Objective C code, tags include Objective C definitions for classes,
-class categories, methods, and protocols.
-
-@item
-In Pascal code, the tags are the functions and procedures defined in
-the file.
-
-@item
-In Perl code, the tags are the procedures defined by the @code{sub},
-@code{my} and @code{local} keywords. Use @samp{--globals} if you want
-to tag global variables.
-
-@item
-In PostScript code, the tags are the functions.
-
-@item
-In Prolog code, a tag name appears at the left margin.
-
-@item
-In Python code, @code{def} or @code{class} at the beginning of a line
-generate a tag.
-@end itemize
-
- You can also generate tags based on regexp matching (@pxref{Etags
-Regexps}) to handle other formats and languages.
-
-@node Create Tags Table
-@subsection Creating Tags Tables
-@cindex @code{etags} program
-
- The @code{etags} program is used to create a tags table file. It knows
-the syntax of several languages, as described in
-@iftex
-the previous section.
-@end iftex
-@ifinfo
-@ref{Tag Syntax}.
-@end ifinfo
-Here is how to run @code{etags}:
-
-@example
-etags @var{inputfiles}@dots{}
-@end example
-
-@noindent
-The @code{etags} program reads the specified files, and writes a tags
-table named @file{TAGS} in the current working directory. You can
-intermix compressed and plain text source file names. @code{etags}
-knows about the most common compression formats, and does the right
-thing. So you can compress all your source files and have @code{etags}
-look for compressed versions of its file name arguments, if it does not
-find uncompressed versions. Under MS-DOS, @code{etags} also looks for
-file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the
-command line and @samp{mycode.c} does not exist.
-
- @code{etags} recognizes the language used in an input file based on
-its file name and contents. You can specify the language with the
-@samp{--language=@var{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 @samp{--include=@var{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
-@code{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 @code{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
-@samp{/}, or with @samp{@var{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 @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
-
-@smallexample
-find . -name "*.[chCH]" -print | etags -
-@end smallexample
-
- Use the option @samp{--language=@var{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
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents. Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
-
- @samp{etags --help} prints the list of the languages @code{etags}
-knows, and the file name rules for guessing the language. It also prints
-a list of all the available @code{etags} options, together with a short
-explanation.
-
-@node Etags Regexps
-@subsection Etags Regexps
-
- The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching. You can freely intermix it with file names.
-Each @samp{--regex} option adds to the preceding ones, and applies only
-to the following files. The syntax is:
-
-@smallexample
---regex=/@var{tagregexp}[/@var{nameregexp}]/
-@end smallexample
-
-@noindent
-where @var{tagregexp} is used to match the lines to tag. It is always
-anchored, that is, it behaves as if preceded by @samp{^}. If you want
-to account for indentation, just match any initial number of blanks by
-beginning your regular expression with @samp{[ \t]*}. In the regular
-expressions, @samp{\} quotes the next character, and @samp{\t} stands
-for the tab character. Note that @code{etags} does not handle the other
-C escape sequences for special characters.
-
-@cindex interval operator (in regexps)
- The syntax of regular expressions in @code{etags} is the same as in
-Emacs, augmented with the @dfn{interval operator}, which works as in
-@code{grep} and @code{ed}. The syntax of an interval operator is
-@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
-expression at least @var{m} times and up to @var{n} times.
-
- You should not match more characters with @var{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 @var{tagregexp}
-(as will usually be the case), you should add a @var{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 @samp{--ignore-case-regex} (or @samp{-c}) is like
-@samp{--regex}, except that the regular expression provided will be
-matched without regard to case, which is appropriate for various
-programming languages.
-
- The @samp{-R} option deletes all the regexps defined with
-@samp{--regex} options. It applies to the file names following it, as
-you can see from the following example:
-
-@smallexample
-etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
- bar.ber -R --lang=lisp los.er
-@end smallexample
-
-@noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents. @code{etags} also uses
-@var{reg1} to recognize additional tags in @file{voo.doo}, and both
-@var{reg1} and @var{reg2} to recognize additional tags in
-@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
-matching, to recognize tags in @file{los.er}.
-
- A regular expression can be bound to a given language, by prepending
-it with @samp{@{lang@}}. When you do this, @code{etags} will use the
-regular expression only for files of that language. @samp{etags --help}
-prints the list of languages recognised by @code{etags}. The following
-example tags the @code{DEFVAR} macros in the Emacs source files.
-@code{etags} applies this regular expression to C files only:
-
-@smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end smallexample
-
-@noindent
-This feature is particularly useful when storing a list of regular
-expressions in a file. The following option syntax instructs
-@code{etags} to read two files of regular expressions. The regular
-expressions contained in the second file are matched without regard to
-case.
-
-@smallexample
---regex=@@first-file --ignore-case-regex=@@second-file
-@end smallexample
-
-@noindent
-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 @samp{@@}, @code{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
-@samp{emacs.tags} with the following contents (the first line in the
-file is a comment):
-
-@smallexample
- -- This is for GNU Emacs source files
-@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
-@end smallexample
-
-@noindent
-and then use it like this:
-
-@smallexample
-etags --regex=@@emacs.tags *.[ch] */*.[ch]
-@end smallexample
-
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
-
-@itemize @bullet
-
-@item
-Tag Octave files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
- --regex='/###key \(.*\)/\1/' \
- --regex='/[ \t]*global[ \t].*/' \
- *.m
-@end smallexample
-
-@noindent
-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.
-
-@item
-Tag Tcl files:
-
-@smallexample
-etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
-@end smallexample
-
-@item
-Tag VHDL files:
-
-@smallexample
---language=none \
---regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
---regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
-\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
-@end smallexample
-@end itemize
-
-@node Select Tags Table
-@subsection Selecting a Tags Table
-
-@vindex tags-file-name
-@findex visit-tags-table
- Emacs has at any time one @dfn{selected} tags table, and all the commands
-for working with tags tables use the selected one. To select a tags table,
-type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
-argument. The name @file{TAGS} in the default directory is used as the
-default file name.
-
- All this command does is store the file name in the variable
-@code{tags-file-name}. Emacs does not actually read in the tags table
-contents until you try to use them. Setting this variable yourself is just
-as good as using @code{visit-tags-table}. The variable's initial value is
-@code{nil}; that value tells all the commands for working with tags tables
-that they must ask for a tags table file name to use.
-
- Using @code{visit-tags-table} when a tags table is already loaded
-gives you a choice: you can add the new tags table to the current list
-of tags tables, or start a new list. The tags commands use all the tags
-tables in the current list. If you start a new list, the new tags table
-is used @emph{instead} of others. If you add the new table to the
-current list, it is used @emph{as well as} the others. When the tags
-commands scan the list of tags tables, they don't always start at the
-beginning of the list; they start with the first tags table (if any)
-that describes the current file, proceed from there to the end of the
-list, and then scan from the beginning of the list until they have
-covered all the tables in the list.
-
-@vindex tags-table-list
- You can specify a precise list of tags tables by setting the variable
-@code{tags-table-list} to a list of strings, like this:
-
-@c keep this on two lines for formatting in smallbook
-@example
-@group
-(setq tags-table-list
- '("~/emacs" "/usr/local/lib/emacs/src"))
-@end group
-@end example
-
-@noindent
-This tells the tags commands to look at the @file{TAGS} files in your
-@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
-directory. The order depends on which file you are in and which tags
-table mentions that file, as explained above.
-
- Do not set both @code{tags-file-name} and @code{tags-table-list}.
-
-@node Find Tag
-@subsection Finding a Tag
-
- The most important thing that a tags table enables you to do is to find
-the definition of a specific tag.
-
-@table @kbd
-@item M-.@: @var{tag} @key{RET}
-Find first definition of @var{tag} (@code{find-tag}).
-@item C-u M-.
-Find next alternate definition of last tag specified.
-@item C-u - M-.
-Go back to previous tag found.
-@item C-M-. @var{pattern} @key{RET}
-Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
-@item C-u C-M-.
-Find the next tag whose name matches the last pattern used.
-@item C-x 4 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, but display it in another window
-(@code{find-tag-other-window}).
-@item C-x 5 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, and create a new frame to select the
-buffer (@code{find-tag-other-frame}).
-@item M-*
-Pop back to where you previously invoked @kbd{M-.} and friends.
-@end table
-
-@kindex M-.
-@findex find-tag
- @kbd{M-.}@: (@code{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, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition. Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
- If an empty argument is given (just type @key{RET}), the sexp in the
-buffer before or around point is used as the @var{tag} argument.
-@xref{Lists}, for info on sexps.
-
- You don't need to give @kbd{M-.} the full name of the tag; a part
-will do. This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring. However, it prefers an exact match
-to a substring match. To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
-
-@kindex C-x 4 .
-@findex find-tag-other-window
-@kindex C-x 5 .
-@findex find-tag-other-frame
- Like most commands that can switch buffers, @code{find-tag} has a
-variant that displays the new buffer in another window, and one that
-makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
-the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
-which invokes @code{find-tag-other-frame}.
-
- To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
-command can take you to another buffer. @kbd{C-x 4 .} with a negative
-argument finds the previous tag location in another window.
-
-@kindex M-*
-@findex pop-tag-mark
-@vindex find-tag-marker-ring-length
- As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them. Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this. Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
-
- Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
-a depth determined by the variable @code{find-tag-marker-ring-length}.
-
-@findex find-tag-regexp
-@kindex C-M-.
- The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
-match a specified regular expression. It is just like @kbd{M-.} except
-that it does regexp matching instead of substring matching.
-
-@node Tags Search
-@subsection 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.