  -*-Text-*-
Don't edit this file! It is produced by SCRIBE from the TAGS MSS file.

This file documents the EMACS Tags package.


TAGS  Node: Top, Up: (EMACS), Next: Create

The TAGS Package.

The TAGS package remembers the locations of the function definitions in
a file and enables you to go directly to the definition of any function,
without searching the whole file.

The functions of several files that make up one program can all be
remembered together if you wish; then the TAGS package will
automatically select the appropriate file as well.


* Menu:

* Create::       How to create and update the tag table for
           your program.
* Select::       How to start using the TAGS package in EMACS.
* Jump:: How to go to the definition of a function.
* Add::          When you define a new function, you can put it
           in the tag table.
* Files::        How to look at all the files in a package, in
           order, one by one.
* Search::       Multi-file searching and replacement.
* Misc:: Listing some or all tags, recomputing tags, etc.
* Source::       What tag definitions should look like so that
           :TAGS will find them.
* Edit:: How to add, delete or rename files in an
           existing tag table.
* Internal::     What a tag table file looks like.
* INFO:: Tag tables for INFO files.



TAGS  Node: Create, Up: Top, Next: Select

How to Make a Tag Table for a Program

To use the TAGS package, you must create a tag table for the source file
or files in your package.  Normally, the tag table does not reside in
any of those files, but in a separate tag table file which contains the
names of the text files which it describes.  Tag table files are
generated by the :TAGS program.  The same program can be used to update
the tag table if it becomes very far out of date (slight inaccuracies do
not matter).  Tag tables for INFO files work differently; the INFO file
contains its own tag table, which describes only that file.  *Note INFO:
INFO, for how to deal with them.

The normal mode of operation of the :TAGS program is to read in an
existing tag table and update it by rescanning the source files that it
describes.  The old tag table file itself tells :TAGS which source files
to process.  When making a new tag table you must start by making a
skeleton.  Then :TAGS is used to turn the skeleton into an accurate tag
table.

A skeleton tag table is like a real one except that it is empty; there
are no tags in it.  It contains exactly this much data, for each source
file that it is going to describe:

    <filenames>
    0,<language>
    

The languages that :TAGS understands now are TECO, LISP, Scheme, MIDAS,
FAIL, PALX, MUDDLE, MACSYMA, TJ6, TeX, and R.  MIDAS will do for MACRO-10
files.  Any incompletely specified filenames will default to > and to the
directory on which the tag table file itself is stored.  The "0," MUST be
present, since :TAGS expects that there will be a number in that place and
will be completely confused if there is not.  The CRLF after each  also
MUST be present.  You can omit both the last  and its CRLF together,
however.

Thus, a skeleton tag table for the files EMACS;USRCOM > and EMACS;TAGS >
would look like

    EMACS;USRCOM >
    0,TECO
    
    EMACS;TAGS >
    0,TECO
    

If this were written out as EMACS;EMACS TAGS, you could then do 

    :TAGS EMACS;EMACS   (DEFAULT FN2 IS TAGS)

which would tell :TAGS to read in the tag table, and write back an
up-to-date tag table for the same set of source files.  To update the
tag table because lots of changes have been made, the same command to
the :TAGS program will work.  *Note Edit: Edit, for info on adding,
deleting, or renaming files in existing tag tables.


TAGS  Node: Select, Previous: Create, Up: Top, Next: Jump

How to Tell EMACS You Want to Use TAGS

Before you can use the TAGS package to find a tag, you must tell EMACS
the name of the tag table file you want to use.  This is done with the
command

    M-X Visit Tag Table <filenames> <cr>

The FN2 of "TAGS" need not be mentioned.

EMACS can only know about one tag table file at a time, so doing a
second M-X Visit Tag Table causes the first one to be forgotten (or
written back if you have added definitions to it).

Giving M-X Visit Tag Table a nonzero numeric argument, as in 

    C-U 1 M-X Visit Tag Table <filenames> <cr>

has the additional effect of setting the variable Tags Find File
nonzero, which causes the TAGS package to use Find File rather than
Visit File when it needs to switch files.  This causes all the files to
remain resident in the EMACS, in different buffers.  In the default
mode, visiting a tag in a different file read it in on top of the old
file, in the same buffer (but it offers to write out changes if there
are any).  Warning: you can easily run out of address space by making
too many buffers, this way.  *Note Lossage: (EMACS)Lossage.

Visit Tag Table is essentially equivalent to selecting the buffer *TAGS*
and visiting the tag table file in that buffer, then returning to the
previously selected buffer.  Afterwards, M-X List Buffers will show the
buffer *TAGS* visiting that file.  The only difference is that Visit Tag
Table causes the TAGS library to be loaded.


