From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Devel" <emacs-devel@gnu.org>
Subject: patch to fill overlong lines in `describe-key'
Date: Thu, 3 Jan 2008 11:59:45 -0800 [thread overview]
Message-ID: <DHEEKFAFJEFOJHLCFPFDKEFICDAA.drew.adams@oracle.com> (raw)
[-- Attachment #1: Type: text/plain, Size: 1487 bytes --]
The first few lines output by `describe-key' can be overly long. Example:
<menu-bar> <operate> <icicles> <icicle-candidate-set-dired-marked-save-more>
runs the command icicle-candidate-set-dired-marked-save-more
which is an interactive compiled Lisp function in `icicles-cmd.el'.
It is bound to C-), <menu-bar> <operate> <icicles>
<icicle-candidate-set-dired-marked-save-more>.
(icicle-candidate-set-dired-marked-save-more &optional ARG)
The code currently attempts to deal with this by hard-coding a newline
before "which is", but that doesn't cut the mustard.
The same problem can occur in some subsequent lines, because of embedded
calls to `describe-function-1'.
The attached patches fill the text of such occurrences as separate
paragraphs. Example:
<menu-bar> <operate> <icicles>
<icicle-candidate-set-dired-marked-save-more> runs the command
icicle-candidate-set-dired-marked-save-more, which is an interactive
compiled Lisp function in `icicles-cmd.el'.
It is bound to C-), <menu-bar> <operate> <icicles>
<icicle-candidate-set-dired-marked-save-more>.
(icicle-candidate-set-dired-marked-save-more &optional ARG)
I also added a comma (,) before "which" in several places where it
introduces an independent clause (see above for an example).
I tested a similar patch against the 22.1 release code. Please try this out
with the latest CVS code. There are several different cases to try,
including mouse-2 remapping. Let me know if you find a case where it doesn't
DTRT.
[-- Attachment #2: help-2008-01-02.patch --]
[-- Type: application/octet-stream, Size: 5842 bytes --]
diff -c help-CVS-2008-01-02.el help-patched-2008-01-02.el
*** help-CVS-2008-01-02.el Wed Jan 2 15:19:54 2008
--- help-patched-2008-01-02.el Thu Jan 3 10:55:58 2008
***************
*** 657,691 ****
(cursor-in-echo-area t)
saved-yank-menu)
(unwind-protect
! (let (key)
! ;; If yank-menu is empty, populate it temporarily, so that
! ;; "Select and Paste" menu can generate a complete event.
! (when (null (cdr yank-menu))
! (setq saved-yank-menu (copy-sequence yank-menu))
! (menu-bar-update-yank-menu "(any string)" nil))
! (setq key (read-key-sequence "Describe key (or click or menu item): "))
! (list
! key
! (prefix-numeric-value current-prefix-arg)
! ;; If KEY is a down-event, read and include the
! ;; corresponding up-event. Note that there are also
! ;; down-events on scroll bars and mode lines: the actual
! ;; event then is in the second element of the vector.
! (and (vectorp key)
! (let ((last-idx (1- (length key))))
! (and (eventp (aref key last-idx))
! (memq 'down (event-modifiers (aref key last-idx)))))
! (or (and (eventp (aref key 0))
! (memq 'down (event-modifiers (aref key 0)))
! ;; However, for the C-down-mouse-2 popup
! ;; menu, there is no subsequent up-event. In
! ;; this case, the up-event is the next
! ;; element in the supplied vector.
! (= (length key) 1))
! (and (> (length key) 1)
! (eventp (aref key 1))
! (memq 'down (event-modifiers (aref key 1)))))
! (read-event))))
;; Put yank-menu back as it was, if we changed it.
(when saved-yank-menu
(setq yank-menu (copy-sequence saved-yank-menu))
--- 657,691 ----
(cursor-in-echo-area t)
saved-yank-menu)
(unwind-protect
! (let (key)
! ;; If yank-menu is empty, populate it temporarily, so that
! ;; "Select and Paste" menu can generate a complete event.
! (when (null (cdr yank-menu))
! (setq saved-yank-menu (copy-sequence yank-menu))
! (menu-bar-update-yank-menu "(any string)" nil))
! (setq key (read-key-sequence "Describe key (or click or menu item): "))
! (list
! key
! (prefix-numeric-value current-prefix-arg)
! ;; If KEY is a down-event, read and include the
! ;; corresponding up-event. Note that there are also
! ;; down-events on scroll bars and mode lines: the actual
! ;; event then is in the second element of the vector.
! (and (vectorp key)
! (let ((last-idx (1- (length key))))
! (and (eventp (aref key last-idx))
! (memq 'down (event-modifiers (aref key last-idx)))))
! (or (and (eventp (aref key 0))
! (memq 'down (event-modifiers (aref key 0)))
! ;; However, for the C-down-mouse-2 popup
! ;; menu, there is no subsequent up-event. In
! ;; this case, the up-event is the next
! ;; element in the supplied vector.
! (= (length key) 1))
! (and (> (length key) 1)
! (eventp (aref key 1))
! (memq 'down (event-modifiers (aref key 1)))))
! (read-event))))
;; Put yank-menu back as it was, if we changed it.
(when saved-yank-menu
(setq yank-menu (copy-sequence saved-yank-menu))
***************
*** 745,752 ****
(with-help-window (help-buffer)
(princ (help-key-description key untranslated))
(princ (format "\
! %s runs the command %S
! which is "
mouse-msg defn))
(describe-function-1 defn)
(when up-event
--- 745,751 ----
(with-help-window (help-buffer)
(princ (help-key-description key untranslated))
(princ (format "\
! %s runs the command %S, which is "
mouse-msg defn))
(describe-function-1 defn)
(when up-event
***************
*** 757,780 ****
----------------- up-event %s----------------
! <%S>%s%s runs the command %S
! which is "
! (if mouse-1-tricky "(short click) " "")
! ev-type mouse-msg
! (if mouse-1-remapped
! " is remapped to <mouse-2>\nwhich" "")
! defn-up))
! (describe-function-1 defn-up))
! (unless (or (null defn-up-tricky)
! (integerp defn-up-tricky)
! (eq defn-up-tricky 'undefined))
! (princ (format "
----------------- up-event (long click) ----------------
Pressing <%S>%s for longer than %d milli-seconds
! runs the command %S
! which is "
ev-type mouse-msg
mouse-1-click-follows-link
defn-up-tricky))
--- 756,777 ----
----------------- up-event %s----------------
! <%S>%s%s runs the command %S, which is "
! (if mouse-1-tricky "(short click) " "")
! ev-type mouse-msg
! (if mouse-1-remapped
! " is remapped to <mouse-2>, which" "")
! defn-up))
! (describe-function-1 defn-up))
! (unless (or (null defn-up-tricky)
! (integerp defn-up-tricky)
! (eq defn-up-tricky 'undefined))
! (princ (format "
----------------- up-event (long click) ----------------
Pressing <%S>%s for longer than %d milli-seconds
! runs the command %S, which is "
ev-type mouse-msg
mouse-1-click-follows-link
defn-up-tricky))
[-- Attachment #3: help-fns-2007-10-19.patch --]
[-- Type: application/octet-stream, Size: 6743 bytes --]
*** help-fns-CVS-2007-10-19.el Fri Oct 19 10:38:10 2007
--- help-fns-patched-2007-10-19.el Fri Oct 19 11:39:10 2007
***************
*** 38,45 ****
;; Functions
;;;###autoload
! (defun describe-function (function)
! "Display the full documentation of FUNCTION (a symbol)."
(interactive
(let ((fn (function-called-at-point))
(enable-recursive-minibuffers t)
--- 38,48 ----
;; Functions
;;;###autoload
! (defun describe-function (function &optional commandp)
! "Display the full documentation of FUNCTION (a symbol).
! FUNCTION names an Emacs Lisp function, possibly a user command.
! With a prefix arg, candidates are commands (interactive functions).
! Returns the description that was displayed, as a string."
(interactive
(let ((fn (function-called-at-point))
(enable-recursive-minibuffers t)
***************
*** 47,58 ****
(setq val (completing-read (if fn
(format "Describe function (default %s): " fn)
"Describe function: ")
! obarray 'fboundp t nil nil
! (and fn (symbol-name fn))))
! (list (if (equal val "")
! fn (intern val)))))
(if (null function)
(message "You didn't specify a function")
(help-setup-xref (list #'describe-function function) (interactive-p))
(save-excursion
(with-output-to-temp-buffer (help-buffer)
--- 50,63 ----
(setq val (completing-read (if fn
(format "Describe function (default %s): " fn)
"Describe function: ")
! obarray (if current-prefix-arg 'commandp 'fboundp)
! t nil nil (and fn (symbol-name fn))))
! (list (if (equal val "") fn (intern val))
! current-prefix-arg)))
(if (null function)
(message "You didn't specify a function")
+ (unless (or (not commandp) (commandp function))
+ (error "Not a defined Emacs command (interactive function): `%s'" function))
(help-setup-xref (list #'describe-function function) (interactive-p))
(save-excursion
(with-output-to-temp-buffer (help-buffer)
***************
*** 66,71 ****
--- 71,92 ----
;; Return the text we displayed.
(buffer-string))))))
+ ;;;###autoload
+ (defun describe-command (function)
+ "Describe an Emacs command (interactive function).
+ Same as using a prefix argument with command `describe-function'."
+ (interactive
+ (let ((fn (function-called-at-point))
+ (enable-recursive-minibuffers t)
+ val)
+ (setq val (completing-read (if fn
+ (format "Describe command (default %s): " fn)
+ "Describe command: ")
+ obarray 'commandp t nil nil
+ (and fn (symbol-name fn))))
+ (list (if (equal val "") fn (intern val)))))
+ (describe-function function t))
+
(defun help-split-fundoc (docstring def)
"Split a function DOCSTRING into the actual doc and the usage info.
Return (USAGE . DOC) or nil if there's no usage info.
***************
*** 457,467 ****
0))
;;;###autoload
! (defun describe-variable (variable &optional buffer frame)
"Display the full documentation of VARIABLE (a symbol).
! Returns the documentation as a string, also.
If VARIABLE has a buffer-local value in BUFFER or FRAME
! \(default to the current buffer and current frame),
it is displayed along with the global value."
(interactive
(let ((v (variable-at-point))
--- 478,490 ----
0))
;;;###autoload
! (defun describe-variable (variable &optional buffer frame optionp)
"Display the full documentation of VARIABLE (a symbol).
! VARIABLE names an Emacs Lisp variable, possibly a user option.
! With a prefix argument, candidates are user variables (options) only.
! Returns the documentation as a string.
If VARIABLE has a buffer-local value in BUFFER or FRAME
! \(default to the current buffer and current frame), then
it is displayed along with the global value."
(interactive
(let ((v (variable-at-point))
***************
*** 472,488 ****
"Describe variable (default %s): " v)
"Describe variable: ")
obarray
! '(lambda (vv)
! (or (boundp vv)
! (get vv 'variable-documentation)))
t nil nil
(if (symbolp v) (symbol-name v))))
! (list (if (equal val "")
! v (intern val)))))
(unless (buffer-live-p buffer) (setq buffer (current-buffer)))
(unless (frame-live-p frame) (setq frame (selected-frame)))
(if (not (symbolp variable))
(message "You did not specify a variable")
(save-excursion
(let ((valvoid (not (with-current-buffer buffer (boundp variable))))
val val-start-pos locus)
--- 495,516 ----
"Describe variable (default %s): " v)
"Describe variable: ")
obarray
! (if current-prefix-arg
! (lambda (vv) (user-variable-p vv))
! (lambda (vv)
! (or (boundp vv) (get vv 'variable-documentation))))
t nil nil
(if (symbolp v) (symbol-name v))))
! (list (if (equal val "") v (intern val))
! nil
! nil
! current-prefix-arg)))
(unless (buffer-live-p buffer) (setq buffer (current-buffer)))
(unless (frame-live-p frame) (setq frame (selected-frame)))
(if (not (symbolp variable))
(message "You did not specify a variable")
+ (unless (or (not optionp) (user-variable-p variable))
+ (error "Not a defined Emacs user option: `%s'" variable))
(save-excursion
(let ((valvoid (not (with-current-buffer buffer (boundp variable))))
val val-start-pos locus)
***************
*** 662,667 ****
--- 690,713 ----
;; Return the text we displayed.
(buffer-string))))))))
+ ;;;###autoload
+ (defun describe-option (variable &optional buffer frame)
+ "Describe an Emacs user variable (option).
+ Same as using a prefix argument with command `describe-variable'."
+ (interactive
+ (let ((v (variable-at-point))
+ (enable-recursive-minibuffers t)
+ val)
+ (setq val (completing-read (if (symbolp v)
+ (format "Describe option (default %s): " v)
+ "Describe option: ")
+ obarray 'user-variable-p t nil nil
+ (if (symbolp v) (symbol-name v))))
+ (list (if (equal val "") v (intern val))
+ nil
+ nil
+ current-prefix-arg)))
+ (describe-variable variable buffer frame t))
;;;###autoload
(defun describe-syntax (&optional buffer)
Diff finished. Fri Oct 19 12:02:43 2007
[-- Attachment #4: Type: text/plain, Size: 142 bytes --]
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
next reply other threads:[~2008-01-03 19:59 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-01-03 19:59 Drew Adams [this message]
-- strict thread matches above, loose matches on Subject: below --
2008-02-12 6:18 patch to fill overlong lines in `describe-key' Drew Adams
2008-02-12 7:11 ` Bastien
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=DHEEKFAFJEFOJHLCFPFDKEFICDAA.drew.adams@oracle.com \
--to=drew.adams@oracle.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).