summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/dtxtags.1
blob: 66ec2a8b6aa0d14d7ed7b2a0c4c3d61b6423889a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
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).