Source

emacs / man / maintaining.texi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
@c   2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Large Programs

  This chapter describes Emacs features for maintaining large
programs.  The version control features (@pxref{Version Control}) are
also particularly useful for this purpose.

@menu
* Change Log::	        Maintaining a change history for your program.
* Format of ChangeLog:: What the change log file looks like.
* Tags::	        Go directly to any function in your program in one
			  command.  Tags remembers which file it is in.
@ifnottex
* Emerge::              A convenient way of merging two versions of a program.
@end ifnottex
@end menu

@node Change Log
@section Change Logs

  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.

@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---that is useful for making log entries for functions that
have been deleted in the current version.

  @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.

@vindex add-log-keep-changes-together
  When the variable @code{add-log-keep-changes-together} is
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
rather than starting a new item.

@vindex add-log-always-start-new-record
  If @code{add-log-always-start-new-record} is non-@code{nil},
@kbd{C-x 4 a} always makes a new entry, even if the last entry
was made by you and on the same date.

@vindex change-log-version-info-enabled
@vindex change-log-version-number-regexp-list
@cindex file version in change log entries
  If the value of the variable @code{change-log-version-info-enabled}
is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
change log entry.  It finds the version number by searching the first
ten percent of the file, using regular expressions from the variable
@code{change-log-version-number-regexp-list}.

@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
  You can use the command @kbd{M-x change-log-merge} to merge other
log files into a buffer in Change Log Mode, preserving the date
ordering of entries.

  Version control systems are another way to keep track of changes in your
program and keep a change log.  @xref{Log Buffer}.

@node Format of ChangeLog
@section Format of ChangeLog

  A change log entry starts with a header line that contains the current
date, your name, and your email address (taken from the variable
@code{add-log-mailing-address}).  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, with two items and one item respectively.

@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

  One entry can describe several changes; each change should have its
own item, or its own line in an 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.

  You should put a copyright notice and permission notice at the
end of the change log file.  Here is an example:

@smallexample
Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
@end smallexample

@noindent
Of course, you should substitute the proper years and copyright holder.

@node Tags
@section Tags Tables
@cindex tags and tag tables

  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.  When a file parsed by @code{etags} is
generated from a different source file, like a C file generated from a
Cweb source file, the tags of the parsed file reference the source
file.

  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 file names, 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
  See also the Ebrowse facility, which is tailored for C++.
@xref{Top,, Ebrowse, 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}.
@code{#define} macro definitions, @code{#undef} 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.

You can tag function declarations and external variables in addition
to function definitions by giving the @samp{--declarations} option to
@code{etags}.  You can tag struct members with the @samp{--members}
option.

@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} definitions have
tag names like @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},
@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
@code{\newenvironment} or @code{\renewenvironment} 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="mycommand:myothercommand"
export TEXTAGS
@end example

@noindent
specifies (using Bourne shell syntax) that the commands
@samp{\mycommand} and @samp{\myothercommand} 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.

In Ada, the same name can be used for different kinds of entity
(e.g.@:, for a procedure and for a function).  Also, for things like
packages, procedures and functions, there is the spec (i.e.@: the
interface) and the body (i.e.@: the implementation).  To make it
easier to pick the definition you want, Ada tag name have suffixes
indicating the type of entity:

@table @samp
@item /b
package body.
@item /f
function.
@item /k
task.
@item /p
procedure.
@item /s
package spec.
@item /t
type.
@end table

  Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
directly to the body of the package @code{bidule}, while @kbd{M-x
find-tag @key{RET} bidule @key{RET}} will just search for any tag
@code{bidule}.

@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 block data are tags.

@item
In HTML input files, the tags are the @code{title} and the @code{h1},
@code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
and all occurrences of @code{id=}.

@item
In Lua input files, all functions are tags.

@item
In makefiles, targets are tags; additionally, variables are tags
unless you specify @samp{--no-globals}.

@item
In Objective C code, tags include Objective C definitions for classes,
class categories, methods and protocols.  Tags for variables and
functions in classes are named @samp{@var{class}::@var{variable}} and
@samp{@var{class}::@var{function}}.

@item
In Pascal code, the tags are the functions and procedures defined in
the file.

@item
In Perl code, the tags are the packages, subroutines and variables
defined by the @code{package}, @code{sub}, @code{my} and @code{local}
keywords.  Use @samp{--globals} if you want to tag global variables.
Tags for subroutines are named @samp{@var{package}::@var{sub}}.  The
name for subroutines defined in the default package is
@samp{main::@var{sub}}.

