Org-ctags released

* Org-ctags released
@ 2009-12-23 22:36 Paul Sexton
  2009-12-23 23:13 ` Xavier Maillard
  2009-12-25  1:17 ` Paul Sexton
  0 siblings, 2 replies; 5+ messages in thread
From: Paul Sexton @ 2009-12-23 22:36 UTC (permalink / raw)
  To: emacs-orgmode

Hi,
I have rewritten org-ctags, a package which allows org mode to use Emacs "tags"
to seamlessly navigate to link targets in other org files (as well as source
code files etc). See below for more of an explanation.

The patch to org.el now creates a hook, as suggested by Carsten. Basically, if a
[[plain link]] is not found in the current file, then each function in the list
'org-missing-link-functions' is tried in turn. Each of these functions takes one
argument (the link as a string eg "plain link") and must return non-nil if it
has successfully "handled" the link, nil otherwise. The default behaviour is to
call a new function, 'org-string-search', which does what org used to do in this
situation (just search for the string as plain text).

org-ctags.el and the patch can be obtained from a repository at:

http://bitbucket.org/eeeickythump/org-ctags/

Further documentation, from org-ctags.el:

Synopsis
========

Allows org-mode to make use of the Emacs `etags' system. Defines tag
destinations in org-mode 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-mode files. Topics can be created in any org mode file and
will always be found by plain links from other files. Other file types
recognised by ctags (source code files, latex files, etc) will also be
available as destinations for plain links, and similarly, org-mode 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
============

1. Install Emacs and org mode!
2. Put org-ctags.el somewhere in your emacs load path.
3. Apply the patch "org-el-patch.txt" to org.el. The command to do this
under Linux/Unix is:
   patch orgmode/lisp/org.el org-el-patch.txt 
4. Download and install Exuberant ctags -- "http://ctags.sourceforge.net/"
5. Edit your .emacs file (see next section) and load emacs.

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

I assume you already have org mode installed.

   (add-to-list 'load-path "/path/to/org-ctags")
   (require 'org-ctags)
   (push "/your/org/directory/" tags-table-list)
   (setq org-ctags/path-to-ctags "/path/to/ctags/executable")
   ;; The sequence below first tries to find "link" as a tag, then
   ;; offers to rebuild the TAGS file before trying again, then finally
   ;; offers to append a topic "* <<link>>" to the end of current buffer.
   (setq org-missing-link-functions
        '(org-ctags/find-tag
          org-ctags/ask-rebuild-tags-file-then-find-tag
          org-ctags/ask-append-topic))
   ;; Other functions you can put in the above list are:
   ;;   org-ctags/ask-visit-buffer-or-file -- for a link "link", visits the
   ;;     file "link.org" (optionally creating it if it doesn't exist)
   ;;   org-string-search -- the default (old) org behaviour
   (define-key org-mode-map "\C-o" 'org-ctags/find-tag-interactive) 
   (org-ctags/enable)

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-mode 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-missing-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-create-tags tags-table-list))

^ permalink raw reply	[flat|nested] 5+ messages in thread