OTAGS
Section: User Manuals (1)
Updated: August 2010
Index
NAME
otags - generate tags files for emacs and vi/vim from OCaml sources
SYNOPSIS
otags
[STATIC-OPTION] ... [FILE] ... [DYNAMIC-OPTION] ... [FILE] ...
DESCRIPTION
otags
generates
TAGS
files for
emacs
and
tags
files for
vi/vim
to give these editors the ability to directly jump to function
and value definitions (use
M-.
in Emacs and
^]
in vi[m] with the cursor on the symbol).
otags
uses the standard
OCaml
parser from the
compiler-libs
library. This is more precise than regular expression based
tagging. On the downside,
otags
can only tag syntactically correct files. Furthermore,
otags
is
OCaml
version specific: Sources to be compiled with
OCaml
version
X.Y
can, in general, only be tagged with
otags
version
X.Y.
This version of
otags
does not support
-pp
or
-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
-r
below.
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
FILE
on the command line are parsed as interfaces if they have a
.mli
suffix and as implementations if they have a
.ml
suffix. (See also the dynamic options
-intf
and
-impl.)
Tag files can contain absolute and/or relative file names.
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
otags
was started.
Otags
supports writing a tags file with relative file names in a parent
directory via option
-add-path.
STATIC OPTIONS
Static options take effect on the whole program run, regardless
of their position in the command line.
- -r
-
Descend into directories. With this option, if one of the
FILE
arguments is a directory
otags
will recursively tag all files in this whole directory tree.
- -o file
-
Write tags to
file.
The default is
TAGS
(for
emacs)
and
tags
for
vi
(if the
-vi
option is given) in the current directory. If
file
is a dash (
-
) the tags are written to standard output.
- -a
-
Append to an existing TAGS file (does only work for emacs TAGS files).
- -vi
-
Generate tags for
vi
and change the default output file into
tags.
- -add-path path
-
Add
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.
- -version
-
Print version and exit.
- -v
-
Verbose. Print file names as they are parsed and the command
lines for externally started
camlp4
parsing processes (if any). If
-v
is the first command line argument, backtraces for exceptions are
enabled and printed if an exception escapes and terminates
otags
(which is considered a bug, about which I would appreciate a
bug report).
- -q
-
Be quiet.
- -help
-
Print the option list.
- --help
-
Alias for
-help
DYNAMIC OPTIONS
Dynamic options do only affect arguments that follow them on the
command line.
- -intf FILE
-
Parse and tag
FILE
as an interface.
- -impl FILE
-
Parse and tag
FILE
as implementation.
EXAMPLES
Tag all
.ml
and
.mli
files in the current directory tree:
-
otags
-r .
Files with syntax errors will be ignored. The error messages can
be disabled with option
-q.
DIAGNOSTICS
Parse errors are reported with normal
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.
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.
For files containing a toplevel directive,
Otags
simply reports a syntax error (as
ocamlc
does).
Escaping exceptions and assertions that terminate
otags
are considered to be bugs. If they occur, please use option
-v
as
first
command line switch to obtain an exception backtrace and submit this
with all relevant information as bug report.
EXIT STATUS
- 0
-
everything went OK
- 1
-
a parse error or some other error occurred and
otags
skipped the affected file
- 2
-
a fatal error caused
otags
to abort
- 3
-
some bug caused a crash, from which
otags
could only marginally recover
MISSING FEATURES
Appending to vi tags files requires to reread the existing tags
file, because vi tags files are sorted.
-pp
and
-ppx
preprocessors are currently not supported.
HISTORY
The first
camlp4
based
OCaml
tagger has been written by Cuihtlauac Alvarado and Jean-Francois
Monin. Around 2005 I took over and released a few versions for
OCaml
3.09. All
otags
versions released up to 3.09.3.3 were written for the original
camlp4,
which is now available as
camlp5.
For 3.11 I rewrote
otags
from scratch for the new
camlp4
and released
several versions under the name
otags reloaded.
The modular structure of
camlp4
made it possible to switch the parsing engine at runtime between
files and to parse all syntax supported by
camlp4
at full native speed without external
camlp4
processes. However, the increasing incompatibility between
camlp4
and
OCaml
and
camlp4's
sloppiness on parsing locations created more and more
difficulties. For instance,
4.02 failed on the
OCaml
standard library because
camlp4
was unable to digest the attribute annotations in there.
Starting from 4.03,
otags
is based on the standard
OCaml
parser from the
compiler-libs
library and has been renamed to
otags III.
AUTHOR
Hendrik Tews <otags at askra.de>
SEE ALSO
etags(1),
ctags(1)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- STATIC OPTIONS
-
- DYNAMIC OPTIONS
-
- EXAMPLES
-
- DIAGNOSTICS
-
- EXIT STATUS
-
- MISSING FEATURES
-
- HISTORY
-
- AUTHOR
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 18:17:00 GMT, August 26, 2017