@item
In PHP code, tags are functions, classes and defines.  When using the
@samp{--members} option, vars are tags too.

@item
In PostScript code, the tags are the functions.

@item
In Prolog code, tags are predicates and rules at the beginning of
line.

@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
@ifnottex
@ref{Tag Syntax}.
@end ifnottex
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.

  If the specified files don't exist, @code{etags} looks for
compressed versions of them and uncompresses them to read them.  Under
MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
if it is given @samp{mycode.c} on the command line and @file{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.  If the tags table fails to record
a tag, or records it for the wrong file, then Emacs cannot possibly
find its definition until you update the tags table.  However, if the
position recorded in the tags table becomes a little bit wrong (due to
other editing), the worst consequence is a slight delay in finding the
tag.  Even if the stored position is very far wrong, Emacs will still
find the tag, after searching most of the file for it.  That delay is
hardly noticeable with today's computers.

   Thus, there is no need to update the tags table after each edit.
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.

  One tags table can virtually 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 covered all the source 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 the tags file is in @file{/dev}, however, the file names are
made relative to the current working directory.  This is useful, for
example, when writing the tags to @file{/dev/stdout}.

  When using a relative file name, it should not be a symbolic link
pointing to a tags file in a different directory, because this would
generally render the file names invalid.

  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}).

  The option @samp{--parse-stdin=@var{file}} is mostly useful when
calling @code{etags} from programs.  It can be used (only once) in
place of a file name on the command line.  @code{Etags} will read from
standard input and mark the produced tags as belonging to the file
@var{file}.

  @samp{etags --help} outputs 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.  If followed by one or more @samp{--language=@var{lang}}
options, it outputs detailed information about how tags are generated for
@var{lang}.

@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 this option with
file names, and each one applies to the source files that follow it.
If you specify multiple @samp{--regex} options, all of them are used
in parallel.  The syntax is:

@smallexample
--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@end smallexample

  The essential part of the option value is @var{tagregexp}, the
regexp for matching tags.  It is always used anchored, that is, it
only matches at the beginning of a line.  If you want to allow
indented tags, use a regexp that matches initial whitespace; start it
with @samp{[ \t]*}.

  In these regular expressions, @samp{\} quotes the next character, and
all the GCC character escape sequences are supported (@samp{\a} for
bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).

  Ideally, @var{tagregexp} should not match more characters than are
needed to recognize what you want to tag.  If the syntax requires you
to write @var{tagregexp} so it matches more characters beyond the tag
itself, 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 @var{modifiers} are a sequence of zero or more characters that
modify the way @code{etags} does the matching.  A regexp with no
modifiers is applied sequentially to each line of the input file, in a
case-sensitive way.  The modifiers and their meanings are:

@table @samp
@item i
Ignore case when matching this regexp.
@item m
Match this regular expression against the whole file, so that
multi-line matches are possible.
@item s
Match this regular expression against the whole file, and allow
@samp{.} in @var{tagregexp} to match newlines.
@end table

  The @samp{-R} option cancels all the regexps defined by preceding
@samp{--regex} options.  It too applies to the file names following
it.  Here's an example:

@smallexample
etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
    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}.  @var{reg1} is checked against each line of
@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
@var{reg2} is checked against the whole @file{bar.ber} file,
permitting multi-line matches, in a case-sensitive way.  @code{etags}
uses only the Lisp tags rules, with no user-specified regexp matching,
to recognize tags in @file{los.er}.

  You can restrict a @samp{--regex} option to match only files of a
given language by using the optional prefix @var{@{language@}}.
(@samp{etags --help} prints the list of languages recognized by
@code{etags}.)  This is particularly useful when storing many
predefined regular expressions for @code{etags} in a file.  The
following example tags the @code{DEFVAR} macros in the Emacs source
files, for the C language only:

@smallexample
--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
@end smallexample

@noindent
When you have complex regular expressions, you can store the list of
them 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=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
@end smallexample

@noindent
A regex file for @code{etags} contains one regular expression 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 another file of regular
expressions; thus, one such file can include another file.  All the
other lines are taken to be regular expressions.  If the first
non-whitespace text on the line is @samp{--}, that line is a comment.

  For example, we can create a file called @samp{emacs.tags} with the
following contents:

