converted man page

[unix-history] / usr / src / usr.bin / ctags / ctags.1

diff --git a/usr/src/usr.bin/ctags/ctags.1 b/usr/src/usr.bin/ctags/ctags.1
index c2fd33f..91a47a8 100644 (file)
--- a/usr/src/usr.bin/ctags/ctags.1
+++ b/usr/src/usr.bin/ctags/ctags.1
@@ -1,136 +1,188 @@
-.\" Copyright (c) 1987 The Regents of the University of California.
+.\" Copyright (c) 1987, 1990 The Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" All rights reserved.
 .\"

-.\" Redistribution and use in source and binary forms are permitted
-.\" provided that the above copyright notice and this paragraph are
-.\" duplicated in all such forms and that any documentation,
-.\" advertising materials, and other materials related to such
-.\" distribution and use acknowledge that the software was developed
-.\" by the University of California, Berkeley.  The name of the
-.\" University may not be used to endorse or promote products derived
-.\" from this software without specific prior written permission.
-.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
-.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.\"    @(#)ctags.1     6.5 (Berkeley) %G%
+.\"     @(#)ctags.1    6.6 (Berkeley) %G%

 .\"
 .\"

-.TH CTAGS 1 ""
-.UC 4
-.SH NAME
-ctags \- create a tags file
-.SH SYNOPSIS
-.B ctags
-[ 
-.B \-BFadtuwvx
-] [
-.B \-f
-.I tagsfile
-]
-name ...
-.SH DESCRIPTION
-\fICtags\fP makes a tags file for \fIex\fP(1) from the specified C,
+.Dd 
+.Dt CTAGS 1
+.Os BSD 4
+.Sh NAME
+.Nm ctags
+.Nd create a tags file
+.Sh SYNOPSIS
+.Nm ctags
+.Op Fl BFadtuwvx
+.Op Fl f Ar tagsfile
+.Ar name ...
+.Sh DESCRIPTION
+.Nm Ctags
+makes a tags file for
+.Xr ex 1
+from the specified C,

 Pascal, Fortran, YACC, lex, and lisp sources.  A tags file gives the
 locations of specified objects in a group of files.  Each line of the
 tags file contains the object name, the file in which it is defined,
 and a search pattern for the object definition, separated by white-space.
 Pascal, Fortran, YACC, lex, and lisp sources.  A tags file gives the
 locations of specified objects in a group of files.  Each line of the
 tags file contains the object name, the file in which it is defined,
 and a search pattern for the object definition, separated by white-space.

-Using the \fItags\fP file, \fIex\fP(1) can quickly locate these object
-definitions.  Depending on the options provided to \fIctags\fP,
+Using the
+.Ar tags
+file,
+.Xr ex 1
+can quickly locate these object
+definitions.  Depending on the options provided to .Nm ctags  ,

 objects will consist of subroutines, typedefs, defines, structs,
 enums and unions.
 objects will consist of subroutines, typedefs, defines, structs,
 enums and unions.

-.PP
-Yacc and lex files each have a special tag.  \fIYyparse\fP is the start
-of the second section of the yacc file, and \fIyylex\fP is the start of
-the second section of the lex file.
-.PP
-If the \fB-x\fP flag is given, \fIctags\fP produces a list of object
+.Pp
+.Tp Fl x
+.Nm ctags
+produces a list of object

 names, the line number and file name on which each is defined, as well
 as the text of that line and prints this on the standard output.  This
 is a simple index which can be printed out as an off-line readable
 function index.
 names, the line number and file name on which each is defined, as well
 as the text of that line and prints this on the standard output.  This
 is a simple index which can be printed out as an off-line readable
 function index.