TAGS  Node: Jump, Previous: Select, Up: Top, Next: Add

Jumping to a Tag

To jump to the definition of a function, use the command Meta-Period
<tag name> <cr>.  You will go straight to the definition of the tag.  If
the definition is in a different file then TAGS visits that file.  If it
is in the same file, TAGS leaves the mark behind and prints "^@" in the
echo area.

You do not need to type the complete name of the function to be found;
any substring will do.  But this implies that sometimes you won't get
the function you intended.  When that happens, C-U Meta-Period will find
the "next" function matching what you typed (next, in the order of
listing in the tag table).  Thus, if you want to find the definition of
X-SET-TYPE-1 and you specify just TYPE-1, you might find X-READ-TYPE-1
instead.  You could then type C-U Meta-Period until you reach
X-SET-TYPE-1.

If you want to make sure you reach a precise function the first time,
you should just include a character of context before and after its
name.  Thus, in a Lisp program, put a space before and after the
function name.  In a MIDAS program, put a linefeed before it and a colon
after.

If Meta-Period is used before M-X Visit Tag Table has been done, it asks
for the name of a tag table file.  After you type this name and a <cr>,
you type the name of the tag as usual.  If the variable Tag Table
Filenames exists, it specifies the defaults for the filename.

Typing an Altmode as the first character of the argument to Meta-Period
allows you to switch to a new tag table.  It prompts for the tag table
filenames, then prompts again for the tag.


TAGS  Node: Add, Previous: Jump, Up: Top, Next: Files

Adding a New Function to a Tag Table

When you define a new function, its location doesn't go in the tag table
automatically.  That's because EMACS can't tell that you have defined a
function unless you tell it by invoking the function ^R Add Tag.  Since
the operation of adding a tag to a tag table has proved not to be very
necessary, this function no longer placed on any character, by default.
You can invoke with M-X or connect it to a character if you like.  For
this section, let's assume you have placed it on C-X Period.

When you type the command C-X Period, the pointer should be on the line
that introduces the function definition, after the function name and the
punctuation that ends it.  Thus, in a Lisp program, you might type
"(DEFUN FOO " (note the space after FOO) and then type the C-X Period.
In a MIDAS program, you might give the C-X Period after typing "FOO:".
In a TECO program in EMACS format, you might type C-X Period after "!Set
New Foo:!".

^R Add Tag modifies only the copy of the tag table loaded into EMACS.
To modify the tag table file itself, you must cause it to be saved.  M-X
Save All Files is the easiest way to do this.

Although local modifications to a file do not degrade the efficiency of
the TAGS package or require that the tag table be updated with :TAGS,
moving a function a great distance make it much slower to find that
function.  In this case, you can "add" the function to the tag table
with C-X Period to give the table its new location.  Or you can just run
:TAGS again to update everything, as is usually done.


TAGS  Node: Files, Previous: Add, Up: Top, Next: Search

How to Process All the Files in a Tag Table

The TAGS package contains a function M-X Next File which visits, one by
one, all the files described by the selected tag table.  This is useful
when there is something to be done to all of the files in the package.
To start off the sequence, do C-U 1 M-X Next File, which visits the
first file.  When you are finished operating on one file, do M-X Next
File (no argument) to see the next.  When all the files have been
processed, M-X Next File gives an error.

The files of the package are visited in the order that they are
mentioned in the tag table, and the current place in the sequence is
remembered by the pointer in the buffer *TAGS* which holds the tag
table.  Thus, if you visit a tag in a different file in the middle of a
M-X Next File sequence, you will screw it up unless you return to the
proper file again by visiting a tag (or go into the buffer *TAGS* and
reset the pointer).  However, visiting any other files directly, not
using TAGS, does not interfere with the sequence, and the next M-X Next
File will go just where it would have gone.

Next File is also useful as a subroutine in functions that wish to
perform an automatic transformation (such as a Query Replace) on each
file.  Such functions should call Next File with a precomma argument as
in 1,M(M.M Next File) or 1,1M(M.M Next File).  The precomma argument
tells Next File to return 0 instead of giving an error when there are no
more files to process.  Normally, it returns -1.

Here is an example of TECO code to do a Query Replace on all of the
files listed in the visited tag table:

    1M(M.M Next File)
    < M(M.M Query Replace)FOOBAR
      1,M(M.M Next File);>

Tags Search and Tags Query Replace (see below) both work using Next
File.


TAGS  Node: Search, Previous: Files, Up: Top, Next: Misc

Multi-File Searches and Replacements

The TAGS package contains a function Tags Search which will search
through all of the files listed in the visited tag table in the order
they are listed.  Do 

    M-X Tags Search<string><cr>

to find every occurrence of <string>.  <string> is a TECO search string
in which special TECO search characters such as , , , , and 
are allowed.  *Note TECO Search Strings: (EMACS)TECOsearch.

