comparison lisp/woman.el @ 65428:25502a355957

(woman-topic-at-point-default): Renamed to woman-use-topic-at-point-default. (woman-topic-at-point): Renamed to woman-use-topic-at-point. (woman-file-name): Reflect renames above. Automatically use the word at point as topic if woman-use-topic-at-point is non-nil. Otherwise offer it as default but don't insert it in the minibuffer. Also use `test-completion' instead of `assoc' as suggested by Stefan Monnier.

65427:153350fbd860

;; Start menu) just execute

;;   man man_page_name


;; Using the `word at point' as a topic suggestion
;; ===============================================

;; By default, the `woman' command uses the word nearest to point in
;; the current buffer as a suggestion for the topic to look up.  The
;; topic must be confirmed or edited in the minibuffer.  This
;; suggestion can be turned off, or `woman' can use the suggested
;; topic without confirmation* if possible, by setting the user-option
;; `woman-topic-at-point' to nil or t respectively.  (Its default
;; value is neither nil nor t, meaning ask for confirmation.)

;; [* Thanks to Benjamin Riefenstahl for suggesting this
;; functionality.]

;; The variable `woman-topic-at-point' can be rebound locally, which
;; may be useful to provide special private key bindings, e.g.

;;  (global-set-key "\C-cw"
;;  		  (lambda ()
;;  		    (interactive)
;;  		    (let ((woman-topic-at-point t))
;;  		      (woman)))))


;; Customization, Hooks and Imenu
;; ==============================

  "*The title to use if WoMan adds a Contents menu to the menubar.
Default is \"CONTENTS\"."
  :type 'string
  :group 'woman-interface)

(defcustom woman-topic-at-point-default 'confirm
  ;; `woman-topic-at-point' may be let-bound when woman is loaded, in
  ;; which case its global value does not get defined.
  ;; `woman-file-name' sets it to this value if it is unbound.
  "*Default value for `woman-topic-at-point'."
  :type '(choice (const :tag "Yes" t)
		 (const :tag "No" nil)
		 (other :tag "Confirm" confirm))
  :group 'woman-interface)

(defcustom woman-topic-at-point woman-topic-at-point-default
  "*Controls use by `woman' of `word at point' as a topic suggestion.
If non-nil then the `woman' command uses the word at point as an
initial topic suggestion when it reads a topic from the minibuffer; if
t then the `woman' command uses the word at point WITHOUT
INTERACTIVE CONFIRMATION if it exists as a topic.  The default value
is `confirm', meaning suggest a topic and ask for confirmation."
  :type '(choice (const :tag "Yes" t)
		 (const :tag "No" nil)
		 (other :tag "Confirm" confirm))
  :group 'woman-interface)

(defvar woman-file-regexp nil
  "Regexp used to select (possibly compressed) man source files, e.g.
\"\\.\\([0-9lmnt]\\w*\\)\\(\\.\\(g?z\\|bz2\\)\\)?\\'\".

(defvar woman-topic-history nil "Topic read history.")
(defvar woman-file-history nil "File-name read history.")

(defun woman-file-name (topic &optional re-cache)
  "Get the name of the UN*X man-page file describing a chosen TOPIC.
When `woman' is called interactively, the word at point may be used as
the topic or initial topic suggestion, subject to the value of the
user option `woman-topic-at-point'.  Return nil if no file can be found.
Optional argument RE-CACHE, if non-nil, forces the cache to be re-read."
  ;; Handle the caching of the directory and topic lists:
  (if (and (not re-cache)
	   (or
	    (and woman-expanded-directory-path woman-topic-all-completions)
	    (woman-read-directory-cache)))

  ;; does not seem to work properly by default, so I re-do the
  ;; completion if necessary.
  (let (files
	(default (current-word)))
    (or (stringp topic)
	(and (eq t
		 (if (boundp 'woman-topic-at-point)
		     woman-topic-at-point
		   ;; Was let-bound when file loaded, so ...
		   (setq woman-topic-at-point woman-topic-at-point-default)))
	     (setq topic
		   (or (current-word t) ""))	; only within or adjacent to word
	     (assoc topic woman-topic-all-completions))
	(setq topic
	      (completing-read
	       (if default
		   (format "Manual entry (default `%s'): " default)
		 "Manual entry: ")
	       woman-topic-all-completions nil 1
	       nil
	       'woman-topic-history
	       ;; Default topic.
	       (and woman-topic-at-point
		    default))))
    ;; Note that completing-read always returns a string.
    (if (= (length topic) 0)
	nil				; no topic, so no file!
      (cond
       ((setq files (woman-file-name-all-completions topic)))

65428:25502a355957

;; Start menu) just execute

;;   man man_page_name


;; Using the word at point as the default topic
;; ============================================

;; The `woman' command uses the word nearest to point in the current
;; buffer as the default topic to look up if it matches the name of a
;; manual page installed on the system.  The default topic can also be
;; used without confirmation by setting the user-option
;; `woman-use-topic-at-point' to t; thanks to Benjamin Riefenstahl for
;; suggesting this functionality.

;; The variable `woman-use-topic-at-point' can be rebound locally,
;; which may be useful to provide special private key bindings, e.g.

;;  (global-set-key "\C-cw"
;;  		  (lambda ()
;;  		    (interactive)
;;  		    (let ((woman-use-topic-at-point t))
;;  		      (woman)))))


;; Customization, Hooks and Imenu
;; ==============================

  "*The title to use if WoMan adds a Contents menu to the menubar.
Default is \"CONTENTS\"."
  :type 'string
  :group 'woman-interface)

(defcustom woman-use-topic-at-point-default nil
  ;; `woman-use-topic-at-point' may be let-bound when woman is loaded,
  ;; in which case its global value does not get defined.
  ;; `woman-file-name' sets it to this value if it is unbound.
  "*Default value for `woman-use-topic-at-point'."
  :type '(choice (const :tag "Yes" t)
		 (const :tag "No" nil))
  :group 'woman-interface)

