source: rtems/doc/tools/src2html1.4a/Ctags/ctags.1 @ 52461c5

4.104.114.84.95
Last change on this file since 52461c5 was 52461c5, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 14, 1998 at 4:03:45 PM

New files

  • Property mode set to 100644
File size: 6.7 KB
Line 
1.\" Ctags-new is a modified version of the ctags produced by UCB and
2.\" distributed in their BSD distributions.
3.\" You should be able to diff this version against theirs to see what I
4.\" have changed.
5.\"     Warren Toomey
6.\"
7.\" Copyright (c) 1987, 1990 The Regents of the University of California.
8.\" All rights reserved.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\"    must display the following acknowledgement:
20.\"     This product includes software developed by the University of
21.\"     California, Berkeley and its contributors.
22.\" 4. Neither the name of the University nor the names of its contributors
23.\"    may be used to endorse or promote products derived from this software
24.\"    without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36.\" SUCH DAMAGE.
37.\"
38.\"     @(#)ctags.1     6.8 (Berkeley) 4/24/91
39.\"
40.Dd April 24, 1991
41.Dt CTAGS 1
42.Os BSD 4
43.Sh NAME
44.Nm ctags-new
45.Nd create a tags file
46.Sh SYNOPSIS
47.Nm ctags-new
48.Op Fl BFadtuwvx
49.Op Fl f Ar tagsfile
50.Ar name ...
51.Sh DESCRIPTION
52.Nm Ctags-new
53makes a tags file for
54.Xr ex 1
55from the specified C,
56Pascal, Fortran,
57.Tn YACC ,
58lex, and lisp sources.  A tags file gives the
59locations of specified objects in a group of files.  Each line of the
60tags file contains the object name, the file in which it is defined,
61and a search pattern for the object definition, separated by white-space.
62Using the
63.Ar tags
64file,
65.Xr ex 1
66can quickly locate these object
67definitions.  Depending on the options provided to
68.Nm ctags-new ,
69objects will consist of subroutines, typedefs, defines, structs,
70enums and unions.
71.Bl -tag -width Ds
72.It Fl B
73use backward searching patterns
74.Pq Li ?...? .
75.It Fl F
76use forward searching patterns
77.Pq Li /.../
78(the default).
79.It Fl a
80append to
81.Ar tags
82file.
83.It Fl d
84create tags for
85.Li #defines
86that don't take arguments;
87.Li #defines
88that take arguments are tagged automatically.
89.It Fl f
90Places the tag descriptions in a file called
91.Ar tagsfile .
92The default behaviour is to place them in a file
93.Ar tags .
94.It Fl t
95create tags for typedefs, structs, unions, and enums.
96.It Fl u
97update the specified files in the
98.Ar tags
99file, that is, all
100references to them are deleted, and the new values are appended to the
101file.  (Beware: this option is implemented in a way which is rather
102slow; it is usually faster to simply rebuild the
103.Ar tags
104file.)
105.It Fl v
106An index of the form expected by
107.Xr vgrind 1
108is produced on the standard output.  This listing
109contains the object name, file name, and page number (assuming 64
110line pages).  Since the output will be sorted into lexicographic order,
111it may be desired to run the output through
112.Xr sort 1 .
113Sample use:
114.Bd -literal -offset indent
115ctags-new \-v files \&| sort \-f > index
116vgrind \-x index
117.Ed
118.It Fl y
119Yet another output format. This produces lines with the information:
120symbol, line number, file name, type of symbol, each separated by whitespace.
121This is used by the
122.Xr src2html 1L
123program.
124.It Fl w
125suppress warning diagnostics.
126.It Fl x
127.Nm ctags-new
128produces a list of object
129names, the line number and file name on which each is defined, as well
130as the text of that line and prints this on the standard output.  This
131is a simple index which can be printed out as an off-line readable
132function index.
133.El
134.Pp
135Files whose names end in
136.Nm \&.c
137or
138.Nm \&.h
139are assumed to be C
140source files and are searched for C style routine and macro definitions.
141Files whose names end in
142.Nm \&.y
143are assumed to be
144.Tn YACC
145source files.
146Files whose names end in
147.Nm \&.l
148are assumed to be lisp files if their
149first non-blank character is `;', `(', or `[',
150otherwise, they are
151treated as lex files.  Other files are first examined to see if they
152contain any Pascal or Fortran routine definitions, and, if not, are
153searched for C style definitions.
154.Pp
155The tag
156.Li main
157is treated specially in C programs.  The tag formed
158is created by prepending
159.Ar M
160to the name of the file, with the
161trailing
162.Nm \&.c
163and any leading pathname components removed.  This
164makes use of
165.Nm ctags-new
166practical in directories with more than one
167program.
168.Pp
169Yacc and lex files each have a special tag.
170.Ar Yyparse
171is the start
172of the second section of the yacc file, and
173.Ar yylex
174is the start of
175the second section of the lex file.
176.Sh FILES
177.Bl -tag -width tags -compact
178.It Pa tags
179default output tags file
180.El
181.Sh DIAGNOSTICS
182.Nm Ctags-new
183exits with a value of 1 if an error occurred, where
184duplicate objects are not considered errors, 0 otherwise.
185.Sh SEE ALSO
186.Xr ex 1 ,
187.Xr vi 1
188.Sh BUGS
189Recognition of
190.Nm functions  ,
191.Nm subroutines
192and
193.Nm procedures
194for
195.Tn FORTRAN
196and Pascal is done is a very simpleminded way.  No attempt
197is made to deal with block structure; if you have two Pascal procedures
198in different blocks with the same name you lose.
199.Nm Ctags-new
200doesn't
201understand about Pascal types.
202.Pp
203The method of deciding whether to look for C, Pascal or
204.Tn FORTRAN
205functions is a hack.
206.Pp
207.Nm Ctags-new
208relies on the input being well formed, and any syntactical
209errors will completely confuse it.  It also finds some legal syntax
210confusing; for example, as it doesn't understand
211.Li #ifdef Ns 's ,
212(incidentally, that's a feature, not a bug) any code with unbalanced
213braces inside
214.Li #ifdef Ns 's
215will cause it to become somewhat disoriented.
216In a similar fashion, multiple line changes within a definition will
217cause it to enter the last line of the object, rather than the first, as
218the searching pattern.  The last line of multiple line
219.Li typedef Ns 's
220will similarly be noted.
221.Sh HISTORY
222The
223.Nm
224command appeared in
225.Bx 3.0 .
Note: See TracBrowser for help on using the repository browser.