.TH DTXTAGS 1 "Time-stamp: <pdc 1995-04-06>" "PDCMAC 1.0" "CONTRIBUTED SOFTWARE"
.SH NAME
dtxtags \- generate an Emacs tags (etags) file from DTX files
.SH SYNOPSIS
.na
.B dtxtags
[
.BI \-\-output= outfile
] [
.I infile
]\|.\|.\|.
.br
.B dtxtags
.B \-\-help
|
.B \-\-version
.SH DESCRIPTION
.na
This is a shellscript that looks for definitions in
.B dtx 
files
(Documented TeX Macros, as used in the 
.SM PDCMAC
package), and generates a tags file in
.IR etags (1)
format.  The tags file will be called
.SM
.B TAGS 
by default.
Any old tags file will be written to
.BR TAGS.bak .
.SH OPTIONS
.TP
.BI \-\-output= outfile, " \-o " outfile
Write tags to
.I outfile
instead of the default.
Any existing file with that name will be renamed
.IB outfile .bak
first.
.TP
.BR \-\-help ", " \-h
Print a summary of options and exit.
.TP
.BR \-\-version ", " \-V
Print version identification and exit.
.SH "INPUT SYNTAX"
This section describes the constructs in the
.B dtx
that will be recognized as tags.  You should already be acquainted with
TeX terminology like `control sequence'.
.PP
A
.I keyword
is (1)\ a TeX control sequence
.I containing
.RB ` def ',
such as
.B \edef
or
.B \edefverbatim
or
.BR \emathchardef ,
or (2)\ a control sequence
.I starting
with
.RB ` \enew ',
like
.B \enewif
and
.BR \enewcount .
Keywords define the
.I tag
(a control sequence or single character) immediately following.
.PP
Keywords are recognized only if immediately following a
.RB ` | '
at the start of a line, the code used to introduce macro code in
.B dtx
files.
.PP
There may be whitespace between the start of the line and the
vertical bar, and between the vertical bar and the keyword (this means a
few definitions appearing within definitions are spuriously tagged, but
this should be harmless).
.SH "OUTPUT FORMAT"
This section sumarizes the syntax of the tag file that is generated,
because the documentation for
.IR etags (1)
omits it. Since this syntax description was made by reverse-engineering
.I etags
output, it should not be taken as definitive!
.PP
A tags file is composed of
.I sections 
catenated together,
each section made of a
.I header
followed by the
.IR body .
All numbers are expressed in ASCII in decimal notation.
.PP
The header consists of a form feed, a newline, the name of the file the
tags are found in, a comma, and the size in bytes of the body and a
newline.
.PP
The body consists of
.I entries
which may be in
old format or new format.
Old format entries are of the form
.IP "" 4n
.I fragment
.B \e177
.IB line ,
.I byte
.SM NL
.PP
where
.I fragment
is a fragment from the file containing the tag (where the start of the
fragment is at the beginning of a line in the file),
.B \e177
is a 
.SM DEL
character (character 127),
.I line
is the number of the line in which the fragment appears,
.I byte
is the position of the start of the fragment in bytes from the
start of the file,
and 
.SM NL
is a newline (character 10).
.PP
New format entries are of the form
.IP "" 4n
.I fragment
.B \e177
.IB line ,
.IB byte ,
.B \e001
.I tag
[
.B \e001
.I tag
]\|.\|.\|.
.SM NL
.PP
(two commas) where
.B \e001
is a
.SM SOH
character (character 1), and
.I tag
is the exact tag (necessary for C++, where the entire tag is not
necessarily found on the definition line).  The brackets and ellipsis
indicate that there may be one or more tags in the entry.
.PP
Real tags files may also have references to other tag files, but I don't
use this feature.
.SH ENVIRONMENT
.TP
.SM TMP
Name of directory for temporary files.
Default is
.BR /tmp .
.SH FILES
.TP
.SB TAGS
Default output file name.
.TP
.B /tmp/mktags\(**
Temporary files.
.SH AUTHOR
P. Damian Cugley
.RI ( damian.cugley@comlab.ox.ac.uk ).
.SH "SEE ALSO"
etags(1), emacs(1)
.PP
The file
.B etc/etags.notes
in the Emacs distribution.
.PP
Richard Stallman,
.I Emacs Reference Manual
(or the corresponding Info file).
.PP
P. Damian Cugley,
.I PDCMAC User Guide
(file
.B pdcguide.tex
in the
.SM PDCMAC
distribution),
for information about
.B dtx
files.
.SH BUGS
This is just a shellscript emulating a subset of
.IR etags 's
functionality.
.PP
Despite the name, this program does not work with the
.B dtx
files used in LaTeX 2e distributions, which have a completely different
format (and their own indexing scheme).