(defcustom woman-use-topic-at-point woman-use-topic-at-point-default
  "*Control use of the word at point as the default topic.
If non-nil the `woman' command uses the word at point automatically,
without interactive confirmation, if it exists as a topic."
  :type '(choice (const :tag "Yes" t)
		 (const :tag "No" nil))
  :group 'woman-interface)

(defvar woman-file-regexp nil
  "Regexp used to select (possibly compressed) man source files, e.g.
\"\\.\\([0-9lmnt]\\w*\\)\\(\\.\\(g?z\\|bz2\\)\\)?\\'\".

(defvar woman-topic-history nil "Topic read history.")
(defvar woman-file-history nil "File-name read history.")

(defun woman-file-name (topic &optional re-cache)
  "Get the name of the UN*X man-page file describing a chosen TOPIC.
When `woman' is called interactively, the word at point may be
automatically used as the topic, if the value of the user option
`woman-use-topic-at-point' is non-nil.  Return nil if no file can
be found.  Optional argument RE-CACHE, if non-nil, forces the
cache to be re-read."
  ;; Handle the caching of the directory and topic lists:
  (if (and (not re-cache)
	   (or
	    (and woman-expanded-directory-path woman-topic-all-completions)
	    (woman-read-directory-cache)))

  ;; does not seem to work properly by default, so I re-do the
  ;; completion if necessary.
  (let (files
	(default (current-word)))
    (or (stringp topic)
	(and (if (boundp 'woman-use-topic-at-point)
		 woman-use-topic-at-point
	       ;; Was let-bound when file loaded, so ...
	       (setq woman-use-topic-at-point woman-use-topic-at-point-default))
	     (setq topic (or (current-word t) "")) ; only within or adjacent to word
	     (test-completion topic woman-topic-all-completions))
	(setq topic
	      (let* ((word-at-point (current-word))
		     (default
		       (when (and word-at-point
				  (test-completion
				   word-at-point woman-topic-all-completions))
			 word-at-point)))
		(completing-read
		 (if default
		     (format "Manual entry [default: %s]: " default)
		   "Manual entry: ")
		 woman-topic-all-completions nil 1
		 nil
		 'woman-topic-history
		 default))))
    ;; Note that completing-read always returns a string.
    (if (= (length topic) 0)
	nil				; no topic, so no file!
      (cond
       ((setq files (woman-file-name-all-completions topic)))