Provided by: otags_4.01.1-1_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 camlp4 for parsing. 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.

       otags can tag all files that camlp4 can parse. Internally otags  keeps  a  current  parser
       list  that  can  be modified with the options -pc (clear list), -pa (add to list), and -pr
       (reset to default).  The default value of the current parser list corresponds to  standard
       OCaml  syntax  (containing  the  parsers  r  and o, see STANDARD CAMLP4 PARSING EXTENSIONS
       below).  Each source file is parsed with a camlp4 parser into which all parsing extensions
       from the current parser list have been loaded. The camlp4 standard parsers are linked into
       otags and if the current parser list contains only such parsers then the parsing module is
       build internally. Otherwise an external camlp4 process is started.

       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  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.)

       otags  can  tag  all  files  in  a  directory tree (if option -r is given). Files that are
       generated by ocamllex or ocamlyacc or that require preprocessing  with  the  camlp4  macro
       parser  must,  however,  be  tagged in the same directory where these tools have been run.
       This is because the line directives that ocamllex and ocamlyacc put into  generated  files
       are  relative  to  the current working directory of the generating process. For the camlp4
       macro parser an INCLUDE  directive  may  be  resolved  relative  to  the  current  working
       directory  of  the  camlp4  process.  Therefore,  if  you  tag such files from a different
       directory you will get an error message.

       When tagging whole directory trees  recursively,  one  can  specify  exceptions  from  the
       current  parser  list  in  a parser hints file, see option -parser-hints and PARSING HINTS
       FILES below.

       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, see EXAMPLES below.

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.

       -I dir Add  directory  dir  to the camlp4 search path for object files for external camlp4
              parsing calls.

       -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.

       -parser-hints file
              Apply  the  parser  hints  in  the  specified file. Whenever otags tags a file that
              appears in a parser hints file, it uses the parsers specified there instead of  the
              current parser list, see PARSING HINTS FILES below.

       -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 as 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.

       -pc    Clear the current parser list.

       -pa parser
              Add  parser  to  the  current  parser  list.   If parser is not one of the standard
              parsers that are distributed with camlp4 then the following file(s) are  parsed  in
              separate  camlp4  process(es).  parser must be accepted by camlp4 -parser, that is,
              it must be a standard camlp4 parser name or  a  bytecode  file  (.cmo)  or  library
              (.cma).

       -pr    Reset  the  current  parser list to its default value (parse standard OCaml without
              extensions).

       -pp    Print the current parser list.

       -extern
              Force otags to parse all the following files with an external camlp4 process.

       -intern
              Switch back to (default) internal parsing.

PARSING HINTS FILES

       Parsing hints files are simple text files that specify parsers for certain files. This  is
       useful  when  tagging  recursively with option -r.  Here is an example for some files from
       the OCaml distribution:

           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

       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 -pa).  The remainder of the
       section contains file names, one per line.  Leading and trailing white space is ignored.

EXAMPLES

       Tag some files in the original and some in the revised syntax:

              otags original.ml -pc -pa r revised.ml -pr original.ml

       The -pc is necessary because, for camlp4, the original OCaml syntax is an extension of the
       revised  syntax.  Therefore, the default current parser list contains the parser r already
       and adding r would not change the current parser list.

       Tag files with quotations (original host syntax and revised quotation syntax):

              otags -pa rq qotation.ml

       Tag files that use the sexplib extension:

              otags -I /usr/lib/ocaml/type-conv -I  /usr/lib/ocaml/sexplib  -pa  pa_type_conv.cmo
              -pa pa_sexp_conv.cmo use_sexp.ml

       The  -I  options  specify  the directories where pa_type_conv.cmo and pa_sexp_conv.cmo are
       located on the system.

       Tag files in a subdirectory keeping the tags file in parent directory

              cd subdir; otags -o ../TAGS -add-path subdir ...

       This complicated procedure is only necessary if there are files inside  subdir  with  line
       directives  containing  relative  file  names  (for  instance,  generated  by  ocamllex or
       ocamlyacc running inside subdir) and when there are  other  sudirectories  whose  material
       should  be  added to ../TAGS.  If there are no files with relative line directives one can
       simply use "otags -r"  in  the  directory  containing  subdir.   If  there  are  no  other
       subdirectories one could put the tags file into subdir without using -o or -add-path.

STANDARD CAMLP4 PARSING EXTENSIONS

       There is currently no documentation on the names and aliases that refer to standard camlp4
       parsing modules. Also the dependencies among those modules  is  mostly  undocumented.  The
       only source for information is the file camlp4/Camlp4Bin.ml in the OCaml distribution.

       The following list describes the identifiers that camlp4 -parser treats specifically. This
       is therefore the list of standard camlp4  parsers.  For  these  identifiers  case  is  not
       significant  (they  are  piped through String.lowercase before matching). The dependencies
       listed here are treated auto-magically by camlp4 and otags.

       r, ocamlr, ocamlrevised, pa_r.cmo, camlp4ocamlrevisedparser.cmo
              Revised syntax without stream parsers.

       rr, reloaded, ocamlreloaded, camlp4ocamlreloadedparser.cmo
              Variant of the revised syntax (usage unknown).

       o, ocaml, pa_o.cmo, camlp4ocamlparser.cmo
              Original syntax without stream parsers. Depends on parser r.

       rp, rparser, pa_rp.cmo, camlp4ocamlrevisedparserparser.cmo
              Revised syntax with stream parsers. (See bug #5134 for OCaml 3.12.0  and  earlier.)
              Depends on parser r.

       op, parser, pa_op.cmo, camlp4ocamlparserparser.cmo
              Original syntax with stream parsers. Depends on parser r, o, rp

       g, grammar, pa_extend.cmo, pa_extend_m.cmo, camlp4grammarparser.cmo
              Grammar extensions.

       m, macro, pa_macro.cmo, camlp4macroparser.cmo
              Macros and conditionals.

       q, camlp4quotationexpander.cmo
              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 Camlp4QuotationCommon (common quotation infrastructure).

       rq, q_mlast.cmo, camlp4ocamlrevisedquotationexpander.cmo
              Revised Quotations. Adds quotations in  the  revised  syntax.  Host  and  quotation
              parsing   remain  independent.  Depends  on  module  Camlp4QuotationCommon  (common
              quotation infrastructure).

       oq, camlp4ocamloriginalquotationexpander.cmo
              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  ocamlr,  ocaml  and   module
              Camlp4QuotationCommon

       rf     Full  revised. Sets up revised syntax with stream parsers, grammar extensions, list
              comprehensions  and   macros   and   adds   reflective   quotations.   Depends   on
              parsers/modules r, rp, Camlp4QuotationCommon, q, g, comp, m.

       of     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 r, o, rp, op, Camlp4QuotationCommon, q, g, comp and m.

       comp, camlp4listcomprehension.cmo
              List comprehensions.

       debug, camlp4debugparser, camlp4debugparser.cmo
              Debugging statements debug and camlp4_debug.  The  expansion  of  those  statements
              depends on the value of the environment variable STATIC_CAMLP4_DEBUG such that also
              the produced tag entries might depend on this variable.

DIAGNOSTICS

       Parse errors are reported with normal camlp4 error messages. No  tags  are  generated  for
       files that produce errors. Tagging continues with the next file, in this case.

       The  error  "Original  source  not  available"  is  reported  if  the file to which a line
       directive refers cannot be found. This may happen if  otags  is  started  in  a  different
       directory than the program that generated the faulting file.

       Otags  exists  with  "Parser list empty for ..." when attempting to process a file with an
       empty current parser list.  This happens when no -pa option follows -pc.

       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.

       Escaping exceptions and assertions that terminate otags are considered as  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

BUGS

       otags dies with a parse error on open!, which was introduced in OCaml version 4.01.0,  but
       forgotten  in  camlp4, see bug #6175. For the same reason, otags 4.01.1 is likely to cause
       strange problems when used with an OCaml version that fixes #6175.

MISSING FEATURES

       Appending to vi tags files requires to reread the existing  tags  file,  because  vi  tags
       files are sorted.

       Incompatible  camlp4  syntax  trees  (from external camlp4 parsing processes) are detected
       with magic numbers. However, an incompatible camlp4 will likely die when it tries to  load
       the  otags  specific  camlp4  printer.  Such  fatal dynamic loader errors are treated like
       parsing errors, because camlp4 produces the same exit status in both cases.

CREDITS

       Cuihtlauac Alvarado and Jean-Francois Monin were the first to exploit camlp4  for  tagging
       OCaml  files.  This  version  is  a  complete  rewrite, based on the new camlp4 from OCaml
       version 3.10 and onwards.

AUTHOR

       Hendrik Tews <otags at askra.de>

SEE ALSO

       etags(1), ctags(1)