Re: patch for woman (woman-topic-at-point)

[Emilio Lopes]

Richard M Stallman writes:

>     The problem is that "to suggest" for `woman' means to actually
>     *insert* the suggested name in the minibuffer, a behavior
>     described as deprecated in the documentation of
>     `completing-read'.

> That is an unnecessarily complex solution.  It would be better just
> to change *how* that name is offered.  Instead of inserting it in
> the minibuffer, make it the default, more or less as below.

I wanted to do it this way too initially.  It didn't work because:

   1- The code following `completing-read' expects the result from
      that function to be an existing man page.  I think this is a
      legitimate assumption.

   2- The argument REQUIRE-MATCH in `completing-read', currently used
      to satisfy item 1 above, has no effect on the argument DEF,
      the default value offered.  It affects only the argument
      INITIAL-INPUT.

Item 2 means that if the user just press <enter> at the prompt
`completing-read' will happily return DEF whether or not it matches
an item in TABLE.  This would break the assumption in item 1.

It follows from the above that if you want to offer some suggestion using
the argument DEF of `completing-read' the suggestion must be "valid".
Otherwise you'll break the code following the `completing-read'.  This is
accomplished by the patches I sent.

Yes, the patches make the code somewhat more complex, but that's
because I wanted it to be backwards compatible.  *I* would just remove
the old behavior, since it makes no sense for me to suggest man pages
which do not exist.

The following patch implements this simpler and more sensible behavior.
It is *not* backwards compatible.  To make that clear, I renamed the
variable `woman-topic-at-point' to `woman-use-topic-at-point'.


2005-08-26  Emilio C. Lopes  <address@hidden>

        * woman.el (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.
  
diff -rN -c old-emacs-darcs.eclig/lisp/woman.el 
new-emacs-darcs.eclig/lisp/woman.el
*** old-emacs-darcs.eclig/lisp/woman.el Fri Aug 26 17:11:11 2005
--- new-emacs-darcs.eclig/lisp/woman.el Fri Aug 26 16:54:51 2005
***************
*** 136,162 ****
  ;;   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)))))
  
  
--- 136,158 ----
  ;;   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)))))
  
  
***************
*** 711,736 ****
    :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
--- 707,727 ----
    :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
***************
*** 1198,1207 ****
  
  (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
--- 1189,1199 ----
  
  (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
***************
*** 1221,1243 ****
    ;; completion if necessary.
    (let (files)
      (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
!              "Manual entry: "
!              woman-topic-all-completions nil 1
!              ;; Initial input suggestion (was nil), with
!              ;; cursor at left ready to kill suggestion!:
!              (and woman-topic-at-point
!                   (cons (or (current-word) "") 0)) ; nearest word
!              'woman-topic-history)))
      ;; Note that completing-read always returns a string.
      (if (= (length topic) 0)
        nil                             ; no topic, so no file!
--- 1213,1236 ----
    ;; completion if necessary.
    (let (files)
      (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
             (assoc topic woman-topic-all-completions))
        (setq topic
!               (let ((default (and (current-word)
!                                   (car (assoc (current-word)
!                                               woman-topic-all-completions)))))
!                 (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!