When M-X Tags Search reaches the end of the buffer, it visits the next
file automatically, typing its name in the echo area.  As soon as M-X
Tags Search finds one occurrence, it returns.  But it defines the
command Control-Period to resume the search from wherever point is.

M-X Tags Query Replace does a Query Replace over all the files in a tag
table.  Like M-X Tags Search, it sets Control-. up to be a command to
continue the Query Replace, in case you wish to exit, do some editing,
and then resume scanning.

With Tags Find File set nonzero, Tags Search or Tags Query Replace could
easily require more buffers than EMACS has room for.  To prevent such a
problem, they do not always put each file in a separate buffer.  If Tags
Search or Tags Query Replace wants to search a file which is already
visited in some buffer, it uses the copy in that buffer.  But if the
file is not present, and Tags Find File is 1, then instead of visiting
it in its own buffer, they visit it in a buffer named *Tags Search*.  So
at most one new buffer is created.  If Tags Find File is 2, a new buffer
is created for each file.

The library MQREPL enables you to use Next File to repeat a sequence of
many Query Replace commands over a set of files, performing all the
replacements on one file at a time.


TAGS  Node: Misc, Previous: Search, Up: Top, Next: Source

Miscellaneous Applications of Tags

M-X List Tags<file><cr> lists all the tags in the specified file.
Actually, all the files in the tag table whose names contain the string
<file> are listed.

M-X Tags Apropos<pat><cr> lists all known tags whose names contain
<pat>.

M-X Tags File List inserts in the buffer a list of the files known in
the visited tag table.

M-X Tags Rescan runs :TAGS over the visited tag table and revisits it.
This is the most convenient way to update the tag table.

M-X View Arglist<tag><cr> lets you look briefly at the line on which a
tag is defined, and at the lines of comments which precede the
definition.  This is a good way to find out what arguments a function
needs.  The file is always loaded into a separate buffer, when this
command is used.

M-X What Tag? tells you which function's definition you are in.  It
looks through the tag table for the tag which most nearly precedes
point.


TAGS  Node: Source, Previous: Misc, Up: Top, Next: Edit

What Constitutes a Tag

In Lisp code, a function definition must start with an "(" at the
beginning of a line, followed immediately with an atom which starts with
"DEF" (and does not start with "DEFP"), or which starts with "MACRO", or
which starts with "ENDF".  The next atom on the line is the name of the
tag.  If there is no second atom on the line, there is no tag.

In MIDAS code, a tag is any symbol that occurs at the beginning of a
line and is terminated with a colon or an equal sign.  MIDAS mode is
good for MACRO-10 also.

FAIL code is like MIDAS code, except that one or two 's or "^"'s are
allowed before a tag, spaces are allowed between the tag name and the
colon or equal sign, and _ is recognized as equivalent to =.

PALX code is like MIDAS code, except that spaces are allowed between a
tag and the following colon or equals, and local tags such as "10$" are
ignored.

In TECO code, a tag starts with an "!" and ends with a ":!".  There may
be any number of tags on a line, but the first one must start at the
beginning of a line.

In MUDDLE code, a tag is identified by a line that starts with "<DEFINE
" or "<DEFMAC ", followed by a symbol.

In MACSYMA code, a function definition is recognized when there is a
symbol at the beginning of a line, terminated with a "(" or "[", and
there is a ":" later on in the line.  If the symbol itself is terminated
with a ":", a variable definition is recognized.

In R text, any line which starts with ".de" or ".am" or ".rtag" defines
a tag.  The name of the tag is what follows, up to the second run of
spaces or the end of the line.  There is no ".rtag" in R; define it to
be a null macro, if you like, and use it to put in tags for chapters, or
anything else.  Any macro whose name starts with "de" or "am" or "rtag",
such as ".define" or ".amplify", also defines a tag.

In TJ6 text, any line which starts with ".C TAG" starts a tag.  The name
of the tag is whatever follows the spaces which should follow the "C
TAG", up to the next space or the end of the line.

In TeX text, any line that starts with "\tag{" starts a tag.  The tag
extends up to the next "}" or the end of the line, whichever comes
first.


TAGS  Node: Edit, Previous: Source, Up: Top, Next: Internal

Adding or Removing Source Files

A tag table file is a sequence of entries, one per file.  Each entry
looks like

    <filenames>
    <count>,<language>
    <data lines>
    

<filenames> are the fully defaulted names of the file, <language> is one
of the languages that TAGS knows how to process, and <data lines> are
the actual tag information (described below).  The CRLF after each 
MUST be present.  You can omit both the last  and its CRLF together,
however.

