1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
35 Basic Program Indentation Commands
36 ----------------------------------
39 Adjust indentation of current line.
42 Equivalent to <RET> followed by <TAB> (`newline-and-indent').
44 The basic indentation command is <TAB>, which gives the current line
45 the correct indentation as determined from the previous lines. The
46 function that <TAB> runs depends on the major mode; it is
47 `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
48 functions understand different syntaxes for different languages, but
49 they all do about the same thing. <TAB> in any programming language
50 major mode inserts or deletes whitespace at the beginning of the
51 current line, independent of where point is in the line. If point is
52 inside the whitespace at the beginning of the line, <TAB> leaves it at
53 the end of that whitespace; otherwise, <TAB> leaves point fixed with
54 respect to the characters around it.
56 Use `C-q <TAB>' to insert a tab at point.
58 When entering a large amount of new code, use <LFD>
59 (`newline-and-indent'), which is equivalent to a <RET> followed by a
60 <TAB>. <LFD> creates a blank line, then gives it the appropriate
63 <TAB> indents the second and following lines of the body of a
64 parenthetical grouping each under the preceding one; therefore, if you
65 alter one line's indentation to be nonstandard, the lines below tend to
66 follow it. This is the right behavior in cases where the standard
67 result of <TAB> does not look good.
69 Remember that Emacs assumes that an open-parenthesis, open-brace, or
70 other opening delimiter at the left margin (including the indentation
71 routines) is the start of a function. You should therefore never have
72 an opening delimiter in column zero that is not the beginning of a
73 function, not even inside a string. This restriction is vital for
74 making the indentation commands fast. *Note Defuns::, for more
75 information on this behavior.
78 File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
80 Indenting Several Lines
81 -----------------------
83 Several commands are available to re-indent several lines of code
84 which have been altered or moved to a different level in a list
88 Re-indent all the lines within one list (`indent-sexp').
91 Shift an entire list rigidly sideways so that its first line is
95 Re-indent all lines in the region (`indent-region').
97 To re-indent the contents of a single list, position point before the
98 beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
99 Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
100 functions in other modes. The indentation of the line the sexp starts
101 on is not changed; therefore, only the relative indentation within the
102 list, and not its position, is changed. To correct the position as
103 well, type a <TAB> before `C-M-q'.
105 If the relative indentation within a list is correct but the
106 indentation of its beginning is not, go to the line on which the list
107 begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
108 it moves all the lines in the group, starting on the current line,
109 sideways the same amount that the current line moves. The command does
110 not move lines that start inside strings, or C preprocessor lines when
113 Another way to specify a range to be re-indented is with point and
114 mark. The command `C-M-\' (`indent-region') applies <TAB> to every
115 line whose first character is between point and mark.
118 File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
120 Customizing Lisp Indentation
121 ----------------------------
123 The indentation pattern for a Lisp expression can depend on the
124 function called by the expression. For each Lisp function, you can
125 choose among several predefined patterns of indentation, or define an
126 arbitrary one with a Lisp program.
128 The standard pattern of indentation is as follows: the second line
129 of the expression is indented under the first argument, if that is on
130 the same line as the beginning of the expression; otherwise, the second
131 line is indented underneath the function name. Each following line is
132 indented under the previous line whose nesting depth is the same.
134 If the variable `lisp-indent-offset' is non-`nil', it overrides the
135 usual indentation pattern for the second line of an expression, so that
136 such lines are always indented `lisp-indent-offset' more columns than
139 Certain functions override the standard pattern. Functions whose
140 names start with `def' always indent the second line by
141 `lisp-body-indention' extra columns beyond the open-parenthesis
142 starting the expression.
144 Individual functions can override the standard pattern in various
145 ways, according to the `lisp-indent-function' property of the function
146 name. (Note: `lisp-indent-function' was formerly called
147 `lisp-indent-hook'). There are four possibilities for this property:
150 This is the same as no property; the standard indentation pattern
154 The pattern used for function names that start with `def' is used
155 for this function also.
158 The first NUMBER arguments of the function are "distinguished"
159 arguments; the rest are considered the "body" of the expression.
160 A line in the expression is indented according to whether the
161 first argument on it is distinguished or not. If the argument is
162 part of the body, the line is indented `lisp-body-indent' more
163 columns than the open-parenthesis starting the containing
164 expression. If the argument is distinguished and is either the
165 first or second argument, it is indented twice that many extra
166 columns. If the argument is distinguished and not the first or
167 second argument, the standard pattern is followed for that line.
170 SYMBOL should be a function name; that function is called to
171 calculate the indentation of a line within this expression. The
172 function receives two arguments:
174 The value returned by `parse-partial-sexp' (a Lisp primitive
175 for indentation and nesting computation) when it parses up to
176 the beginning of this line.
179 The position at which the line being indented begins.
181 It should return either a number, which is the number of columns of
182 indentation for that line, or a list whose first element is such a
183 number. The difference between returning a number and returning a
184 list is that a number says that all following lines at the same
185 nesting level should be indented just like this one; a list says
186 that following lines might call for different indentations. This
187 makes a difference when the indentation is computed by `C-M-q'; if
188 the value is a number, `C-M-q' need not recalculate indentation
189 for the following lines until the end of the list.
192 File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
194 Customizing C Indentation
195 -------------------------
197 Two variables control which commands perform C indentation and when.
199 If `c-auto-newline' is non-`nil', newlines are inserted both before
200 and after braces that you insert and after colons and semicolons.
201 Correct C indentation is done on all the lines that are made this way.
203 If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
204 does indentation only if point is at the left margin or within the
205 line's indentation. If there is non-whitespace to the left of point,
206 <TAB> just inserts a tab character in the buffer. Normally, this
207 variable is `nil', and <TAB> always reindents the current line.
209 C does not have anything analogous to particular function names for
210 which special forms of indentation are desirable. However, it has a
211 different need for customization facilities: many different styles of C
212 indentation are in common use.
214 There are six variables you can set to control the style that Emacs C
218 Indentation of C statements within surrounding block. The
219 surrounding block's indentation is the indentation of the line on
220 which the open-brace appears.
222 `c-continued-statement-offset'
223 Extra indentation given to a substatement, such as the then-clause
224 of an `if' or body of a `while'.
227 Extra indentation for lines that start with an open brace.
229 `c-brace-imaginary-offset'
230 An open brace following other text is treated as if it were this
231 far to the right of the start of its line.
234 Indentation level of declarations of C function arguments.
237 Extra indentation for a line that is a label, case, or default.
239 The variable `c-indent-level' controls the indentation for C
240 statements with respect to the surrounding block. In the example:
245 the difference in indentation between the lines is `c-indent-level'.
246 Its standard value is 2.
248 If the open-brace beginning the compound statement is not at the
249 beginning of its line, the `c-indent-level' is added to the indentation
250 of the line, not the column of the open-brace. For example,
255 One popular indentation style is that which results from setting
256 `c-indent-level' to 8 and putting open-braces at the end of a line in
257 this way. Another popular style prefers to put the open-brace on a
260 In fact, the value of the variable `c-brace-imaginary-offset' is
261 also added to the indentation of such a statement. Normally this
262 variable is zero. Think of this variable as the imaginary position of
263 the open brace, relative to the first non-blank character on the line.
264 By setting the variable to 4 and `c-indent-level' to 0, you can get
271 When `c-indent-level' is zero, the statements inside most braces
272 line up exactly under the open brace. An exception are braces in column
273 zero, like those surrounding a function's body. The statements inside
274 those braces are not placed at column zero. Instead, `c-brace-offset'
275 and `c-continued-statement-offset' (see below) are added to produce a
276 typical offset between brace levels, and the statements are indented
279 `c-continued-statement-offset' controls the extra indentation for a
280 line that starts within a statement (but not within parentheses or
281 brackets). These lines are usually statements inside other statements,
282 like the then-clauses of `if' statements and the bodies of `while'
283 statements. The `c-continued-statement-offset' parameter determines
284 the difference in indentation between the two lines in:
289 The default value for `c-continued-statement-offset' is 2. Some
290 popular indentation styles correspond to a value of zero for
291 `c-continued-statement-offset'.
293 `c-brace-offset' is the extra indentation given to a line that
294 starts with an open-brace. Its standard value is zero; compare:
304 If you set `c-brace-offset' to 4, the first example becomes:
309 `c-argdecl-indent' controls the indentation of declarations of the
310 arguments of a C function. It is absolute: argument declarations
311 receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
312 results in code like this:
319 `c-label-offset' is the extra indentation given to a line that
320 contains a label, a case statement, or a `default:' statement. Its
321 standard value is -2 and results in code like this:
327 If `c-label-offset' were zero, the same code would be indented as:
333 This example assumes that the other variables above also have their
336 Using the indentation style produced by the default settings of the
337 variables just discussed and putting open braces on separate lines
338 produces clear and readable files. For an example, look at any of the C
339 source files of XEmacs.
342 File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
344 Automatic Display of Matching Parentheses
345 =========================================
347 The Emacs parenthesis-matching feature shows you automatically how
348 parentheses match in the text. Whenever a self-inserting character that
349 is a closing delimiter is typed, the cursor moves momentarily to the
350 location of the matching opening delimiter, provided that is visible on
351 the screen. If it is not on the screen, some text starting with that
352 opening delimiter is displayed in the echo area. Either way, you see
353 the grouping you are closing off.
355 In Lisp, automatic matching applies only to parentheses. In C, it
356 also applies to braces and brackets. Emacs knows which characters to
357 regard as matching delimiters based on the syntax table set by the major
358 mode. *Note Syntax::.
360 If the opening delimiter and closing delimiter are mismatched--as in
361 `[x)'--the echo area displays a warning message. The correct matches
362 are specified in the syntax table.
364 Two variables control parenthesis matching displays.
365 `blink-matching-paren' turns the feature on or off. The default is `t'
366 (match display is on); `nil' turns it off.
367 `blink-matching-paren-distance' specifies how many characters back
368 Emacs searches to find a matching opening delimiter. If the match is
369 not found in the specified region, scanning stops, and nothing is
370 displayed. This prevents wasting lots of time scanning when there is no
371 match. The default is 4000.
374 File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
376 Manipulating Comments
377 =====================
379 The comment commands insert, kill and align comments.
382 Insert or align comment (`indent-for-comment').
385 Set comment column (`set-comment-column').
388 Kill comment on current line (`kill-comment').
391 Like <RET> followed by inserting and aligning a comment
392 (`indent-new-comment-line').
394 The command that creates a comment is `Meta-;'
395 (`indent-for-comment'). If there is no comment already on the line, a
396 new comment is created and aligned at a specific column called the
397 "comment column". Emacs creates the comment by inserting the string at
398 the value of `comment-start'; see below. Point is left after that
399 string. If the text of the line extends past the comment column,
400 indentation is done to a suitable boundary (usually, at least one space
401 is inserted). If the major mode has specified a string to terminate
402 comments, that string is inserted after point, to keep the syntax valid.
404 You can also use `Meta-;' to align an existing comment. If a line
405 already contains the string that starts comments, `M-;' just moves
406 point after it and re-indents it to the conventional place. Exception:
407 comments starting in column 0 are not moved.
409 Some major modes have special rules for indenting certain kinds of
410 comments in certain contexts. For example, in Lisp code, comments which
411 start with two semicolons are indented as if they were lines of code,
412 instead of at the comment column. Comments which start with three
413 semicolons are supposed to start at the left margin. Emacs understands
414 these conventions by indenting a double-semicolon comment using <TAB>
415 and by not changing the indentation of a triple-semicolon comment at
418 ;; This function is just an example.
419 ;;; Here either two or three semicolons are appropriate.
421 ;;; And now, the first part of the function:
422 ;; The following line adds one.
423 (1+ x)) ; This line adds one.
425 In C code, a comment preceded on its line by nothing but whitespace
426 is indented like a line of code.
428 Even when an existing comment is properly aligned, `M-;' is still
429 useful for moving directly to the start of the comment.
431 `C-u - C-x ;' (`kill-comment') kills the comment on the current
432 line, if there is one. The indentation before the start of the comment
433 is killed as well. If there does not appear to be a comment in the
434 line, nothing happens. To reinsert the comment on another line, move
435 to the end of that line, type first `C-y', and then `M-;' to realign
436 the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
437 ;' (`set-comment-column') with a negative argument. That command is
438 programmed to call `kill-comment' when called with a negative argument.
439 However, `kill-comment' is a valid command which you could bind
440 directly to a key if you wanted to.
442 Multiple Lines of Comments
443 --------------------------
445 If you are typing a comment and want to continue it on another line,
446 use the command `Meta-<LFD>' (`indent-new-comment-line'), which
447 terminates the comment you are typing, creates a new blank line
448 afterward, and begins a new comment indented under the old one. If
449 Auto Fill mode is on and you go past the fill column while typing, the
450 comment is continued in just this fashion. If point is not at the end
451 of the line when you type `M-<LFD>', the text on the rest of the line
452 becomes part of the new comment line.
454 Options Controlling Comments
455 ----------------------------
457 The comment column is stored in the variable `comment-column'. You
458 can explicitly set it to a number. Alternatively, the command `C-x ;'
459 (`set-comment-column') sets the comment column to the column point is
460 at. `C-u C-x ;' sets the comment column to match the last comment
461 before point in the buffer, and then calls `Meta-;' to align the
462 current line's comment under the previous one. Note that `C-u - C-x ;'
463 runs the function `kill-comment' as described above.
465 `comment-column' is a per-buffer variable; altering the variable
466 affects only the current buffer. You can also change the default value.
467 *Note Locals::. Many major modes initialize this variable for the
470 The comment commands recognize comments based on the regular
471 expression that is the value of the variable `comment-start-skip'.
472 This regexp should not match the null string. It may match more than
473 the comment starting delimiter in the strictest sense of the word; for
474 example, in C mode the value of the variable is `"/\\*+ *"', which
475 matches extra stars and spaces after the `/*' itself. (Note that `\\'
476 is needed in Lisp syntax to include a `\' in the string, which is needed
477 to deny the first star its special meaning in regexp syntax. *Note
480 When a comment command makes a new comment, it inserts the value of
481 `comment-start' to begin it. The value of `comment-end' is inserted
482 after point and will follow the text you will insert into the comment.
483 In C mode, `comment-start' has the value `"/* "' and `comment-end' has
486 `comment-multi-line' controls how `M-<LFD>'
487 (`indent-new-comment-line') behaves when used inside a comment. If
488 `comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
489 terminates the comment on the starting line and starts a new comment on
490 the new following line. If `comment-multi-line' is not `nil', then
491 `M-<LFD>' sets up the new following line as part of the same comment
492 that was found on the starting line. This is done by not inserting a
493 terminator on the old line and not inserting a starter on the new line.
494 In languages where multi-line comments are legal, the value you choose
495 for this variable is a matter of taste.
497 The variable `comment-indent-hook' should contain a function that is
498 called to compute the indentation for a newly inserted comment or for
499 aligning an existing comment. Major modes set this variable
500 differently. The function is called with no arguments, but with point
501 at the beginning of the comment, or at the end of a line if a new
502 comment is to be inserted. The function should return the column in
503 which the comment ought to start. For example, in Lisp mode, the
504 indent hook function bases its decision on the number of semicolons
505 that begin an existing comment and on the code in the preceding lines.
508 File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
510 Editing Without Unbalanced Parentheses
511 ======================================
514 Put parentheses around next sexp(s) (`insert-parentheses').
517 Move past next close parenthesis and re-indent
518 (`move-over-close-and-reindent').
520 The commands `M-(' (`insert-parentheses') and `M-)'
521 (`move-over-close-and-reindent') are designed to facilitate a style of
522 editing which keeps parentheses balanced at all times. `M-(' inserts a
523 pair of parentheses, either together as in `()', or, if given an
524 argument, around the next several sexps, and leaves point after the open
525 parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
526 which has the same effect except for leaving the cursor before the
527 close parenthesis. You can then type `M-)', which moves past the close
528 parenthesis, deletes any indentation preceding it (in this example
529 there is none), and indents with <LFD> after it.
532 File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
534 Completion for Lisp Symbols
535 ===========================
537 Completion usually happens in the minibuffer. An exception is
538 completion for Lisp symbol names, which is available in all buffers.
540 The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
541 Lisp symbol before point to be an abbreviation, and compares it against
542 all non-trivial Lisp symbols currently known to Emacs. Any additional
543 characters that they all have in common are inserted at point.
544 Non-trivial symbols are those that have function definitions, values, or
547 If there is an open-parenthesis immediately before the beginning of
548 the partial symbol, only symbols with function definitions are
549 considered as completions.
551 If the partial name in the buffer has more than one possible
552 completion and they have no additional characters in common, a list of
553 all possible completions is displayed in another window.
556 File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
558 Documentation Commands
559 ======================
561 As you edit Lisp code to be run in Emacs, you can use the commands
562 `C-h f' (`describe-function') and `C-h v' (`describe-variable') to
563 print documentation of functions and variables you want to call. These
564 commands use the minibuffer to read the name of a function or variable
565 to document, and display the documentation in a window.
567 For extra convenience, these commands provide default arguments
568 based on the code in the neighborhood of point. `C-h f' sets the
569 default to the function called in the innermost list containing point.
570 `C-h v' uses the symbol name around or adjacent to point as its default.
572 The `M-x manual-entry' command gives you access to documentation on
573 Unix commands, system calls, and libraries. The command reads a topic
574 as an argument, and displays the Unix manual page for that topic.
575 `manual-entry' always searches all 8 sections of the manual and
576 concatenates all the entries it finds. For example, the topic
577 `termcap' finds the description of the termcap library from section 3,
578 followed by the description of the termcap data base from section 5.
581 File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs
586 The Emacs command `M-x add-change-log-entry' helps you keep a record
587 of when and why you have changed a program. It assumes that you have a
588 file in which you write a chronological sequence of entries describing
589 individual changes. The default is to store the change entries in a
590 file called `ChangeLog' in the same directory as the file you are
591 editing. The same `ChangeLog' file therefore records changes for all
592 the files in a directory.
594 A change log entry starts with a header line that contains your name
595 and the current date. Except for these header lines, every line in the
596 change log starts with a tab. One entry can describe several changes;
597 each change starts with a line starting with a tab and a star. `M-x
598 add-change-log-entry' visits the change log file and creates a new entry
599 unless the most recent entry is for today's date and your name. In
600 either case, it adds a new line to start the description of another
601 change just after the header line of the entry. When `M-x
602 add-change-log-entry' is finished, all is prepared for you to edit in
603 the description of what you changed and how. You must then save the
604 change log file yourself.
606 The change log file is always visited in Indented Text mode, which
607 means that <LFD> and auto-filling indent each new line like the previous
608 line. This is convenient for entering the contents of an entry, which
609 must be indented. *Note Text Mode::.
611 Here is an example of the formatting conventions used in the change
614 Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
616 * xdisp.c (try_window_id):
617 If C-k is done at end of next-to-last line,
618 this fn updates window_end_vpos and cannot leave
619 window_end_pos nonnegative (it is zero, in fact).
620 If display is preempted before lines are output,
621 this is inconsistent. Fix by setting
622 blank_end_of_window to nonzero.
624 Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
627 Call the auto fill hook if appropriate.
629 * xdisp.c (try_window_id):
630 If point is found by compute_motion after xp, record that
631 permanently. If display_text_line sets point position wrong
632 (case where line is killed, point is at eob and that line is
633 not displayed), set it again in final compute_motion.
636 File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
641 A "tags table" is a description of how a multi-file program is
642 broken up into files. It lists the names of the component files and the
643 names and positions of the functions (or other named subunits) in each
644 file. Grouping the related files makes it possible to search or replace
645 through all the files with one command. Recording the function names
646 and positions makes possible the `M-.' command which finds the
647 definition of a function by looking up which of the files it is in.
649 Tags tables are stored in files called "tags table files". The
650 conventional name for a tags table file is `TAGS'.
652 Each entry in the tags table records the name of one tag, the name
653 of the file that the tag is defined in (implicitly), and the position
654 in that file of the tag's definition.
656 Just what names from the described files are recorded in the tags
657 table depends on the programming language of the described file. They
658 normally include all functions and subroutines, and may also include
659 global variables, data types, and anything else convenient. Each name
660 recorded is called a "tag".
664 * Tag Syntax:: Tag syntax for various types of code and text files.
665 * Create Tags Table:: Creating a tags table with `etags'.
666 * Etags Regexps:: Create arbitrary tags using regular expressions.
667 * Select Tags Table:: How to visit a tags table.
668 * Find Tag:: Commands to find the definition of a specific tag.
669 * Tags Search:: Using a tags table for searching and replacing.
670 * List Tags:: Listing and finding tags defined in a file.
673 File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Prev: Tags, Up: Tags
675 Source File Tag Syntax
676 ----------------------
678 Here is how tag syntax is defined for the most popular languages:
680 * In C code, any C function or typedef is a tag, and so are
681 definitions of `struct', `union' and `enum'. You can tag function
682 declarations and external variables in addition to function
683 definitions by giving the `--declarations' option to `etags'.
684 `#define' macro definitions and `enum' constants are also tags,
685 unless you specify `--no-defines' when making the tags table.
686 Similarly, global variables are tags, unless you specify
687 `--no-globals'. Use of `--no-globals' and `--no-defines' can make
688 the tags table file much smaller.
690 * In C++ code, in addition to all the tag constructs of C code,
691 member functions are also recognized, and optionally member
692 variables if you use the `--members' option. Tags for variables
693 and functions in classes are named `CLASS::VARIABLE' and
694 `CLASS::FUNCTION'. `operator' functions tags are named, for
697 * In Java code, tags include all the constructs recognized in C++,
698 plus the `interface', `extends' and `implements' constructs. Tags
699 for variables and functions in classes are named `CLASS.VARIABLE'
700 and `CLASS.FUNCTION'.
702 * In LaTeX text, the argument of any of the commands `\chapter',
703 `\section', `\subsection', `\subsubsection', `\eqno', `\label',
704 `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
707 Other commands can make tags as well, if you specify them in the
708 environment variable `TEXTAGS' before invoking `etags'. The value
709 of this environment variable should be a colon-separated list of
710 command names. For example,
712 TEXTAGS="def:newcommand:newenvironment"
715 specifies (using Bourne shell syntax) that the commands `\def',
716 `\newcommand' and `\newenvironment' also define tags.
718 * In Lisp code, any function defined with `defun', any variable
719 defined with `defvar' or `defconst', and in general the first
720 argument of any expression that starts with `(def' in column zero,
723 * In Scheme code, tags include anything defined with `def' or with a
724 construct whose name starts with `def'. They also include
725 variables set with `set!' at top level in the file.
727 Several other languages are also supported:
729 * In Ada code, functions, procedures, packages, tasks, and types are
730 tags. Use the `--packages-only' option to create tags for packages
733 * In assembler code, labels appearing at the beginning of a line,
734 followed by a colon, are tags.
736 * In Bison or Yacc input files, each rule defines as a tag the
737 nonterminal it constructs. The portions of the file that contain
738 C code are parsed as C code.
740 * In Cobol code, tags are paragraph names; that is, any word
741 starting in column 8 and followed by a period.
743 * In Erlang code, the tags are the functions, records, and macros
746 * In Fortran code, functions, subroutines and blockdata are tags.
748 * In Objective C code, tags include Objective C definitions for
749 classes, class categories, methods, and protocols.
751 * In Pascal code, the tags are the functions and procedures defined
754 * In Perl code, the tags are the procedures defined by the `sub',
755 `my' and `local' keywords. Use `--globals' if you want to tag
758 * In Postscript code, the tags are the functions.
760 * In Prolog code, a tag name appears at the left margin.
762 * In Python code, `def' or `class' at the beginning of a line
765 You can also generate tags based on regexp matching (*note Etags
766 Regexps::) to handle other formats and languages.
769 File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
774 The `etags' program is used to create a tags table file. It knows
775 the syntax of several languages, as described in *Note Tag Syntax::.
776 Here is how to run `etags':
780 The `etags' program reads the specified files, and writes a tags table
781 named `TAGS' in the current working directory. You can intermix
782 compressed and plain text source file names. `etags' knows about the
783 most common compression formats, and does the right thing. So you can
784 compress all your source files and have `etags' look for compressed
785 versions of its file name arguments, if it does not find uncompressed
786 versions. Under MS-DOS, `etags' also looks for file names like
787 `mycode.cgz' if it is given `mycode.c' on the command line and
788 `mycode.c' does not exist.
790 `etags' recognizes the language used in an input file based on its
791 file name and contents. You can specify the language with the
792 `--language=NAME' option, described below.
794 If the tags table data become outdated due to changes in the files
795 described in the table, the way to update the tags table is the same
796 way it was made in the first place. It is not necessary to do this
799 If the tags table fails to record a tag, or records it for the wrong
800 file, then Emacs cannot possibly find its definition. However, if the
801 position recorded in the tags table becomes a little bit wrong (due to
802 some editing in the file that the tag definition is in), the only
803 consequence is a slight delay in finding the tag. Even if the stored
804 position is very wrong, Emacs will still find the tag, but it must
805 search the entire file for it.
807 So you should update a tags table when you define new tags that you
808 want to have listed, or when you move tag definitions from one file to
809 another, or when changes become substantial. Normally there is no need
810 to update the tags table after each edit, or even every day.
812 One tags table can effectively include another. Specify the included
813 tags file name with the `--include=FILE' option when creating the file
814 that is to include it. The latter file then acts as if it contained
815 all the files specified in the included file, as well as the files it
818 If you specify the source files with relative file names when you run
819 `etags', the tags file will contain file names relative to the
820 directory where the tags file was initially written. This way, you can
821 move an entire directory tree containing both the tags file and the
822 source files, and the tags file will still refer correctly to the source
825 If you specify absolute file names as arguments to `etags', then the
826 tags file will contain absolute file names. This way, the tags file
827 will still refer to the same files even if you move it, as long as the
828 source files remain in the same place. Absolute file names start with
829 `/', or with `DEVICE:/' on MS-DOS and MS-Windows.
831 When you want to make a tags table from a great number of files, you
832 may have problems listing them on the command line, because some systems
833 have a limit on its length. The simplest way to circumvent this limit
834 is to tell `etags' to read the file names from its standard input, by
835 typing a dash in place of the file names, like this:
837 find . -name "*.[chCH]" -print | etags -
839 Use the option `--language=NAME' to specify the language explicitly.
840 You can intermix these options with file names; each one applies to
841 the file names that follow it. Specify `--language=auto' to tell
842 `etags' to resume guessing the language from the file names and file
843 contents. Specify `--language=none' to turn off language-specific
844 processing entirely; then `etags' recognizes tags by regexp matching
845 alone (*note Etags Regexps::).
847 `etags --help' prints the list of the languages `etags' knows, and
848 the file name rules for guessing the language. It also prints a list of
849 all the available `etags' options, together with a short explanation.
852 File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
857 The `--regex' option provides a general way of recognizing tags
858 based on regexp matching. You can freely intermix it with file names.
859 Each `--regex' option adds to the preceding ones, and applies only to
860 the following files. The syntax is:
862 --regex=/TAGREGEXP[/NAMEREGEXP]/
864 where TAGREGEXP is used to match the lines to tag. It is always
865 anchored, that is, it behaves as if preceded by `^'. If you want to
866 account for indentation, just match any initial number of blanks by
867 beginning your regular expression with `[ \t]*'. In the regular
868 expressions, `\' quotes the next character, and `\t' stands for the tab
869 character. Note that `etags' does not handle the other C escape
870 sequences for special characters.
872 The syntax of regular expressions in `etags' is the same as in
873 Emacs, augmented with the "interval operator", which works as in `grep'
874 and `ed'. The syntax of an interval operator is `\{M,N\}', and its
875 meaning is to match the preceding expression at least M times and up to
878 You should not match more characters with TAGREGEXP than that needed
879 to recognize what you want to tag. If the match is such that more
880 characters than needed are unavoidably matched by TAGREGEXP (as will
881 usually be the case), you should add a NAMEREGEXP, to pick out just the
882 tag. This will enable Emacs to find tags more accurately and to do
883 completion on tag names more reliably. You can find some examples
886 The option `--ignore-case-regex' (or `-c') is like `--regex', except
887 that the regular expression provided will be matched without regard to
888 case, which is appropriate for various programming languages.
890 The `-R' option deletes all the regexps defined with `--regex'
891 options. It applies to the file names following it, as you can see
892 from the following example:
894 etags --regex=/REG1/ voo.doo --regex=/REG2/ \
895 bar.ber -R --lang=lisp los.er
897 Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
898 according to their contents. `etags' also uses REG1 to recognize
899 additional tags in `voo.doo', and both REG1 and REG2 to recognize
900 additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
901 regexp matching, to recognize tags in `los.er'.
903 A regular expression can be bound to a given language, by prepending
904 it with `{lang}'. When you do this, `etags' will use the regular
905 expression only for files of that language. `etags --help' prints the
906 list of languages recognised by `etags'. The following example tags
907 the `DEFVAR' macros in the Emacs source files. `etags' applies this
908 regular expression to C files only:
910 --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
912 This feature is particularly useful when storing a list of regular
913 expressions in a file. The following option syntax instructs `etags'
914 to read two files of regular expressions. The regular expressions
915 contained in the second file are matched without regard to case.
917 --regex=@first-file --ignore-case-regex=@second-file
919 A regex file contains one regular expressions per line. Empty lines,
920 and lines beginning with space or tab are ignored. When the first
921 character in a line is `@', `etags' assumes that the rest of the line
922 is the name of a file of regular expressions. This means that such
923 files can be nested. All the other lines are taken to be regular
924 expressions. For example, one can create a file called `emacs.tags'
925 with the following contents (the first line in the file is a comment):
927 -- This is for GNU Emacs source files
928 {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
930 and then use it like this:
932 etags --regex=@emacs.tags *.[ch] */*.[ch]
934 Here are some more examples. The regexps are quoted to protect them
935 from shell interpretation.
939 etags --language=none \
940 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
941 --regex='/###key \(.*\)/\1/' \
942 --regex='/[ \t]*global[ \t].*/' \
945 Note that tags are not generated for scripts so that you have to
946 add a line by yourself of the form `###key <script-name>' if you
951 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
956 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
957 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
958 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
961 File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
963 Selecting a Tags Table
964 ----------------------
966 At any time Emacs has one "selected" tags table, and all the commands
967 for working with tags tables use the selected one. To select a tags
968 table, use the variable `tag-table-alist'.
970 The value of `tag-table-alist' is a list that determines which
971 `TAGS' files should be active for a given buffer. This is not really
972 an association list, in that all elements are checked. The car of each
973 element of this list is a pattern against which the buffers file name
974 is compared; if it matches, then the cdr of the list should be the name
975 of the tags table to use. If more than one element of this list
976 matches the buffers file name, all of the associated tags tables are
977 used. Earlier ones are searched first.
979 If the car of elements of this list are strings, they are treated as
980 regular-expressions against which the file is compared (like the
981 `auto-mode-alist'). If they are not strings, they are evaluated. If
982 they evaluate to non-`nil', the current buffer is considered to match.
984 If the cdr of the elements of this list are strings, they are
985 assumed to name a tags file. If they name a directory, the string
986 `tags' is appended to them to get the file name. If they are not
987 strings, they are evaluated and must return an appropriate string.
991 (setq tag-table-alist
992 '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
993 ("\\.el$" . "/usr/local/emacs/src/")
994 ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
995 ("" . "/usr/local/emacs/src/")
998 The example defines the tags table alist in the following way:
1000 * Anything in the directory `/usr/src/public/perl/' should use the
1001 `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
1003 * Files ending in `.el' should use the `TAGS' file
1004 `/usr/local/emacs/src/TAGS'.
1006 * Anything in or below the directory `/jbw/gnu/' should use the
1007 `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
1009 If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
1011 `/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
1012 that order), because it matches both patterns.
1014 If the buffer-local variable `buffer-tag-table' is set, it names a
1015 tags table that is searched before all others when `find-tag' is
1016 executed from this buffer.
1018 If there is a file called `TAGS' in the same directory as the file
1019 in question, then that tags file will always be used as well (after the
1020 `buffer-tag-table' but before the tables specified by this list).
1022 If the variable `tags-file-name' is set, the `TAGS' file it names
1023 will apply to all buffers (for backwards compatibility.) It is searched
1026 If the value of the variable `tags-always-build-completion-table' is
1027 `t', the tags file will always be added to the completion table without
1028 asking first, regardless of the size of the tags file.
1030 The function `M-x visit-tags-table', is largely made obsolete by the
1031 variable `tag-table-alist', tells tags commands to use the tags table
1032 file FILE first. The FILE should be the name of a file created with
1033 the `etags' program. A directory name is also acceptable; it means the
1034 file `TAGS' in that directory. The function only stores the file name
1035 you provide in the variable `tags-file-name'. Emacs does not actually
1036 read in the tags table contents until you try to use them. You can set
1037 the variable explicitly instead of using `visit-tags-table'. The value
1038 of the variable `tags-file-name' is the name of the tags table used by
1039 all buffers. This is for backward compatibility, and is largely
1040 supplanted by the variable `tag-table-alist'.
1043 File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
1048 The most important thing that a tags table enables you to do is to
1049 find the definition of a specific tag.
1051 `M-. TAG &OPTIONAL OTHER-WINDOW'
1052 Find first definition of TAG (`find-tag').
1055 Find next alternate definition of last tag specified.
1058 Find first definition of TAG, but display it in another window
1059 (`find-tag-other-window').
1061 `M-.' (`find-tag') is the command to find the definition of a
1062 specified tag. It searches through the tags table for that tag, as a
1063 string, then uses the tags table information to determine the file in
1064 which the definition is used and the approximate character position of
1065 the definition in the file. Then `find-tag' visits the file, moves
1066 point to the approximate character position, and starts searching
1067 ever-increasing distances away for the text that should appear at the
1068 beginning of the definition.
1070 If an empty argument is given (by typing <RET>), the sexp in the
1071 buffer before or around point is used as the name of the tag to find.
1072 *Note Lists::, for information on sexps.
1074 The argument to `find-tag' need not be the whole tag name; it can be
1075 a substring of a tag name. However, there can be many tag names
1076 containing the substring you specify. Since `find-tag' works by
1077 searching the text of the tags table, it finds the first tag in the
1078 table that the specified substring appears in. To find other tags that
1079 match the substring, give `find-tag' a numeric argument, as in `C-u
1080 M-.'. This does not read a tag name, but continues searching the tag
1081 table's text for another tag containing the same substring last used.
1082 If your keyboard has a real <META> key, `M-0 M-.' is an easier
1083 alternative to `C-u M-.'.
1085 If the optional second argument OTHER-WINDOW is non-`nil', it uses
1086 another window to display the tag. Multiple active tags tables and
1087 completion are supported.
1089 Variables of note include the following:
1092 Controls which tables apply to which buffers.
1095 Stores a default tags table.
1097 `tags-build-completion-table'
1098 Controls completion behavior.
1101 Specifies a buffer-local table.
1103 `make-tags-files-invisible'
1104 Sets whether tags tables should be very hidden.
1106 `tag-mark-stack-max'
1107 Specifies how many tags-based hops to remember.
1109 Like most commands that can switch buffers, `find-tag' has another
1110 similar command that displays the new buffer in another window. `C-x 4
1111 .' invokes the function `find-tag-other-window'. (This key sequence
1112 ends with a period.)
1114 Emacs comes with a tags table file `TAGS' (in the directory
1115 containing Lisp libraries) that includes all the Lisp libraries and all
1116 the C sources of Emacs. By specifying this file with `visit-tags-table'
1117 and then using `M-.' you can quickly look at the source of any Emacs
projects / chise / xemacs-chise.git- / blob