-.PP
-If the \fB-v\fP flag is given, an index of the form expected by
-\fIvgrind\fP(1) is produced on the standard output.  This listing
+.Pp
+.Tp Fl v
+An index of the form expected by
+.Xr vgrind 1
+is produced on the standard output.  This listing

 contains the object name, file name, and page number (assuming 64
 line pages).  Since the output will be sorted into lexicographic order,
 contains the object name, file name, and page number (assuming 64
 line pages).  Since the output will be sorted into lexicographic order,

-it may be desired to run the output through \fBsort -f\fP.
+it may be desired to run the output through
+.Xr sort 1 .

 Sample use:
 Sample use:

-.nf
-       ctags \-v files | sort \-f > index
-       vgrind \-x index
-.fi
-.PP
-Normally \fIctags\fP places the tag descriptions in a file called
-\fItags\fP; this may be overridden with the \fB-f\fP option.
-.PP
-Files whose names end in \fB.c\fP or \fB.h\fP are assumed to be C
-source files and are searched for C style routine and macro definitions.
-Files whose names end in \fB.y\fP are assumed to be YACC source files.
-Files whose names end in \fB.l\fP are assumed to be lisp files if their
-first non-blank character is `;', `(', or `[', otherwise, they are
-treated as lex files.  Other files are first examined to see if they
-contain any Pascal or Fortran routine definitions, and, if not, are
-searched for C style definitions.
-.PP
-Other options are:
-.TP 5
-.B \-F
+.Pp
+.Ds I
+ctags \-v files  sort \-f > index
+vgrind \-x index
+.De
+.Tp Fl f
+Places the tag descriptions in a file called
+.Ar tagsfile.  The default behaviour is to place them in a file
+named
+.Ar tags .
+.Tp Fl F

 use forward searching patterns (/.../) (the default).
 use forward searching patterns (/.../) (the default).

-.TP 5
-.B \-B
+.Tp Fl B

 use backward searching patterns (?...?).
 use backward searching patterns (?...?).

-.TP 5
-.B \-a
-append to \fItags\fP file.
-.TP 5
-.B \-d
-create tags for \fI#defines\fP that don't take arguments; \fI#defines\fP
+.Tp Fl a
+append to
+.Ar tags
+file.
+.Tp Fl d
+create tags for
+.Ar #defines
+that don't take arguments;
+.Ar #defines

 that take arguments are tagged automatically.
 that take arguments are tagged automatically.

-.TP 5
-.B \-t
+.Tp Fl t

 create tags for typedefs, structs, unions, and enums.
 create tags for typedefs, structs, unions, and enums.

-.TP 5
-.B \-w
+.Tp Fl w

 suppress warning diagnostics.
 suppress warning diagnostics.

-.TP 5
-.B \-u
-update the specified files in the \fItags\fP file, that is, all
+.Tp Fl u
+update the specified files in the
+.Ar tags
+file, that is, all

 references to them are deleted, and the new values are appended to the
 file.  (Beware: this option is implemented in a way which is rather
 references to them are deleted, and the new values are appended to the
 file.  (Beware: this option is implemented in a way which is rather

-slow; it is usually faster to simply rebuild the \fItags\fP file.)
-.PP
-The tag \fImain\fP is treated specially in C programs.  The tag formed
-is created by prepending \fIM\fP to the name of the file, with the
-trailing \fB.c\fP and any leading pathname components removed.  This
-makes use of \fIctags\fP practical in directories with more than one
+slow; it is usually faster to simply rebuild the
+.Ar tags
+file.)
+.Tp
+.Pp
+Files whose names end in
+.Nm \&.c
+or
+.Nm \&.h
+are assumed to be C
+source files and are searched for C style routine and macro definitions.
+Files whose names end in
+.Nm \&.y
+are assumed to be YACC source files.
+Files whose names end in
+.Nm \&.l
+are assumed to be lisp files if their
+first non-blank character is `;', `(', or `[',
+otherwise, they are
+treated as lex files.  Other files are first examined to see if they
+contain any Pascal or Fortran routine definitions, and, if not, are
+searched for C style definitions.
+.Pp
+The tag
+.Ar main
+is treated specially in C programs.  The tag formed
+is created by prepending
+.Ar M
+to the name of the file, with the
+trailing
+.Nm \&.c
+and any leading pathname components removed.  This
+makes use of
+.Nm ctags
+practical in directories with more than one

 program.
 program.

-.SH FILES
-.DT
-tags           default output tags file
-.SH DIAGNOSTICS
-\fICtags\fP exits with a value of 1 if an error occurred, where
+.Pp
+Yacc and lex files each have a special tag.
+.Ar Yyparse
+is the start
+of the second section of the yacc file, and
+.Ar yylex
+is the start of
+the second section of the lex file.
+.Sh FILES
+.Dw tags
+.Di L
+.Dp Pa tags
+default output tags file
+.Dp
+.Sh DIAGNOSTICS
+.Nm Ctags
+exits with a value of 1 if an error occurred, where

 duplicate objects are not considered errors, 0 otherwise.
 duplicate objects are not considered errors, 0 otherwise.

-.SH SEE ALSO
-ex(1), vi(1)
-.SH AUTHOR
+.Sh SEE ALSO
+.Xr ex 1 ,
+.Xr vi 1
+.Sh HISTORY
+.Nm
+appeared in 3 BSD.
+.Sh AUTHOR

 Ken Arnold; FORTRAN added by Jim Kleckner; Bill Joy added Pascal and
 Ken Arnold; FORTRAN added by Jim Kleckner; Bill Joy added Pascal and

-\fB-x\fP, replacing \fIcxref\fP; C typedefs added by Ed Pelegri-Llopart.
-.SH BUGS
-Recognition of \fBfunctions\fR, \fBsubroutines\fR and \fBprocedures\fR
+.Fl x ,
+replacing
+.Ar cxref  ;
+C typedefs added by Ed Pelegri-Llopart.
+.Sh BUGS
+Recognition of
+.Nm functions  ,
+.Nm subroutines
+and
+.Nm procedures

 for FORTRAN and Pascal is done is a very simpleminded way.  No attempt
 is made to deal with block structure; if you have two Pascal procedures
 for FORTRAN and Pascal is done is a very simpleminded way.  No attempt
 is made to deal with block structure; if you have two Pascal procedures

-in different blocks with the same name you lose.  \fICtags\fP doesn't
+in different blocks with the same name you lose.
+.Nm Ctags
+doesn't

 understand about Pascal types.
 understand about Pascal types.

-.PP
+.Pp

 The method of deciding whether to look for C, Pascal or FORTRAN
 functions is a hack.
 The method of deciding whether to look for C, Pascal or FORTRAN
 functions is a hack.

-.PP
-\fICtags\fP relies on the input being well formed, and any syntactical
+.Pp
+.Nm Ctags
+relies on the input being well formed, and any syntactical

 errors will completely confuse it.  It also finds some legal syntax
 errors will completely confuse it.  It also finds some legal syntax

-confusing; for example, as it doesn't understand \fI#ifdef\fP's,
+confusing; for example, as it doesn't understand
+.Cx Ar #ifdef
+.Cx 's,
+.Cx

 (incidentally, that's a feature, not a bug) any code with unbalanced
 (incidentally, that's a feature, not a bug) any code with unbalanced

-braces inside \fI#ifdef\fP's will cause it to become somewhat disoriented.
+braces inside
+.Cx Ar #ifdef
+.Cx 's
+will cause it to become somewhat disoriented.
+.Cx

 In a similar fashion, multiple line changes within a definition will
 cause it to enter the last line of the object, rather than the first, as
 In a similar fashion, multiple line changes within a definition will
 cause it to enter the last line of the object, rather than the first, as

-the searching pattern.  The last line of multiple line \fItypedef\fP's
+the searching pattern.  The last line of multiple line
+.Ar typedef
+'s

 will similarly be noted.
 will similarly be noted.