Provided by: otags_4.05.1-3_amd64 bug

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)