Implement comment standards in org-ctags.el
This commit is contained in:
Carsten Dominik
parent
44d56dfa2d
commit
f3d72b13f4
|
|
@ -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 <eeeickythump@gmail.com>
|
||||
;;; Version: 1.0
|
||||
;; Author: Paul Sexton <eeeickythump@gmail.com>
|
||||
;; 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 <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.
|
||||
;;
|
||||
;; 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))
|
||||
;; 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)
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue