Otags: TAGS generation for emacs and vi from Ocaml sources

===========================================================================
===========================================================================

Summary
=======

Otags can be used to build TAGS tables for emacs and vi, like etags
does, but for Ocaml code source files. It is based on camlp4 parsers
of caml, which makes it more accurate than versions based on regexps :
otags finds references to constructors of sum types, fields of
records, etc. The downside of the camlp4 approach is that you can only
tag syntactically correct files and that otags only accepts what 
camlp4 thinks is correct (which is sometimes different from ocamlc).

For installation see INSTALLATION below.

Usage :

To build TAGS for a set of files:

   otags file1.ml file2.ml ...

To build TAGS for all .ml files in a directory:

   otags dir

To build TAGS recusively:

   otags -r dir

Theses syntaxes can be mixed, see

  otags -help

for list of options available.

When searching directories, processed files are those matching the
"suffix list", which is set by default to: [".mli"; ".ml"]. This list
can be edited using the options -sc, -sa and -sr which, respectively
clears, add entries and removes entries in this list.

Addtional parser can be trown to Camlp4 using the -pa option

Otags X.Y version number match Ocaml version number. See ChangeLog for
old versions / Ocaml matching.

===========================================================================
===========================================================================

INSTALLATION
============

1- configure with

   ./configure

Recognized options are:
  --prefix <path>       installation prefix [/usr/local]
  --bindir <path>       user executables [PREFIX/bin]
  --libdir <path>       camlp4 libraries [PREFIX/lib/ocaml]
  --bytecode            don't use native compiler (for testing only)
  --no-version-check    don't check for correct ocaml version (not recommended)

The first three options set the directories where the binaries and 
the camlp4 parser libraries are installed.


The --no-version-check option disables the ocaml version check. Use 
it at your own risk (for instance when your working with the latest 
cvs version of ocaml).

2- compile with

   make all

3- acquire suitable rights and install

   make install


===========================================================================
===========================================================================

TROUBLESHOOTING
===============

Compilation fails with: gcc: .../pa_o_fast.o: No such file or directory

  You are probably using ocaml prior to 3.09.3. Versions prior to 3.09.3
  do not properly install all needed files. There are three solutions:

  1. Copy the missing files from your ocaml build directory to the 
     installation directory. Check the error messages for what is 
     missing, copy, try make again and repeat. There are about 5 files 
     missing. 

  2. After the above error, do 

      make camlp4o_pr_emacs_ext
      make camlp4o_pr_vi_ext
      mv camlp4o_pr_emacs_ext camlp4o_pr_emacs
      mv camlp4o_pr_vi_ext camlp4o_pr_vi

     and proceed with make install.

  3. Configure with --bytecode


===========================================================================
===========================================================================

Contact
=======

Please send bug reports, comments, patches, donations to 
Hendrik Tews <tews@tcs.inf.tu-dresden.de>


===========================================================================
===========================================================================

Authors
=======

From version 3.09.0 onwards

    Hendrik Tews --- TU Dresden
      <tews@tcs.inf.tu-dresden.de>
      http://www.tcs.inf.tu-dresden.de/~tews


Up to version 3.09.0

    Cuihtlauac Alvarado --- France Télécom R&D 
      <cuihtlauac.alvarado@francetelecom.com>
      http://perso.rd.francetelecom.fr/alvarado/

    Jean-Francois MONIN --- Université Joseph Fourier - VERIMAG 
      <jeanfrancois.monin@francetelecom.com>
      http://www-verimag.imag.fr/~monin/


===========================================================================
===========================================================================

Thanks
======

Francesco Potorti, CNUCE <f.potorti at cnuce.cnr.it> etags maintainer
Daniel de Rauglaudre, Inria <daniel.de rauglaudre at inria.fr> Camlp4 author
Ohad Rodeh
Kipton Barros
John Eikenberry <jae at zhar.net> vi/vim tags
Michal Moskal <malekith at pld-linux.org> vi/vim patch
Alan Schmitt <alan.schmitt at polytechnique.org> stdout patch
Pascal Brisset COPYING file forgot in distribution
Karl Zilles <zilles at 1969.ws> vi/vim string escape patch
Chris Hecker <checker at d6.com> vi/vim & win32 patches
Andrew I. Schein" <andrew at andrewschein.com> bug report
  

===========================================================================
===========================================================================

Emacs TAGS file syntax
======================

Supposed syntax for emacs TAGS (.tags) files, as analysed from output
of etags, read in etags.c and discussed with Francesco Potorti.

<file> ::= <page>+

<page> ::= <header><body>

<header> ::= <NP><CR><file-name>,<body-length><CR>

<body> ::= <tag-line>*

<tag-line> ::= <prefix><DEL><tag><SOH><line-number>,<begin-char-index><CR>

<NP> ::= ascii NP, (emacs ^L) 
<DEL> ::= ascii DEL, (emacs ^?)
<SOH> ::= ascii SOH, (emacs ^A)
<CR> :: ascii CR


===========================================================================
===========================================================================

Wish list
=========

  - tagging qualified names (e.g. Yetanothertbl.create)
  - handling .ml4 files of Coq sources