.\" groff -man -Tascii foo.1
.\"
.TH OTAGS 1 "August 2010" OTAGS "User Manuals"
.SH NAME
otags \- generate tags files for emacs and vi/vim from OCaml sources
.SH SYNOPSIS
.B otags
[\fISTATIC-OPTION\fR] ... [\fIFILE\fR] ... [\fIDYNAMIC-OPTION\fR] ... [\fIFILE\fR] ...
.SH DESCRIPTION
.\" ============= paragraph general purpose ===================================
.B otags
generates
.I TAGS
files for 
.B emacs
and
.I tags
files for
.B vi\fR/\fBvim
to give these editors the ability to directly jump to function
and value definitions (use 
.B M-.
in Emacs and
.B ^]
in vi[m] with the cursor on the symbol).
.\" ============= paragraph camlp4 compatibility ==============================
.P
.B otags
uses the standard
.B OCaml
parser from the
.I compiler-libs
library. This is more precise than regular expression based
tagging. On the downside, 
.B otags
can only tag syntactically correct files. Furthermore,
.B otags
is 
.B OCaml
version specific: Sources to be compiled with 
.B OCaml 
version 
.I X.Y
can, in general, only be tagged with 
.B otags
version
.I X.Y\fR.
This version of
.B otags
does not support
.I -pp
or
.I -ppx
preprocessors and can therefore not tag files using syntax
extensions or containing top level directives. For tagging all
files in a directory tree, see option
.B -r
below.
.\" =============== paragraph what is tagged =================================
.P
.B otags
tags all toplevel items in structures and signatures, including
infix operators and nested modules and signatures. It also tags
instance variables and methods in classes.
Filenames 
.B FILE
on the command line are parsed as interfaces if they have a 
.B .mli
suffix and as implementations if they have a
.B .ml
suffix. (See also the dynamic options 
.B -intf
and
.B -impl\fR.)
.\" =============== paragraph recursive directories ==========================
.\" .P
.\" .B otags
.\" can tag all files in a directory tree (if option
.\" .B -r
.\" is given). Files that are generated by
.\" .B ocamllex
.\" or
.\" .B ocamlyacc
.\" or that require preprocessing with the 
.\" .B camlp4 macro
.\" parser must, however, be tagged in the same directory where these
.\" tools have been run. This is because the line directives that
.\" .B ocamllex
.\" and
.\" .B ocamlyacc
.\" put into generated files are relative to the current working
.\" directory of the generating process. For the
.\" .B camlp4 macro
.\" parser an 
.\" .B INCLUDE
.\" directive may be resolved relative to the current working
.\" directory of the
.\" .B camlp4
.\" process. Therefore, if you tag such files from a different
.\" directory you will get an error message. 
.\" =============== paragraph hint files =====================================
.\" .P
.\" When tagging whole directory trees recursively, one can specify
.\" exceptions from the
.\" .B current parser list
.\" in a parser hints file or directory tree, see option
.\" .B -parser-hints
.\" and PARSING HINTS FILES below.
.\" =============== paragraph absolute and relative path =====================
.P
Tag files can contain absolute and/or relative file names. 
.B Otags
uses the file names from the command line for the tags file.
Specifying relative file names on the command line will therefore
give you a tag file with relative file names. Obviously, a tag
file with relative file names will only work if it is located in
the directory where
.B otags
was started. 
.B Otags 
supports writing a tags file with relative file names in a parent
directory via option
.I -add-path\fR.
.\"
.\" ==========================================================================
.\" ================ Static Options ==========================================
.\" ==========================================================================
.\"
.SH STATIC OPTIONS
Static options take effect on the whole program run, regardless
of their position in the command line.
.\" ==========================================================================
.IP -r
Descend into directories. With this option, if one of the 
.I FILE
arguments is a directory 
.B otags
will recursively tag all files in this whole directory tree.
.\" ================ -o ======================================================
.IP "-o file"
Write tags to
.I file\fR.
The default is
.I TAGS
(for
.B emacs\fR)
and 
.I tags
for 
.B vi
(if the 
.B -vi
option is given) in the current directory. If
.I file
is a dash (
.I -
) the tags are written to standard output.
.\" ================ -a ======================================================
.IP -a
Append to an existing TAGS file (does only work for emacs TAGS files).
.\" ================ -vi =====================================================
.IP -vi
Generate tags for 
.B vi
and change the default output file into
.I tags\fR.
.\" ================ -add-path ===============================================
.IP "-add-path path"
Add
.I path
at the front of every relative file name in the tags file.
Useful when you want to put the tags file in a parent directory.
.\" ================ -parser-hints ===========================================
.\" .IP "-parser-hints file"
.\" Apply the parser hints in the specified file or directory tree. Whenever
.\" .B otags
.\" tags a file that appears in a parser hints file, it uses the
.\" parsers specified there instead of the
.\" .B current parser list\fR,
.\" see PARSING HINTS FILES below. This option can be given multiple
.\" times to process several hints files. If
.\" .I file
.\" is a directory then all files in that tree are processed as parser
.\" hints files.
.\" ================ -version ================================================
.IP -version
Print version and exit.
.\" ================ -v ======================================================
.IP -v
Verbose. Print file names as they are parsed and the command
lines for externally started 
.B camlp4
parsing processes (if any). If
.B -v
is the first command line argument, backtraces for exceptions are
enabled and printed if an exception escapes and terminates 
.B otags
(which is considered a bug, about which I would appreciate a
bug report).
.\" ================ -q ======================================================
.IP -q
Be quiet.
.\" ================ -help ===================================================
.IP -help
Print the option list.
.\" ================ --help ==================================================
.IP --help
Alias for
.B -help
.\"
.\" ==========================================================================
.\" ================ Dynamic Options =========================================
.\" ==========================================================================
.\"
.SH DYNAMIC OPTIONS
Dynamic options do only affect arguments that follow them on the
command line. 
.\" ================ -intf ===================================================
.IP "-intf FILE"
Parse and tag 
.B FILE
as an interface.
.\" ================ -impl ===================================================
.IP "-impl FILE"
Parse and tag
.B FILE
as implementation.
.\"
.\" ==========================================================================
.\" ================ Parsing Hints ===========================================
.\" ==========================================================================
.\"
.\" .SH PARSING HINTS FILES
.\" Parsing hints files are simple text files that specify parsers
.\" for certain files. This is useful when tagging recursively with
.\" option 
.\" .B -r\fR.
.\" Here is an example for some files from the
.\" .B OCaml
.\" distribution:
.\" .PP
.\" .in +4n
.\" .nf
.\" oq:
.\" 	camlp4/examples/parse_files.ml
.\" o rq g:
.\" 	camlp4/examples/macros.ml
.\" 	camlp4/examples/arith.ml
.\" rf debug:
.\" 	camlp4/Camlp4Bin.ml
.\" 	camlp4/mkcamlp4.ml
.\" 	camlp4/camlp4prof.ml
.\" 	camlp4/camlp4prof.mli
.\" .fi
.\" .in
.\" .PP
.\" =============== paragraph format =========================================
.\" .P
.\" The format of parser hints files is as follows. Empty lines and
.\" lines starting with ``#'' are ignored. A parser hints file
.\" consists of an arbitrary number of sections. Each section starts
.\" with a colon terminated line that specifies the parser to use
.\" with a space separated list of parser names (like those accepted
.\" by option 
.\" .B -pa\fR). 
.\" The remainder of the section contains file names, one per line.
.\" Leading and trailing white space is ignored.
.\"
.\" ==========================================================================
.\" ================ Examples ================================================
.\" ==========================================================================
.\"
.SH EXAMPLES
.\" ================ tag directory tryee =====================================
.B Tag all
.I .ml
and
.I .mli
files in the current directory tree:
.P
.RS
.B otags 
.B -r \fR.
.RE
.P
Files with syntax errors will be ignored. The error messages can
be disabled with option
.I -q\fR.
.P
.\" ================ subdir example =======================================
.\" .P
.\" .B Tag files in a subdirectory keeping the tags file in parent directory
.\" .P
.\" .RS
.\" cd 
.\" .I subdir\fR;
.\" .B otags 
.\" \-o 
.\" .I ../TAGS
.\" \-add-path
.\" .I subdir\fR ...
.\" .RE
.\" .P
.\" This complicated procedure is only necessary if there are files inside
.\" .I subdir 
.\" with line directives containing relative file names (for
.\" instance, generated by 
.\" .B ocamllex
.\" or
.\" .B ocamlyacc
.\" running inside 
.\" .I subdir\fR) 
.\" and when there are other sudirectories whose material should be
.\" added to 
.\" .I ../TAGS\fR.
.\" If there are no files with relative line directives one can
.\" simply use 
.\" .B \fR"\fBotags\fR -r" 
.\" in the directory containing 
.\" .I subdir\fR.
.\" If there are no other subdirectories one could put the tags file
.\" into
.\" .I subdir
.\" without using \-o or \-add-path.
.\"
.\" ==========================================================================
.\" ================ Diagnostics =============================================
.\" ==========================================================================
.\"
.SH DIAGNOSTICS
.\" ============= paragraph general purpose ==================================
Parse errors are reported with normal
.B OCaml
error messages. No tags are generated for files that produce
errors. Tagging continues with the next file, in this case.
Warnings are always completely disabled.
.P
.\" ============= paragraph orig source not avail ============================
The errors "Original source not available" and "The parser
delivered an invalid location" 
might be reported if the file contains a line directive that refers to
a position and/or a file that cannot be resolved.
.P
.\" ============= paragraph toplevel directives ==============================
For files containing a toplevel directive,
.B Otags
simply reports a syntax error (as
.B ocamlc
does). 
.P
.\" ============= paragraph excaping exceptions ==============================
Escaping exceptions and assertions that terminate 
.B otags
are considered to be bugs. If they occur, please use option
.B -v
as 
.B first
command line switch to obtain an exception backtrace and submit this
with all relevant information as bug report.
.\"
.\" ==========================================================================
.\" ================ Exit status =============================================
.\" ==========================================================================
.\"
.SH EXIT STATUS
.IP "0"
everything went OK
.IP "1"
a parse error or some other error occurred and 
.B otags
skipped the affected file
.IP "2"
a fatal error caused 
.B otags 
to abort
.IP "3"
some bug caused a crash, from which 
.B otags
could only marginally recover
.\"
.\" ==========================================================================
.\" ================ KNOWN PROBLEMS ==========================================
.\" ==========================================================================
.\"
.\"
.\" ==========================================================================
.\" ================ Missing Features ========================================
.\" ==========================================================================
.\"
.SH MISSING FEATURES
Appending to vi tags files requires to reread the existing tags
file, because vi tags files are sorted.
.P
.\" ============= paragraph -pp -ppx =========================================
.I -pp
and
.I -ppx
preprocessors are currently not supported.
.\"
.\" ==========================================================================
.\" ================ Credits =================================================
.\" ==========================================================================
.\"
.SH HISTORY
.\" ============= paragraph early french versions ============================
The first
.B camlp4
based
.B OCaml
tagger has been written by Cuihtlauac Alvarado and Jean-Francois
Monin. Around 2005 I took over and released a few versions for
.B OCaml
3.09. All
.B otags
versions released up to 3.09.3.3 were written for the original
.B camlp4\fR,
which is now available as
.B camlp5\fR.
.P
.\" ============= paragraph otags reloaded ===================================
For 3.11 I rewrote
.B otags
from scratch for the new
.B camlp4
and released
several versions under the name
.B otags reloaded\fR.
The modular structure of
.B camlp4
made it possible to switch the parsing engine at runtime between
files and to parse all syntax supported by
.B camlp4
at full native speed without external
.B camlp4
processes. However, the increasing incompatibility between
.B camlp4
and
.B OCaml
and
.B camlp4\fR's
sloppiness on parsing locations created more and more
difficulties. For instance,
.b otags
4.02 failed on the
.B OCaml
standard library because
.B camlp4
was unable to digest the attribute annotations in there.
.P
.\" ============= paragraph otags III ========================================
Starting from 4.03,
.B otags
is based on the standard
.B OCaml
parser from the
.I compiler-libs
library and has been renamed to
.B otags III\fR.
.\"
.\" ==========================================================================
.\" ================ Author ==================================================
.\" ==========================================================================
.\"
.SH AUTHOR
Hendrik Tews <otags at askra.de>
.\"
.\" ==========================================================================
.\" ================ See also ================================================
.\" ==========================================================================
.\"
.SH "SEE ALSO"
.BR etags (1),
.BR ctags (1)
.\"
.\"
.\" Local Variables:
.\" ispell-local-dictionary:"american"
.\" mode:flyspell
.\" End:
.\" 
.\" LocalWords: ctags