From mboxrd@z Thu Jan 1 00:00:00 1970 From: Paul Sexton Subject: Org-ctags released Date: Wed, 23 Dec 2009 22:36:51 +0000 (UTC) Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NNZpc-0001VH-7U for emacs-orgmode@gnu.org; Wed, 23 Dec 2009 17:37:24 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NNZpX-0001UQ-J2 for emacs-orgmode@gnu.org; Wed, 23 Dec 2009 17:37:23 -0500 Received: from [199.232.76.173] (port=56670 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NNZpX-0001UL-9q for emacs-orgmode@gnu.org; Wed, 23 Dec 2009 17:37:19 -0500 Received: from lo.gmane.org ([80.91.229.12]:50757) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1NNZpW-0000cF-Pw for emacs-orgmode@gnu.org; Wed, 23 Dec 2009 17:37:19 -0500 Received: from list by lo.gmane.org with local (Exim 4.50) id 1NNZpS-0003so-50 for emacs-orgmode@gnu.org; Wed, 23 Dec 2009 23:37:14 +0100 Received: from rp.young.med.auckland.ac.nz ([130.216.140.20]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 23 Dec 2009 23:37:14 +0100 Received: from psexton by rp.young.med.auckland.ac.nz with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 23 Dec 2009 23:37:14 +0100 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org 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 <>. 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 <> 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 "* <>" 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 "<>" 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 "<>" in any other files. If it does, the matching file will be opened and the cursor will jump to the position of "<>" 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 "") '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))