Implement comment standards in org-ctags.el

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 <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.
-
-;;; 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)
@@ -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