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)))
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 (7)
org-ctags-enabled-p | Activate ctags support in org mode? |
org-ctags-find-tag-history | History of tags visited by org-ctags-find-tag-interactive. |
org-ctags-new-topic-template | Text to insert when creating a new org file via opening a hyperlink. |
org-ctags-open-link-functions | List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS by ORG-CTAGS. |
org-ctags-path-to-ctags | Name of the ctags executable file. |
org-ctags-tag-list | List of all tags in the active TAGS file. |
org-ctags-tag-regexp | Regexp expression used by ctags external program. |
Defined functions (17)
org--ctags-load-tag-list | (&rest _) |
org--ctags-set-org-mark-before-finding-tag | (&rest _) |
org-ctags-all-tags-in-current-tags-table | () |
org-ctags-append-topic | (NAME &optional NARROWP) |
org-ctags-ask-append-topic | (NAME &optional NARROWP) |
org-ctags-ask-rebuild-tags-file-then-find-tag | (NAME) |
org-ctags-ask-visit-buffer-or-file | (NAME) |
org-ctags-create-tags | (&optional DIRECTORY-NAME) |
org-ctags-fail-silently | (NAME) |
org-ctags-find-tag | (NAME) |
org-ctags-find-tag-at-point | () |
org-ctags-find-tag-interactive | () |
org-ctags-get-filename-for-tag | (TAG) |
org-ctags-open-file | (NAME &optional TITLE) |
org-ctags-rebuild-tags-file-then-find-tag | (NAME) |
org-ctags-string-search-and-replace | (SEARCH REPLACE STRING) |
org-ctags-visit-buffer-or-file | (NAME &optional CREATE) |