;;; org-ctags.el - Integrate Emacs "tags" facility with org mode.
-;;;
+;;
;; Copyright (C) 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
-;;; Author: Paul Sexton <eeeickythump@gmail.com>
-;;; Version: 1.0
+;; Author: Paul Sexton <eeeickythump@gmail.com>
+;; Version: 1.0
;; Keywords: org, wp
;; Version: 6.35i
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
-;;;
-;;; 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
-;;; ============
-;;;
-;;; 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 "<<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-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))
+;;
+;; 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
+;; ============
+;;
+;; 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 "<<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-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)
;;; 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,
(provide 'org-ctags)
-;;; arch-tag: 4b1ddd5a-8529-4b17-bcde-96a922d26343
+;; arch-tag: 4b1ddd5a-8529-4b17-bcde-96a922d26343
;;; org-ctags.el ends here
projects / emacs.git / commitdiff