A tags table file is for the most part an ordinary ASCII file, and any
changes you make in it, including changes to the source files' names,
will do what they appear to do.

The one exception is that each entry contains a count, in decimal, of
the number of characters in it, including the  and CRLF.  If you edit
the contents of an individual source file's entry, and change its
length, then the tag table is no good for use in editing until the count
is updated.  This is usually done by running :TAGS over it.  :TAGS
ignores the specified count and always writes the correct count.  If you
are sure that the length is unchanged, or if you change the count
manually, then running :TAGS is not necessary, but you do so at your own
risk.

Thus, if you are changing a source file's name, you should simply change
the name where it is present in the tag table, and run :TAGS over it if
necessary.

To add a new source file, simply insert a dummy entry of the sort used
in making a new tag table. Then use :TAGS to update the tag table.  The
dummy will turn into a real entry.

You can delete a source file from a tag table by deleting its entire
entry.  Since the counts of the remaining entries are still valid, you
need not run :TAGS over the file again.  You can also change the order
of the entries without doing any harm.  The order of the entries matters
if there are tags which appear in more than one source file.

You can edit everything else in the tag table too, if you want to.  You
might want to change a language name once in a while, but I doubt you
will frequently want to add or remove tags, especially since that would
all be undone by the next use of :TAGS!


TAGS  Node: Internal, Previous: Edit, Up: Top, Next: Info

How a Tag Is Described in the Tag Table

A tag table file consists of one or more entries in succession.  Each
entry lists the tags of one source file, and has the overall format
described in the previous section, containing zero or more lines
describing tags.  Here we give the format of each of those lines.

Starting with the third line of the tag table entry, each line describes
a tag.  It starts with a copy of the beginning of the line that the tag
is defined on, up through the tag name and its terminating punctuation.
Then there is a rubout, followed by the character position in decimal of
the place in the line where copying stopped.  For example, if a line in
a MIDAS program starts with "FOO:"  and the colon is at position 602 in
the file, then the line describing it in the tag table would be

    FOO:<rubout>603

One line can describe several tags, if they are defined on the same
line; in fact, in that case, they must be on the same line in the tag
table, since it must contain everything before the tag name on its
definition line.  For example, 

    !Foo:! !Bar:!

in a file of TECO code followed by character number 500 of the file
would turn into 

    !Foo:! !Bar:!<rubout>500

EMACS will be able to use that line to find either FOO or BAR.  :TAGS
knows how to create such things only for TECO files, at the moment.
They aren't necessary in Lisp or MACSYMA files.  In MIDAS files, :TAGS
simply ignores all but the first tag on a line.


TAGS  Node: INFO, Previous: Internal, Up: Top

Tag Tables for INFO Structured Documentation Files

INFO files are divided up into nodes, which the INFO program must search
for.  Tag tables for these files are designed to make the INFO program
run faster.  Unlike a normal tag table, the tag table for an INFO file
resides in that file and describes only that file.  This is so that
INFO, when visiting a file, can automatically use its tag table if it
has one.  INFO uses the tag tables of INFO files itself, without going
through the normal TAGS package, which has no knowledge of INFO file tag
tables.  Thus, INFO file tag tables and normal ones resemble each other
only in their appearance and purpose, and that for convenience the same
:TAGS program generates both.  In use, they are unrelated.

To create a tag table in an INFO file, you must first put in a skeleton.
This skeleton must be very close to the end of the file (at most 8 lines
may follow it, or INFO will not notice it), and it must start on the
line following a  or  which ends a node.  Its format is as
follows:

    
    Tag Table:
    
    End Tag Table

No nodes may follow the tag table, or :TAGS will not put them in it.
:TAGS is one pass and after writing the tag table into the file it
copies the rest of the input file with no processing.

To turn the skeleton into the real thing, or to update the tag table,
run :TAGS on the file and specify the /I switch, as in

    :TAGS INFO;EMACS/I

:TAGS will process the file and replace the old tag table or skeleton
with an up-to-date tag table.  The /I identifies the specified file as
an INFO file rather than a tag table file.  Also, it makes the default
FN2 ">" rather than the usual "TAGS".

Once the tag table is constructed, INFO will automatically make use of
it.  A tag in an INFO file is just a node; whatever follows "Node:" on a
line whose predecessor contains a "" is taken to be a tag.  The
character which terminates the node name, which may be a comma, tab, or
CRLF, is not included in the tag table.  Instead, the rubout comes right
after the tag name.  This is to make it easy for INFO to demand an exact
match on node names, rather than the substring match which the TAGS
package normally uses.

Tag tables in INFO files must be kept close to up to date.  INFO will
not find the node if its start has moved more than 1000 characters
before the position listed in the tag table.  For best results, you
should update an INFO file's tag table every time you modify more than a
few characters of it.
