File: org-ctags.el.html

Synopsis
========

Allows Org mode to make use of the Emacs etags system. Defines tag destinations in Org files as any text between <<double angled brackets>>. This allows the tags-generation program exuberant ctags to parse these files and create tag tables that record where these destinations are found. Plain [[links]] in org mode files which do not have <<matching destinations>> within the same file will then be interpreted as links to these 'tagged' destinations, allowing seamless navigation between multiple Org files. Topics can be created in any org mode file and will always be found by plain links from other files. Other file types recognized by ctags
(source code files, latex files, etc) will also be available as
destinations for plain links, and similarly, Org links will be available as tags from source files. Finally, the function org-ctags-find-tag-interactive lets you choose any known tag, using autocompletion, and quickly jump to it.

Installation
============

Download and install Exuberant ctags -- "https://ctags.sourceforge.net/" Edit your .emacs file (see next section) and load emacs.

To put in your init file (.emacs):
==================================

Assuming you already have org mode installed and set up:

   (setq org-ctags-path-to-ctags "/path/to/ctags/executable")
   (add-hook 'org-mode-hook
     (lambda ()
       (define-key org-mode-map "\\C-co" 'org-ctags-find-tag-interactive)))
   (with-eval-after-load "org-ctags"
     (org-ctags-enable))

To activate the library, you need to call org-ctags-enable explicitly. It used to be invoked during library loading, but it was against Emacs policy and caused inconvenience of Org users who do not use org-ctags.

By default, with org-ctags loaded, org will first try and visit the tag with the same name as the link; then, if unsuccessful, ask the user if he/she wants to rebuild the 'TAGS' database and try again; then ask if the user wishes to append 'tag' as a new toplevel heading at the end of the buffer; and finally, defer to org's default behavior which is to search the entire text of the current buffer for 'tag'.

This behavior can be modified by changing the value of ORG-CTAGS-OPEN-LINK-FUNCTIONS. For example, I have the following in my
.emacs, which describes the same behavior as the above paragraph with
one difference:

(setq org-ctags-open-link-functions
      '(org-ctags-find-tag
        org-ctags-ask-rebuild-tags-file-then-find-tag
        org-ctags-ask-append-topic
        org-ctags-fail-silently)) ; <-- prevents org default behavior

Usage
=====

When you click on a link "[[foo]]" and org cannot find a matching "<<foo>>" in the current buffer, the tags facility will take over. The file TAGS in the active directory is examined to see if the tags facility knows about
"<<foo>>" in any other files. If it does, the matching file will be opened
and the cursor will jump to the position of "<<foo>>" in that file.

User-visible functions:
- org-ctags-find-tag-interactive: type a tag (plain link) name and visit
  it. With autocompletion. Bound to ctrl-O in the above setup.
- All the etags functions should work. These include:

     M-. find-tag -- finds the tag at point

     C-M-. find-tag based on regular expression

     M-x tags-search RET -- like C-M-. but searches through ENTIRE TEXT
            of ALL the files referenced in the TAGS file. A quick way to
            search through an entire 'project'.

     M-* "go back" from a tag jump. Like org-mark-ring-goto.
            You may need to bind this key yourself with (eg)
            (global-set-key (kbd "<M-kp-multiply>") 'pop-tag-mark)

     (see etags chapter in Emacs manual for more)

Keeping the TAGS file up to date
================================

Tags mode has no way of knowing that you have created new tags by typing in your Org buffer. New tags make it into the TAGS file in
3 ways:

1. You re-run (org-ctags-create-tags "directory") to rebuild the file.
2. You put the function org-ctags-ask-rebuild-tags-file-then-find-tag in
   your org-open-link-functions list, as is done in the setup
   above. This will cause the TAGS file to be rebuilt whenever a link
   cannot be found. This may be slow with large file collections however.
3. You run the following from the command line (all 1 line):

     ctags --langdef=orgmode --langmap=orgmode:.org
       --regex-orgmode="/<<([^>]+)>>/\\1/d,definition/"
         -f /your/path/TAGS -e -R /your/path/*.org

If you are paranoid, you might want to run (org-ctags-create-tags
"/path/to/org/files") at startup, by including the following toplevel form
in .emacs. However this can cause a pause of several seconds if ctags has to scan lots of files.

    (progn (message "-- rebuilding tags tables...") (mapc 'org-ctags-create-tags tags-table-list))

Defined variables (8)

Defined functions (19)

Defined faces (0)