Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

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

To make a tags table file for some source file or group of source files,
you need to run the TAGS program which should reside somewhere on SYS:
or, if not there, <EMACS>.  When you run it, it will ask you for an
output file.  This is the file that will contain the tags of the source
files.  Usually you would specify something like FOO.TAGS if the source
file is FOO.BAR, so that they will be grouped together in directory
listings.  For example:

    @TAGS                      ; Runs the TAGS program
    Output tags file:FOO.TAGS   ; Specify output file
    Type filenames, end with blank line
    *

After you specify the output file, TAGS asks you for the input files.
You can give a number of files separated by commas, with wildcards
allowed.  Once you have done this, TAGS scans each input file and writes
the data into the output file.  For example:

    Type filenames, end with blank line
    *FOO.MAC
    FOO.MAC.1 - 784. functions found.
    *
    FOO.TAGS.1 - 784. functions in 1. files.
    @

Once each file is scanned, a message is typed indicating the number of
"functions" (labels, procedures, routines etc.) that were actually
found.  Once it is through processing your input files, you can type
another line full of input file names.  If there are no more, type just
a Return.  The empty line of input tells TAGS to finish up and close the
output file, which is now a usable tag table file.

The following languages are recognized by the TAGS program according to
the extension of the input filename specified:

        Language        Presumed extension
        BLISS           BLI
        BLISS11         B11
        FAIL            FAI
        FORTRAN         FOR
        H316            H16
        INTERLISP       ILSP
        MACLISP         LSP
        MACN11          M11
        MACRO           MAC
        MIDAS           MID
        PAL11X          P11
        SAIL            SAI
        PASCAL          PAS
        TECO            EMACS

If the extension you give is not recognizable, TAGS asks you to specify
the complete language name as above.

Once a tag table file exists, you must updated it if you add new tags to
the source files, or change them grossly.  You can do this by invoking
TAGS with the tab table filename as an argument:

    @TAGS FOO.TAGS

TAGS finds the names and languages of the source files by reading the
old tag table.


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, you must tell EMACS the name of the
tags table file you want to use.  This is done with the command

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

The extension 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

    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.

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.

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.

You do not need to type the complete name of the function; 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 wanted to find the definition of X-SET-TYPE-1
and you said just TYPE-1, you might find X-READ-TYPE-1 instead.  You
could then type C-U Meta-Period's until you reached 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.


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.  Do
this by selecting the buffer *TAGS* and saving it with C-X C-S, or with
M-X Save All Files.

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 MacLisp 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, and 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 BLISS and BLISS11 code, a tag starts with "GLOBAL" followed by
"ROUTINE" or "FUNCTION", or just a "ROUTINE" or "FUNCTION", and ends
with "=".  The "FUNCTION" identifier is only relevant in BLISS-10.

In FORTRAN code, a tag starts with "SUBROUTINE", "FUNCTION", or
"PROGRAM" and ends with the end of the line.

In INTERLISP code, a tag starts with (DEFINEQ and ends where the
function ends. Nested functions are handled properly.

In INFO code, (e.g. files that are used for the INFO documentation
subsystem), a tag starts with "Node:" and ends at the first ",".

In SAIL code, a tag starts with one of the following:  "SIMPLE",
"RECURSIVE", "POINTER", "BOOLEAN", "INTEGER", "REAL", "STRING",
"INTERNAL" and is followed by "PROCEDURE" and ends with the first ";".

In PASCAL code, a tag starts with either "PROCEDURE" or "FUNCTION" and
ends with the 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 you run
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.  If you screw things up, use TAGS to fix the
file.

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 containing the
filename, the language, a count which can be zero because TAGS will
recompute it, and a .  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 subunits in succession.  Each
subunit lists the tags of one source file.  Each subunit 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.  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 ITAGS will not put them in it.
ITAGS 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 the ITAGS program.

    @ITAGS <info file name>

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.