OTAGS(1)

📦 version 4.05.1, in debian bookworm, ubuntu jammy

💖 OTAGS — the tag-generator bestie 💖

okay so real talk, this is the manual page for otags, and she's here to make your editor actually know where stuff lives. no more scrolling around like a lost girlie. let's get into it 💅

✨ SYNOPSIS ✨

otags [STATIC-OPTION] ... [FILE] ... [DYNAMIC-OPTION] ... [FILE] ...

🌸 DESCRIPTION 🌸

otags generates TAGS files for emacs and tags files for vi/vim so these editors can jump straight to function and value definitions — like, cursor on the symbol, hit M-. in Emacs or ^] in vi[m], and boom, you're there. main character navigation energy fr fr ✨

Here's the tea: otags uses the standard OCaml parser from the compiler-libs library. That's way more precise than regular-expression-based tagging. The downside? She can only tag files that are syntactically correct. And she's OCaml-version-specific, no cap: sources meant to be compiled with OCaml version X.Y can, in general, only be tagged with otags version X.Y. Periodt. 😤

Also, heads up bestie: this version of otags does not support -pp or -ppx preprocessors, so she cannot tag files using syntax extensions or containing top level directives. If you wanna tag everything in a whole directory tree, peep the -r option below. 🌳

otags tags all toplevel items in structures and signatures — including infix operators and nested modules and signatures. She also tags instance variables and methods in classes, because classy. 💅

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 — so if you specify relative file names on the command line, you get a tag file with relative file names. Obvi. But listen: a tag file with relative file names will only work if it's 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, no matter where they sit on 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 only affect arguments that follow them on the command line. yes, order matters, she's picky like that 💁

  • -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 a 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. iconic rebrand ngl 💖

💜 AUTHOR 💜

Hendrik Tews <otags at askra.de>

🌸 SEE ALSO 🌸

etags(1), ctags(1)

and that's the whole page bestie 🫶 this version of the otags manual page is from the User Manuals, dated August 2010, so go forth and tag slayfully. mwah 💅✨

📦 where this page comes from