@smallexample
        -- This is for GNU Emacs C 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 @samp{###key @var{scriptname}} 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
etags --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, with @file{TAGS} in the default
directory as the default.

  Emacs does not actually read in the tags table contents until you
try to use them; all @code{visit-tags-table} does is store the file
name in the variable @code{tags-file-name}, and setting the variable
yourself is just as good.  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.

@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 balanced
expression in the buffer before or around point is used as the
@var{tag} argument.  @xref{Expressions}.

  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 @w{@kbd{C-x 4 .}}, which invokes
the command @code{find-tag-other-window}.  The latter is @w{@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.  @w{@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
@cindex search and replace in multiple files
@cindex multiple-file search and replace

  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.  These
commands scan the list of tags tables starting 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.

@table @kbd
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
Search for @var{regexp} through the files in the selected tags
table.
@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Perform a @code{query-replace-regexp} on each file in the selected tags table.
@item M-,
Restart one of the commands above, from the current location of point
(@code{tags-loop-continue}).
@end table

@findex tags-search
  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
searches for matches in all the files in the selected tags table, one
file at a time.  It displays the name of the file being searched so you
can follow its progress.  As soon as it finds an occurrence,
@code{tags-search} returns.

@kindex M-,
@findex tags-loop-continue
  Having found one match, you probably want to find all the rest.  To find
one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
@code{tags-search}.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.@refill

@findex tags-query-replace
  @kbd{M-x tags-query-replace} performs a single
@code{query-replace-regexp} through all the files in the tags table.  It
reads a regexp to search for and a string to replace with, just like
ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
input.  @xref{Replace}, for more information on query replace.

@vindex tags-case-fold-search
@cindex case-sensitivity and tags search
  You can control the case-sensitivity of tags search commands by
customizing the value of the variable @code{tags-case-fold-search}.  The
default is to use the same setting as the value of
@code{case-fold-search} (@pxref{Search Case}).

  It is possible to get through all the files in the tags table with a
single invocation of @kbd{M-x tags-query-replace}.  But often it is
useful to exit temporarily, which you can do with any input event that
has no special query replace meaning.  You can resume the query
replace subsequently by typing @kbd{M-,}; this command resumes the
last tags search or replace command that you did.  For instance, to
skip the rest of the current file, you can type @kbd{M-> M-,}.

  The commands in this section carry out much broader searches than the
@code{find-tag} family.  The @code{find-tag} commands search only for
definitions of tags that match your substring or regexp.  The commands
@code{tags-search} and @code{tags-query-replace} find every occurrence
of the regexp, as ordinary search commands and replace commands do in
the current buffer.

  These commands create buffers only temporarily for the files that they
have to search (those which are not already visited in Emacs buffers).
Buffers in which no match is found are quickly killed; the others
continue to exist.

  It may have struck you that @code{tags-search} is a lot like
@code{grep}.  You can also run @code{grep} itself as an inferior of
Emacs and have Emacs show you the matching lines one by one.
@xref{Grep Searching}.

@node List Tags
@subsection Tags Table Inquiries

@table @kbd
@item M-x list-tags @key{RET} @var{file} @key{RET}
Display a list of the tags defined in the program file @var{file}.
@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all tags matching @var{regexp}.
@end table

@findex list-tags
  @kbd{M-x list-tags} reads the name of one of the files described by
the selected tags table, and displays a list of all the tags defined in
that file.  The ``file name'' argument is really just a string to
compare against the file names recorded in the tags table; it is read as
a string rather than as a file name.  Therefore, completion and
defaulting are not available, and you must enter the file name the same
way it appears in the tags table.  Do not include a directory as part of
the file name unless the file name recorded in the tags table includes a
directory.

@findex tags-apropos
@vindex tags-apropos-verbose
  @kbd{M-x tags-apropos} is like @code{apropos} for tags
(@pxref{Apropos}).  It finds all the tags in the selected tags table
whose entries match @var{regexp}, and displays them.  If the variable
@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
of the tags files together with the tag names.

@vindex tags-tag-face
@vindex tags-apropos-additional-actions
  You can customize the appearance of the output by setting the
variable @code{tags-tag-face} to a face.  You can display additional
output with @kbd{M-x tags-apropos} by customizing the variable
@code{tags-apropos-additional-actions}---see its documentation for
details.

  You can also use the collection of tag names to complete a symbol
name in the buffer.  @xref{Symbol Completion}.

@ifnottex
@include emerge-xtra.texi
@end ifnottex

@ignore
   arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
@end ignore