.\" 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
.B camlp4
for parsing. 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.
.\" ============= paragraph current parser list ===============================
.P
.B otags
can tag all files that
.B camlp4
can parse. Internally
.B otags
keeps a 
.B current parser list
that can be modified with the options
.B -pc
(clear list), 
.B -pa
(add to list), and
.B -pr 
(reset to default).
The default value of the
.B current parser list
corresponds to standard
.B OCaml
syntax (containing the parsers
.B r
and
.B o\fR,
see STANDARD CAMLP4 PARSING EXTENSIONS below).
Each source file is parsed with a
.B camlp4
parser into which all parsing extensions from the 
.B current parser list
have been loaded. The
.B camlp4
standard parsers are linked into
.B otags
and if the 
.B current parser list
contains only such parsers then the parsing module is build
internally. Otherwise an external
.B camlp4
process is started.
.\" =============== 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 and class-types.
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, 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,
see EXAMPLES below.
.\"
.\" ==========================================================================
.\" ================ 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.
.\" ================ -I ======================================================
.IP "-I dir"
Add directory dir to the 
.B camlp4
search path for object files for
external
.B camlp4
parsing calls.
.\" ================ -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. 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.
.\" ================ -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 as 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.
.\" ================ -pc =====================================================
.IP -pc
Clear the 
.B current parser list\fR.
.\" ================ -pa =====================================================
.IP "-pa parser"
Add 
.I parser
to the 
.B current parser list\fR. 
If 
.I parser
is not one of the
standard parsers that are distributed with 
.B camlp4
then the following file(s) are parsed in separate 
.B camlp4
process(es). 
.I parser
must be accepted by
.B camlp4 -parser\fR,
that is, it must be a standard camlp4 parser name or a bytecode file
.I \fR(\fI.cmo\fR) or library (\fI.cma\fR).
.\" ================ -pr =====================================================
.IP -pr
Reset the 
.B current parser list
to its default value (parse standard 
.B OCaml
without extensions).
.\" ================ -pp =====================================================
.IP -pp
Print the 
.B current parser list\fR.
.\" ================ -extern =================================================
.IP -extern
Force
.B otags
to parse all the following files with an external
.B camlp4
process.
.\" ================ -intern =================================================
.IP -intern
Switch back to (default) internal parsing. 
.\"
.\" ==========================================================================
.\" ================ 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 revised files =======================================
.B Tag some files in the original and some in the revised syntax:
.P
.RS
.B otags 
original.ml 
.B -pc -pa r
revised.ml
.B -pr
original.ml
.RE
.P
The
.B -pc
is necessary because, for 
.B camlp4\fR,
the original 
.B OCaml
syntax is an extension of the revised syntax. Therefore, the
default 
.B current parser list
contains the parser 
.B r
already and adding 
.B r
would not change the 
.B current parser list\fR.
.P
.\" ================ Quotation example =======================================
.B Tag files with quotations
(original host syntax and revised quotation syntax):
.P
.RS
.B otags -pa rq 
qotation.ml
.RE
.P
.\" ================ Sexplib example =========================================
.B Tag files that use the sexplib extension:
.P
.RS
.B otags -I 
.I /usr/lib/ocaml/type-conv 
.B -I 
.I /usr/lib/ocaml/sexplib 
.B -pa
.I pa_type_conv.cmo
.B -pa
.I pa_sexp_conv.cmo
use_sexp.ml
.RE
.P
The
.B -I
options specify the directories where 
.I  pa_type_conv.cmo 
and 
.I pa_sexp_conv.cmo
are located on the system.
.\" ================ 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.
.\"
.\" ==========================================================================
.\" ================ Camlp4 Parsing Extensions ===============================
.\" ==========================================================================
.\"
.SH STANDARD CAMLP4 PARSING EXTENSIONS
There is currently no documentation on the names and aliases that
refer to standard
.B camlp4
parsing modules. Also the dependencies among those modules is
mostly undocumented. The only source for information is the file
.I camlp4/Camlp4Bin.ml
in the 
.B OCaml
distribution.
.P
The following list describes the identifiers that
.B camlp4 -parser
treats specifically. This is therefore the list of standard
.B camlp4
parsers. For these identifiers case is not significant (they are
piped through
.B String.lowercase
before matching). The dependencies listed here are treated
auto-magically by
.B camlp4
and 
.B otags\fR. 
.\" ================ ocamlr ==================================================
.IP "\fBr\fR, \fBocamlr\fR, \fBocamlrevised\fR, \fBpa_r.cmo\fR, \fBcamlp4ocamlrevisedparser.cmo\fR"
Revised syntax without stream parsers.
.\" ================ reloaded ================================================
.IP "\fBrr\fR, \fBreloaded\fR, \fBocamlreloaded\fR, \fBcamlp4ocamlreloadedparser.cmo\fR"
Variant of the revised syntax (usage unknown).
.\" ================ ocaml ===================================================
.IP "\fBo\fR, \fBocaml\fR, \fBpa_o.cmo\fR, \fBcamlp4ocamlparser.cmo\fR"
Original syntax without stream parsers. Depends on parser
.B r\fR.
.\" ================ rparser =================================================
.IP "\fBrp\fR, \fBrparser\fR, \fBpa_rp.cmo\fR, \fBcamlp4ocamlrevisedparserparser.cmo\fR"
Revised syntax with stream parsers. (See bug #5134 for OCaml
3.12.0 and earlier.)
Depends on parser 
.B r\fR.
.\" ================ parser ==================================================
.IP "\fBop\fR, \fBparser\fR, \fBpa_op.cmo\fR, \fBcamlp4ocamlparserparser.cmo\fR"
Original syntax with stream parsers. Depends on parser
.B r\fR, \fBo\fR, \fBrp
.\" ================ grammar =================================================
.IP "\fBg\fR, \fBgrammar\fR, \fBpa_extend.cmo\fR, \fBpa_extend_m.cmo\fR, \fBcamlp4grammarparser.cmo\fR" 
Grammar extensions.
.\" ================ macro ===================================================
.IP "\fBm\fR, \fBmacro\fR, \fBpa_macro.cmo\fR, \fBcamlp4macroparser.cmo\fR" 
Macros and conditionals.
.\" ================ camlp4quotationexpander =================================
.IP "\fBq\fR, \fBcamlp4quotationexpander.cmo\fR" 
Reflective Quotations. This parsing extension takes the current
host syntax and adds quotation expanders using that current
syntax such that the resulting grammar is reflective: Changing
the host syntax afterwards does also affect the quotation syntax.
Depends on module 
.B Camlp4QuotationCommon
(common quotation infrastructure).
.\" ================ q_mlast =================================================
.IP "\fBrq\fR, \fBq_mlast.cmo\fR, \fBcamlp4ocamlrevisedquotationexpander.cmo\fR" 
Revised Quotations. Adds quotations in the revised syntax. Host
and quotation parsing remain independent. Depends on module
.B Camlp4QuotationCommon
(common quotation infrastructure).
.\" ================ camlp4ocamloriginalquotationexpander ====================
.IP "\fBoq\fR, \fBcamlp4ocamloriginalquotationexpander.cmo\fR" 
Original OCaml with original quotations. Loads original OCaml
(without stream parsers) as host syntax and as quotation syntax.
Host and quotation syntax are independent (not reflective).
Depends on parser
.B ocamlr\fR, \fBocaml\fR and module \fBCamlp4QuotationCommon\fR
.\" ================ rf ======================================================
.IP "\fBrf\fR"
Full revised. Sets up revised syntax with stream parsers, grammar
extensions, list comprehensions and macros and adds reflective
quotations. Depends on parsers/modules
.B r\fR, \fBrp\fR, \fBCamlp4QuotationCommon\fR, \fBq\fR, \fBg\fR, \fBcomp\fR, \fBm\fR.
.\" ================ of ======================================================
.IP "\fBof\fR"
Original full. Sets up original OCaml with stream parsers,
grammar extensions, list comprehensions and macros and adds
reflective quotations (i.e., quotations are in original syntax).
(See bug #5129 for OCaml 3.12.0 and earlier.)
Depends on parsers/modules
.B r\fR, \fBo\fR, \fBrp\fR, \fBop\fR, \fBCamlp4QuotationCommon\fR, \fBq\fR, \fBg\fR, \fBcomp\fR and \fBm\fR.
.\" ================ comp ====================================================
.IP "\fBcomp\fR, \fBcamlp4listcomprehension.cmo\fR" 
List comprehensions.
.\" ================ debug ===================================================
.IP "\fBdebug\fR, \fBcamlp4debugparser\fR, \fBcamlp4debugparser.cmo\fR"
Debugging statements 
.I debug
and
.I camlp4_debug\fR.
The expansion of those statements depends on the value of the
environment variable
.B STATIC_CAMLP4_DEBUG
such that also the produced tag entries might depend on this variable.
.\"
.\" ==========================================================================
.\" ================ Diagnostics =============================================
.\" ==========================================================================
.\"
.SH DIAGNOSTICS
.\" ============= paragraph general purpose ==================================
Parse errors are reported with normal
.B camlp4
error messages. No tags are generated for files that produce
errors. Tagging continues with the next file, in this case. 
.P
.\" ============= paragraph orig source not avail ============================
The error "Original source not available" is reported if the file
to which a line directive refers cannot be found. This may happen
if 
.B otags
is started in a different directory than the program that
generated the faulting file.
.P
.\" ============= paragraph parser list empty ================================
.B Otags
exists with "Parser list empty for ..." when attempting
to process a file with an empty
.B current parser list\fR. 
This happens when no 
.B -pa
option follows
.B -pc\fR.
.P
.\" ============= paragraph toplevel directives ==============================
.B Otags
prints "Toplevel directive found in ... Skip file." for files
containing toplevel directives. The problem is that the location
information in the abstract syntax tree is incorrect after
toplevel directives, see bug #5127.
.P
.\" ============= paragraph excaping exceptions ==============================
Escaping exceptions and assertions that terminate 
.B otags
are considered as 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
.\"
.\" ==========================================================================
.\" ================ Bugs ====================================================
.\" ==========================================================================
.\"
.SH BUGS
.\" ============= parse error on open! =======================================
.B otags
dies with a parse error on open!, which was introduced in
.B OCaml
version 4.01.0, but forgotten in
.B camlp4\fR,
see bug #6175. For the same reason,
.B otags
4.01.1 is likely to cause strange problems when used with an
.B OCaml
version that fixes #6175.
.\"
.\" ==========================================================================
.\" ================ 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 DynLoader error ==============================
Incompatible
.B camlp4
syntax trees (from external 
.B camlp4
parsing processes) are detected with magic numbers. However, an
incompatible 
.B camlp4
will likely die when it tries to load the 
.B otags
specific
.B camlp4
printer. Such fatal dynamic loader errors are treated like
parsing errors, because 
.B camlp4
produces the same exit status in both cases.
.\"
.\" ==========================================================================
.\" ================ Credits =================================================
.\" ==========================================================================
.\"
.SH CREDITS
Cuihtlauac Alvarado and Jean-Francois Monin were the first to
exploit
.B camlp4
for tagging 
.B OCaml
files. This version is a complete rewrite,
based on the new
.B camlp4
from 
.B OCaml
version 3.10 and onwards.
.\"
.\" ==========================================================================
.\" ================ 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