Trailing-Edge - PDP-10 Archives - mit_emacs_170_teco_1220 - info/tags.mss
There are no other files named tags.mss in the archive.

This is the SCRIBE source from which the INFO file for TAGS and
the section describing it in the EMACS GUIDE are generated.

Control characters are represented as @CTL[X].

SCRIBE requires two @'s whenever one is wanted.
The SCRIBE "@:" construct must be used when a sentence ends with a
one-letter word.  "@." must be used when a sentence end appears to
occur after an abbreviation.

The SCRIBE constructs @U and @I cannot be used.  Instead, use @XXU and
@XXI for underlining and italicizing.  These do nothing in the INFO version.
Alternatively, use @XXUU and @XXII, which turn into all caps in
the INFO version.

@Define(Commands=Description,LeftMargin 16,Indent -8,Spread 0)
@Define(WideCommands=Description,LeftMargin 20,Indent -12,Spread 0)
@Define(DoubleWideCommands=Description,LeftMargin 24,Indent -16,Spread 0)
@Define(GrossCommands=Description,LeftMargin 16,Indent -16,Spread 1)
@Case{draft, ITS <@Textform[CC="C-C",CMC="C-M-C",TAGS=":TAGS",ITAGS=":TAGS"]>}
@Case{draft, Twenex <@Textform[CC="C-Z",CMC="C-M-Z",TAGS="TAGS",ITAGS="ITAGS"]>}

@Comment< These do not work!
@ITS{@Textform[C-C="C-C", C-M-C="C-M-C"]}
@Twenex{@Textform[C-C="C-Z", C-M-C="C-M-Z"]}
	They all get "Textform not at beginning of manuscript">


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

This file documents the EMACS Tags package.
@Node(Name="Top", Up="(EMACS)", Next="Create")

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

* 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.
@Node(Name="Create", Up="Top", Next="Select")

@Section[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(Name="INFO tag tables", IName="INFO",
Node="INFO"), for how to deal with them.

@ITS{  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:


  The languages that @TAGS[] understands now are TECO, LISP, MIDAS, FAIL,
PALX, MUDDLE, MACSYMA, TJ6, 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," @xxii[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
@CTL[_] also @xxii[must] be present.  You can omit both the last @CTL[_] and its CRLF
together, however.

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


  If this were written out as EMACS;EMACS TAGS, you could then do
:TAGS EMACS;EMACS   @I[(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(Node="Edit"), for info on adding,
deleting, or renaming files in existing tag tables.

  To make a tag 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
wild cards 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.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






















  If the extension you give is not recognizable, TAGS asks you to
specify the complete language name as above.  Languages NONE and TEXT
just include the file in the tag table, for use with Tags Query
Replace and such; files with those languages contain no tags.

  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 finds the names and languages of the source files by reading the
old tag table.

  The recently developed TAGGEN library is contains the function
Generate Tags File for updating a tag table.  This library may
eventually replace the TAGS program, being easier to customize.  In
the mean time, you are encouraged to try it out.  Refer to its
self-documentation for more information.

@Node(Name="Select", Prev="Create", Next="Jump")

@Section[How to Tell EMACS You Want to Use TAGS]

@index{Visit Tag Table}
  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 @ITS{FN2}@Twenex{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).

@index{Tags Find File}@index{Find File}@index{buffers}
  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.  @Manual{@XNote(Node="URK", Name="Storage
Exhausted", File="EMACS").} @INFO{@XNote(Node="Lossage", IName="URK
Error", File="EMACS")}.

@index{*TAGS* (buffer)}@index{Buffers}
  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.

@Node(Name="Jump", Prev="Select", Next="Add")

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

@index{Tag Table Filenames}
  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.

@Section[Other Operations on Tag Tables]}

@Node(Name="Add", Prev="Jump", Next="Files")

@SubSection[Adding a New Function to a Tag Table]

@index{^R Add Tag}
  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.

@Node(Name="Files", Prev="Add", Next="Search")

@SubSection[How to Process All the Files in a Tag Table]

@index{Next File}
  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

@index{*TAGS* (buffer)}
  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.

@Node(Name="Search", Prev="Files", Next="Misc")

@SubSection[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
@example[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 @CTL[O],
@CTL[X], @CTL[N], @CTL[B], and @CTL[Q] are allowed.
@XNote(File="EMACS", Node="TECOsearch", Name="TECO Search Strings").
@index{TECO search string}

@index{C-.}@index{Tags Search}
  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.

@index{Tags Query Replace}
  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.

@index{Tags Find File}@index{Buffers}@index{*Tags Search* (buffer)}
  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.

@Node(Name="Misc", Prev="Search", Next="Source")

@SubSection[Miscellaneous Applications of Tags]

@index{List 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.

@index{Tags Apropos}
  M-X Tags Apropos<pat><cr> lists all known tags whose names contain

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

@index{Tags Rescan}
  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.

@index{View Arglist}
  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.

@index{What Tag?}
  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

@Node(Name="Source", Prev="Misc", Next="Edit")

@Section[What Constitutes a Tag]

  In @Twenex{Mac}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 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:
"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 ";".
  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

  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.

@Node(Name="Edit", Prev="Source", Next="Internal")

@Section[Adding or Removing Source Files]

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

<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
@CTL[_] @xxii[must] be present.  You can omit both the last @CTL[_] 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 @CTL[_] 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 @ITS{of the
sort used in making a new tag table.}@Twenex{containing the filename,
the language, a count which can be zero because @TAGS[] will recompute
it, and a @CTL[_].}  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[]!

@Node(Name="Internal", Prev="Edit", Next="Info")

@Section[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

  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


  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.

@Node(Name="INFO", Prev="Internal")

@Section[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@ITS{, 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 @CTL[_] or @CTL[_]@CTL[L] 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.

@ITS{  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 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".}

  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 "@CTL[_]" 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.