diff --git a/lisp/org-ctags.el b/lisp/org-ctags.el index d4735c9d3..35f432f33 100644 --- a/lisp/org-ctags.el +++ b/lisp/org-ctags.el @@ -1,9 +1,9 @@ ;;; org-ctags.el - Integrate Emacs "tags" facility with org mode. -;;; +;; ;; Copyright (C) 2007, 2008, 2009, 2010 Free Software Foundation, Inc. -;;; Author: Paul Sexton -;;; Version: 1.0 +;; Author: Paul Sexton +;; Version: 1.0 ;; Keywords: org, wp ;; Version: 6.36trans @@ -23,116 +23,116 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . -;;; -;;; 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 -;;; ============ -;;; -;;; Install org mode -;;; Ensure org-ctags.el is somewhere in your emacs load path. -;;; Download and install Exuberant ctags -- "http://ctags.sourceforge.net/" -;;; Edit your .emacs file (see next section) and load emacs. +;; +;; 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 +;; ============ +;; +;; Install org mode +;; Ensure org-ctags.el is somewhere in your emacs load path. +;; Download and install Exuberant ctags -- "http://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 behaviour which is to -;;; search the entire text of the current buffer for 'tag'. -;;; -;;; This behaviour 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 behaviour 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 behaviour -;;; -;;; -;;; 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-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-create-tags tags-table-list)) +;; 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 behaviour which is to +;; search the entire text of the current buffer for 'tag'. +;; +;; This behaviour 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 behaviour 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 behaviour +;; +;; +;; 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-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-create-tags tags-table-list)) (eval-when-compile (require 'cl)) (require 'org) @@ -219,7 +219,7 @@ The following patterns are replaced in the string: ;;; General utility functions. =============================================== -;;; These work outside org-ctags mode. +;; These work outside org-ctags mode. (defun org-ctags-get-filename-for-tag (tag) "TAG is a string. Search the active TAGS file for a matching tag, @@ -535,5 +535,5 @@ a new topic." (provide 'org-ctags) -;;; arch-tag: 4b1ddd5a-8529-4b17-bcde-96a922d26343 +;; arch-tag: 4b1ddd5a-8529-4b17-bcde-96a922d26343 ;;; org-ctags.el ends here