summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/dtxtags.1
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/contrib/pdcmac/dtxtags.1')
-rw-r--r--macros/plain/contrib/pdcmac/dtxtags.1207
1 files changed, 207 insertions, 0 deletions
diff --git a/macros/plain/contrib/pdcmac/dtxtags.1 b/macros/plain/contrib/pdcmac/dtxtags.1
new file mode 100644
index 0000000000..66ec2a8b6a
--- /dev/null
+++ b/macros/plain/contrib/pdcmac/dtxtags.1
@@ -0,0 +1,207 @@
+.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).