Use defgroup and defcustom.

Many doc fixes.
(ffap-next): Fix message.

1 files changed, 91 insertions, 47 deletions

diff --git a/lisp/ffap.el b/lisp/ffap.el
index a4d69ec0eb6..bb4c4612c83 100644
--- a/lisp/ffap.el
+++ b/lisp/ffap.el
@@ -1,6 +1,6 @@
-;;; ffap.el --- find file or url at point
+;;; ffap.el --- find file or URL at point
 
-;; Copyright (C) 1995, 1996 Free Software Foundation, Inc.
+;; Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
 
 ;; Author: Michelangelo Grigni <mic@mathcs.emory.edu>
 ;; Created: 29 Mar 1993
@@ -29,7 +29,7 @@
 ;;
 ;; Command find-file-at-point replaces find-file.  With a prefix, it
 ;; behaves exactly like find-file.  Without a prefix, it first tries
-;; to guess a default file or url from the text around the point
+;; to guess a default file or URL from the text around the point
 ;; (`ffap-require-prefix' swaps these behaviors).  This is useful for
 ;; following references in situations such as mail or news buffers,
 ;; README's, MANIFEST's, and so on.  Submit bugs or suggestions with
@@ -64,12 +64,12 @@
 ;;
 ;; (setq ffap-alist nil)                ; faster, dumber prompting
 ;; (setq ffap-machine-p-known 'accept)  ; no pinging
-;; (setq ffap-url-regexp nil)           ; disable url features in ffap
+;; (setq ffap-url-regexp nil)           ; disable URL features in ffap
 ;;
-;; ffap uses w3 (if found) or else browse-url to fetch url's.  For
+;; ffap uses w3 (if found) or else browse-url to fetch URL's.  For
 ;; a hairier `ffap-url-fetcher', try ffap-url.el (same ftp site).
 ;; Also, you can add `ffap-menu-rescan' to various hooks to fontify
-;; the file and url references within a buffer.
+;; the file and URL references within a buffer.
 
 ;;; Todo list:
 ;; * recognize paths inside /usr/bin:/bin:/etc, ./ffap.el:80:
@@ -101,6 +101,11 @@
 
 ;;; User Variables:
 
+(defgroup ffap nil
+  "Find file or URL at point."
+  :group 'matching)
+
+
 ;; This function is used inside defvars:
 (defun ffap-soft-value (name &optional default)
   "Return value of symbol with NAME, if it is interned.
@@ -110,7 +115,7 @@ Otherwise return nil (or the optional DEFAULT value)."
     (if (and sym (boundp sym)) (symbol-value sym) default)))
 
 
-(defvar ffap-ftp-regexp
+(defcustom ffap-ftp-regexp
   (and
    (or (featurep 'ange-ftp)
        (featurep 'efs)
@@ -119,29 +124,41 @@ Otherwise return nil (or the optional DEFAULT value)."
                 (rassq 'efs-file-handler-function file-name-handler-alist))))
    ;; Apparently this is good enough for both ange-ftp and efs:
    "\\`/[^/:]+:")
-  "*Treat paths matching this as remote ftp paths.  Nil to disable.
-Nil also disables the generation of such paths by ffap.")
-
-(defvar ffap-url-unwrap-local t
-  "*If non-nil, convert \"file:\" url to local path before prompting.")
-
-(defvar ffap-url-unwrap-remote t
-  "*If non-nil, convert \"ftp:\" url to remote path before prompting.
-This is ignored if `ffap-ftp-regexp' is nil.")
-
-(defvar ffap-ftp-default-user
+  "*Treat paths matching this as remote ftp paths.  nil to disable.
+nil also disables the generation of such paths by ffap."
+  :type '(choice (const :tag "Disable" nil)
+                 regexp)
+  :group 'ffap)
+
+(defcustom ffap-url-unwrap-local t
+  "*If non-nil, convert \"file:\" URL to local path before prompting."
+  :type 'boolean
+  :group 'ffap)
+
+(defcustom ffap-url-unwrap-remote t
+  "*If non-nil, convert \"ftp:\" URL to remote path before prompting.
+This is ignored if `ffap-ftp-regexp' is nil."
+  :type 'boolean
+  :group 'ffap)
+
+(defcustom ffap-ftp-default-user
   (if (or (equal (ffap-soft-value "ange-ftp-default-user") "anonymous")
           (equal (ffap-soft-value "efs-default-user") "anonymous"))
       nil
     "anonymous")
   "*User name in ftp paths generated by `ffap-host-to-path'.
-Nil to rely on `efs-default-user' or `ange-ftp-default-user'.")
+nil to rely on `efs-default-user' or `ange-ftp-default-user'."
+  :type '(choice (const :tag "Default" nil)
+                 string)
+  :group 'ffap)
 
-(defvar ffap-rfs-regexp
+(defcustom ffap-rfs-regexp
   ;; Remote file access built into file system?  HP rfa or Andrew afs:
   "\\`/\\(afs\\|net\\)/."
   ;; afs only: (and (file-exists-p "/afs") "\\`/afs/.")
-  "*Matching paths are treated as remote.  Nil to disable.")
+  "*Matching paths are treated as remote.  nil to disable."
+  :type 'regexp
+  :group 'ffap)
 
 (defvar ffap-url-regexp
   ;; Could just use `url-nonrelative-link' of w3, if loaded.
@@ -153,11 +170,13 @@ Nil to rely on `efs-default-user' or `ange-ftp-default-user'.")
    "\\(ftp\\|http\\|telnet\\|gopher\\|www\\|wais\\)://" ; needs host
    "\\)."                               ; require one more character
    )
-   "Regexp matching url's.  Nil to disable url features in ffap.")
+   "Regexp matching URL's.  nil to disable URL features in ffap.")
 
-(defvar ffap-foo-at-bar-prefix "mailto"
-  "*Presumed url prefix type of strings like \"<foo.9z@bar>\".
-Sensible values are nil, \"news\", or \"mailto\".")
+(defcustom ffap-foo-at-bar-prefix "mailto"
+  "*Presumed URL prefix type of strings like \"<foo.9z@bar>\".
+Sensible values are nil, \"news\", or \"mailto\"."
+  :type 'string
+  :group 'ffap)
 
 
 ;;; Peanut Gallery:
@@ -168,30 +187,39 @@ Sensible values are nil, \"news\", or \"mailto\".")
 ;; through this section for features that you like, put an appropriate
 ;; enabler in your .emacs file.
 
-(defvar ffap-dired-wildcards nil        ; "[*?][^/]*$"
+(defcustom ffap-dired-wildcards nil     ; "[*?][^/]*$"
   ;; Suggestion from RHOGEE, 07 Jul 1994.  Disabled, dired is still
   ;; available by "C-x C-d <pattern>", and valid filenames may
   ;; sometimes contain wildcard characters.
   "*A regexp matching filename wildcard characters, or nil.
 If `find-file-at-point' gets a filename matching this pattern,
-it passes it on to `dired' instead of `find-file'.")
+it passes it on to `dired' instead of `find-file'."
+  :type '(choice (const :tag "off" nil)
+                 regexp)
+  :group 'ffap)
 
-(defvar ffap-newfile-prompt nil         ; t
+(defcustom ffap-newfile-prompt nil              ; t
   ;; Suggestion from RHOGEE, 11 Jul 1994.  Disabled, I think this is
   ;; better handled by `find-file-not-found-hooks'.
-  "*Whether `find-file-at-point' prompts about a nonexistent file.")
+  "*Whether `find-file-at-point' prompts about a nonexistent file."
+  :type 'boolean
+  :group 'ffap)
 
-(defvar ffap-require-prefix nil
+(defcustom ffap-require-prefix nil
   ;; Suggestion from RHOGEE, 20 Oct 1994.
   "*If set, reverses the prefix argument to `find-file-at-point'.
 This is nil so neophytes notice ffap.  Experts may prefer to disable
-ffap most of the time.")
-
-(defvar ffap-file-finder 'find-file
-  "*The command called by `find-file-at-point' to find a file.")
+ffap most of the time."
+  :type 'boolean
+  :group 'ffap)
+
+(defcustom ffap-file-finder 'find-file
+  "*The command called by `find-file-at-point' to find a file."
+  :type 'function
+  :group 'ffap)
 (put 'ffap-file-finder 'risky-local-variable t)
 
-(defvar ffap-url-fetcher
+(defcustom ffap-url-fetcher
   (cond ((fboundp 'w3-fetch) 'w3-fetch)
         ((fboundp 'browse-url-netscape) 'browse-url-netscape)
         (t 'w3-fetch))
@@ -200,7 +228,9 @@ ffap most of the time.")
   ;; http://home.netscape.com/newsref/std/x-remote.html
   "*A function of one argument, called by ffap to fetch an URL.
 Reasonable choices are `w3-fetch' or `browse-url-netscape'.
-For a fancier alternative, get ffap-url.el.")
+For a fancier alternative, get ffap-url.el."
+  :type 'function
+  :group 'ffap)
 (put 'ffap-url-fetcher 'risky-local-variable t)
 
 
@@ -210,7 +240,7 @@ For a fancier alternative, get ffap-url.el.")
 ;; then, broke it up into ffap-next-guess (noninteractive) and
 ;; ffap-next (a command).  It now work on files as well as url's.
 
-(defvar ffap-next-regexp
+(defcustom ffap-next-regexp
   ;; If you want ffap-next to find URL's only, try this:
   ;; (and ffap-url-regexp (string-match "\\\\`" ffap-url-regexp)
   ;;      (concat "\\<" (substring ffap-url-regexp 2))))
@@ -218,11 +248,13 @@ For a fancier alternative, get ffap-url.el.")
   ;; It pays to put a big fancy regexp here, since ffap-guesser is
   ;; much more time-consuming than regexp searching:
   "[/:.~a-zA-Z]/\\|@[a-zA-Z][-a-zA-Z0-9]*\\."
-  "*Regular expression governing movements of `ffap-next'.")
+  "*Regular expression governing movements of `ffap-next'."
+  :type 'regexp
+  :group 'ffap)
 
 (defvar ffap-next-guess nil "Last value returned by `ffap-next-guess'.")
 (defun ffap-next-guess (&optional back lim)
-  "Move point to next file or url, and return it as a string.
+  "Move point to next file or URL, and return it as a string.
 If nothing is found, leave point at limit and return nil.
 Optional BACK argument makes search backwards.
 Optional LIM argument limits the search.
@@ -239,7 +271,7 @@ Only considers strings that match `ffap-next-regexp'."
 
 ;;;###autoload
 (defun ffap-next (&optional back wrap)
-  "Search buffer for next file or url, and run ffap.
+  "Search buffer for next file or URL, and run ffap.
 Optional argument BACK says to search backwards.
 Optional argument WRAP says to try wrapping around if necessary.
 Interactively: use a single prefix to search backwards,
@@ -259,7 +291,7 @@ Actual search is done by `ffap-next-guess'."
           (sit-for 0)                   ; display point movement
           (find-file-at-point (ffap-prompter guess)))
       (goto-char pt)                    ; restore point
-      (message "No %sfiles or URL's found."
+      (message "No %sfiles or URL's found"
                (if wrap "" "more ")))))
 
 (defun ffap-next-url (&optional back wrap)
@@ -301,17 +333,29 @@ Actual search is done by `ffap-next-guess'."
 ;; I cannot decide a "best" strategy here, so these are variables.  In
 ;; particular, if `Pinging...' is broken or takes too long on your
 ;; machine, try setting these all to accept or reject.
-(defvar ffap-machine-p-local 'reject    ; this happens often
+(defcustom ffap-machine-p-local 'reject ; this happens often
   "*A symbol, one of: ping, accept, reject.
-What `ffap-machine-p' does with hostnames that have no domain.")
-(defvar ffap-machine-p-known 'ping      ; 'accept for speed
+What `ffap-machine-p' does with hostnames that have no domain."
+  :type '(choice (const ping)
+                 (const accept)
+                 (const reject))
+  :group 'ffap)
+(defcustom ffap-machine-p-known 'ping   ; 'accept for speed
   "*A symbol, one of: ping, accept, reject.
 What `ffap-machine-p' does with hostnames that have a known domain
-\(see mail-extr.el for the known domains\).")
-(defvar ffap-machine-p-unknown 'reject
+\(see mail-extr.el for the known domains\)."
+  :type '(choice (const ping)
+                 (const accept)
+                 (const reject))
+  :group 'ffap)
+(defcustom ffap-machine-p-unknown 'reject
   "*A symbol, one of: ping, accept, reject.
 What `ffap-machine-p' does with hostnames that have an unknown domain
-\(see mail-extr.el for the known domains\).")
+\(see mail-extr.el for the known domains\)."
+  :type '(choice (const ping)
+                 (const accept)
+                 (const reject))
+  :group 'ffap)
 
 (defun ffap-what-domain (domain)
   ;; Like what-domain in mail-extr.el, returns string or nil.