* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
@ 2020-02-29 19:00 Štěpán Němec
2020-02-29 20:02 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Štěpán Němec @ 2020-02-29 19:00 UTC (permalink / raw)
To: 39842; +Cc: monnier
The commit
2015-01-16T22:52:15-05:00!monnier@iro.umontreal.ca
24b7f77581
(Improve handling of doc-strings and describe-function for cl-generic)
added 'help-fns-short-filename', which provides file name shortening
smarter than a simple 'file-name-nondirectory' call, but besides the
generic/eieio functions ('cl--generic-describe', 'cl--describe-class',
'eieio-help-constructor'), it is currently only used by
'describe-function' (via 'help-fns-function-description-header').
Make the other help commands use it, too.
(Other than the obvious consistency/maintenance argument, my immediate
motivation for this change is the possibility to customize the file
name abbreviation by advising the function.)
* lisp/help-fns.el (help-fns-short-filename): Autoload.
(describe-variable) (describe-face) (describe-keymap):
Use 'help-fns-short-filename'.
* lisp/help.el (describe-mode): Declare and use 'help-fns-short-filename'.
---
lisp/help-fns.el | 7 ++++---
lisp/help.el | 3 ++-
2 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 36c2a8b186..e204be72ad 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -661,6 +661,7 @@ help-fns--mention-first-release
(insert (format " Probably introduced at or before Emacs version %s.\n"
first))))))
+;;;###autoload
(defun help-fns-short-filename (filename)
(let* ((abbrev (abbreviate-file-name filename))
(short abbrev))
@@ -968,7 +969,7 @@ describe-variable
" is a variable defined in `%s'.\n"
(if (eq file-name 'C-source)
"C source code"
- (file-name-nondirectory file-name))))
+ (help-fns-short-filename file-name))))
(with-current-buffer standard-output
(save-excursion
(re-search-backward (substitute-command-keys
@@ -1350,7 +1351,7 @@ describe-face
(setq file-name (find-lisp-object-file-name f 'defface))
(when file-name
(princ (substitute-command-keys "Defined in `"))
- (princ (file-name-nondirectory file-name))
+ (princ (help-fns-short-filename file-name))
(princ (substitute-command-keys "'"))
;; Make a hyperlink to the library.
(save-excursion
@@ -1642,7 +1643,7 @@ describe-keymap
" defined in `%s'.\n\n"
(if (eq file-name 'C-source)
"C source code"
- (file-name-nondirectory file-name))))
+ (help-fns-short-filename file-name))))
(save-excursion
(re-search-backward (substitute-command-keys
"`\\([^`']+\\)'")
diff --git a/lisp/help.el b/lisp/help.el
index 45cbaad4e8..32204d04e3 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -879,6 +879,7 @@ describe-key
(princ ", which is ")
(describe-function-1 defn)))))))
\f
+(declare-function help-fns-short-filename "help-fns" (filename))
(defun describe-mode (&optional buffer)
"Display documentation of current major mode and minor modes.
A brief summary of the minor modes comes first, followed by the
@@ -975,7 +976,7 @@ describe-mode
(file-name (find-lisp-object-file-name mode nil)))
(when file-name
(princ (format-message " defined in `%s'"
- (file-name-nondirectory file-name)))
+ (help-fns-short-filename file-name)))
;; Make a hyperlink to the library.
(with-current-buffer standard-output
(save-excursion
--
2.25.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 19:00 bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands Štěpán Němec
@ 2020-02-29 20:02 ` Stefan Monnier
2020-02-29 20:18 ` Štěpán Němec
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2020-02-29 20:02 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 39842
> Make the other help commands use it, too.
Sounds good. See a few comments below.
> +;;;###autoload
> (defun help-fns-short-filename (filename)
OK, we can live that. Maybe, moving it to help.el would be a cleaner option.
> index 45cbaad4e8..32204d04e3 100644
> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -879,6 +879,7 @@ describe-key
> (princ ", which is ")
> (describe-function-1 defn)))))))
> \f
> +(declare-function help-fns-short-filename "help-fns" (filename))
> (defun describe-mode (&optional buffer)
> "Display documentation of current major mode and minor modes.
> A brief summary of the minor modes comes first, followed by the
The autoload cookie above should render this `declare-function`
unnecessary, right?
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 20:02 ` Stefan Monnier
@ 2020-02-29 20:18 ` Štěpán Němec
2020-02-29 20:29 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Štěpán Němec @ 2020-02-29 20:18 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 39842
On Sat, 29 Feb 2020 15:02:05 -0500
Stefan Monnier wrote:
>> +;;;###autoload
>> (defun help-fns-short-filename (filename)
>
> OK, we can live that. Maybe, moving it to help.el would be a cleaner option.
>
>> index 45cbaad4e8..32204d04e3 100644
>> --- a/lisp/help.el
>> +++ b/lisp/help.el
>> @@ -879,6 +879,7 @@ describe-key
>> (princ ", which is ")
>> (describe-function-1 defn)))))))
>> \f
>> +(declare-function help-fns-short-filename "help-fns" (filename))
>> (defun describe-mode (&optional buffer)
>> "Display documentation of current major mode and minor modes.
>> A brief summary of the minor modes comes first, followed by the
>
> The autoload cookie above should render this `declare-function`
> unnecessary, right?
R...right...? I'm somewhat unclear on the "something non-preloaded
required by something preloaded" situation. :-)
So, which shall it be? Move help-fns-short-filename to help.el, or
just remove the declaration?
Thanks,
Štěpán
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 20:18 ` Štěpán Němec
@ 2020-02-29 20:29 ` Stefan Monnier
2020-02-29 20:40 ` Štěpán Němec
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2020-02-29 20:29 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 39842
> So, which shall it be? Move help-fns-short-filename to help.el, or
> just remove the declaration?
I think the declaration can be removed in either case (either with the
function autoloaded or with it moved to help.el).
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 20:29 ` Stefan Monnier
@ 2020-02-29 20:40 ` Štěpán Němec
2020-02-29 21:07 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Štěpán Němec @ 2020-02-29 20:40 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 39842
On Sat, 29 Feb 2020 15:29:01 -0500
Stefan Monnier wrote:
>> So, which shall it be? Move help-fns-short-filename to help.el, or
>> just remove the declaration?
>
> I think the declaration can be removed in either case (either with the
> function autoloaded or with it moved to help.el).
That's what I understood from your previous message. Now I'm asking if I
should just remove the declaration, or also move the function (and
rename it to help-short-filename?).
--
Štěpán
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 20:40 ` Štěpán Němec
@ 2020-02-29 21:07 ` Stefan Monnier
2020-02-29 21:47 ` Štěpán Němec
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2020-02-29 21:07 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 39842
> That's what I understood from your previous message. Now I'm asking if I
> should just remove the declaration, or also move the function (and
> rename it to help-short-filename?).
Not sure which is best either.
Hmm... now that I look at it more closely, I see that `describe-mode`
can't work without loading `help-fns` (e.g. because it calls
`find-lisp-object-file-name`), so there's no point having
`describe-mode` preloaded.
I.e. I think the better answer is that `describe-mode` should move to
`help-fns.el`.
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 21:07 ` Stefan Monnier
@ 2020-02-29 21:47 ` Štěpán Němec
2020-03-03 15:53 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Štěpán Němec @ 2020-02-29 21:47 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 39842
[-- Attachment #1: Type: text/plain, Size: 225 bytes --]
On Sat, 29 Feb 2020 16:07:46 -0500
Stefan Monnier wrote:
> I.e. I think the better answer is that `describe-mode` should move to
> `help-fns.el`.
Patch updated to that effect attached.
Thank you,
Štěpán
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-help-fns-short-filename-in-other-describe-comman.patch --]
[-- Type: text/x-patch, Size: 12055 bytes --]
From f9edbe36d6c56f7bf64ba687d525e48fd8762cde Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= <stepnem@gmail.com>
Date: Sat, 29 Feb 2020 19:43:53 +0100
Subject: [PATCH] Use help-fns-short-filename in other describe- commands
The commit
2015-01-16T22:52:15-05:00!monnier@iro.umontreal.ca
24b7f77581
(Improve handling of doc-strings and describe-function for cl-generic)
added 'help-fns-short-filename', which provides file name shortening
smarter than a simple 'file-name-nondirectory' call, but besides the
generic/eieio functions ('cl--generic-describe', 'cl--describe-class',
'eieio-help-constructor'), it is currently only used by
'describe-function' (via 'help-fns-function-description-header').
Make the other help commands use it, too.
(Other than the obvious consistency/maintenance argument, my immediate
motivation for this change is the possibility to customize the file
name abbreviation by advising the function.)
* lisp/help.el (describe-mode): Move to help-fns.el. The command was
already depending on 'find-lisp-object-file-name' defined there.
* lisp/help-fns.el (describe-variable) (describe-face) (describe-keymap)
(describe-mode): Use 'help-fns-short-filename'.
---
lisp/help-fns.el | 116 +++++++++++++++++++++++++++++++++++++++++++++--
lisp/help.el | 108 -------------------------------------------
2 files changed, 112 insertions(+), 112 deletions(-)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 36c2a8b186..ad496166f5 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -968,7 +968,7 @@ describe-variable
" is a variable defined in `%s'.\n"
(if (eq file-name 'C-source)
"C source code"
- (file-name-nondirectory file-name))))
+ (help-fns-short-filename file-name))))
(with-current-buffer standard-output
(save-excursion
(re-search-backward (substitute-command-keys
@@ -1350,7 +1350,7 @@ describe-face
(setq file-name (find-lisp-object-file-name f 'defface))
(when file-name
(princ (substitute-command-keys "Defined in `"))
- (princ (file-name-nondirectory file-name))
+ (princ (help-fns-short-filename file-name))
(princ (substitute-command-keys "'"))
;; Make a hyperlink to the library.
(save-excursion
@@ -1642,7 +1642,7 @@ describe-keymap
" defined in `%s'.\n\n"
(if (eq file-name 'C-source)
"C source code"
- (file-name-nondirectory file-name))))
+ (help-fns-short-filename file-name))))
(save-excursion
(re-search-backward (substitute-command-keys
"`\\([^`']+\\)'")
@@ -1658,7 +1658,115 @@ describe-keymap
;; Cleanup.
(when used-gentemp
(makunbound keymap))))
-
+\f
+;;;###autoload
+(defun describe-mode (&optional buffer)
+ "Display documentation of current major mode and minor modes.
+A brief summary of the minor modes comes first, followed by the
+major mode description. This is followed by detailed
+descriptions of the minor modes, each on a separate page.
+
+For this to work correctly for a minor mode, the mode's indicator
+variable \(listed in `minor-mode-alist') must also be a function
+whose documentation describes the minor mode.
+
+If called from Lisp with a non-nil BUFFER argument, display
+documentation for the major and minor modes of that buffer."
+ (interactive "@")
+ (unless buffer (setq buffer (current-buffer)))
+ (help-setup-xref (list #'describe-mode buffer)
+ (called-interactively-p 'interactive))
+ ;; For the sake of help-do-xref and help-xref-go-back,
+ ;; don't switch buffers before calling `help-buffer'.
+ (with-help-window (help-buffer)
+ (with-current-buffer buffer
+ (let (minor-modes)
+ ;; Older packages do not register in minor-mode-list but only in
+ ;; minor-mode-alist.
+ (dolist (x minor-mode-alist)
+ (setq x (car x))
+ (unless (memq x minor-mode-list)
+ (push x minor-mode-list)))
+ ;; Find enabled minor mode we will want to mention.
+ (dolist (mode minor-mode-list)
+ ;; Document a minor mode if it is listed in minor-mode-alist,
+ ;; non-nil, and has a function definition.
+ (let ((fmode (or (get mode :minor-mode-function) mode)))
+ (and (boundp mode) (symbol-value mode)
+ (fboundp fmode)
+ (let ((pretty-minor-mode
+ (if (string-match "\\(\\(-minor\\)?-mode\\)?\\'"
+ (symbol-name fmode))
+ (capitalize
+ (substring (symbol-name fmode)
+ 0 (match-beginning 0)))
+ fmode)))
+ (push (list fmode pretty-minor-mode
+ (format-mode-line (assq mode minor-mode-alist)))
+ minor-modes)))))
+ ;; Narrowing is not a minor mode, but its indicator is part of
+ ;; mode-line-modes.
+ (when (buffer-narrowed-p)
+ (push '(narrow-to-region "Narrow" " Narrow") minor-modes))
+ (setq minor-modes
+ (sort minor-modes
+ (lambda (a b) (string-lessp (cadr a) (cadr b)))))
+ (when minor-modes
+ (princ "Enabled minor modes:\n")
+ (make-local-variable 'help-button-cache)
+ (with-current-buffer standard-output
+ (dolist (mode minor-modes)
+ (let ((mode-function (nth 0 mode))
+ (pretty-minor-mode (nth 1 mode))
+ (indicator (nth 2 mode)))
+ (save-excursion
+ (goto-char (point-max))
+ (princ "\n\f\n")
+ (push (point-marker) help-button-cache)
+ ;; Document the minor modes fully.
+ (insert-text-button
+ pretty-minor-mode 'type 'help-function
+ 'help-args (list mode-function)
+ 'button '(t))
+ (princ (format " minor mode (%s):\n"
+ (if (zerop (length indicator))
+ "no indicator"
+ (format "indicator%s"
+ indicator))))
+ (princ (help-split-fundoc (documentation mode-function)
+ nil 'doc)))
+ (insert-button pretty-minor-mode
+ 'action (car help-button-cache)
+ 'follow-link t
+ 'help-echo "mouse-2, RET: show full information")
+ (newline)))
+ (forward-line -1)
+ (fill-paragraph nil)
+ (forward-line 1))
+
+ (princ "\n(Information about these minor modes follows the major mode info.)\n\n"))
+ ;; Document the major mode.
+ (let ((mode mode-name))
+ (with-current-buffer standard-output
+ (let ((start (point)))
+ (insert (format-mode-line mode nil nil buffer))
+ (add-text-properties start (point) '(face bold)))))
+ (princ " mode")
+ (let* ((mode major-mode)
+ (file-name (find-lisp-object-file-name mode nil)))
+ (when file-name
+ (princ (format-message " defined in `%s'"
+ (help-fns-short-filename file-name)))
+ ;; Make a hyperlink to the library.
+ (with-current-buffer standard-output
+ (save-excursion
+ (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
+ nil t)
+ (help-xref-button 1 'help-function-def mode file-name)))))
+ (princ ":\n")
+ (princ (help-split-fundoc (documentation major-mode) nil 'doc)))))
+ ;; For the sake of IELM and maybe others
+ nil)
\f
;;; Replacements for old lib-src/ programs. Don't seem especially useful.
diff --git a/lisp/help.el b/lisp/help.el
index 45cbaad4e8..e40ed479e0 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -879,114 +879,6 @@ describe-key
(princ ", which is ")
(describe-function-1 defn)))))))
\f
-(defun describe-mode (&optional buffer)
- "Display documentation of current major mode and minor modes.
-A brief summary of the minor modes comes first, followed by the
-major mode description. This is followed by detailed
-descriptions of the minor modes, each on a separate page.
-
-For this to work correctly for a minor mode, the mode's indicator
-variable \(listed in `minor-mode-alist') must also be a function
-whose documentation describes the minor mode.
-
-If called from Lisp with a non-nil BUFFER argument, display
-documentation for the major and minor modes of that buffer."
- (interactive "@")
- (unless buffer (setq buffer (current-buffer)))
- (help-setup-xref (list #'describe-mode buffer)
- (called-interactively-p 'interactive))
- ;; For the sake of help-do-xref and help-xref-go-back,
- ;; don't switch buffers before calling `help-buffer'.
- (with-help-window (help-buffer)
- (with-current-buffer buffer
- (let (minor-modes)
- ;; Older packages do not register in minor-mode-list but only in
- ;; minor-mode-alist.
- (dolist (x minor-mode-alist)
- (setq x (car x))
- (unless (memq x minor-mode-list)
- (push x minor-mode-list)))
- ;; Find enabled minor mode we will want to mention.
- (dolist (mode minor-mode-list)
- ;; Document a minor mode if it is listed in minor-mode-alist,
- ;; non-nil, and has a function definition.
- (let ((fmode (or (get mode :minor-mode-function) mode)))
- (and (boundp mode) (symbol-value mode)
- (fboundp fmode)
- (let ((pretty-minor-mode
- (if (string-match "\\(\\(-minor\\)?-mode\\)?\\'"
- (symbol-name fmode))
- (capitalize
- (substring (symbol-name fmode)
- 0 (match-beginning 0)))
- fmode)))
- (push (list fmode pretty-minor-mode
- (format-mode-line (assq mode minor-mode-alist)))
- minor-modes)))))
- ;; Narrowing is not a minor mode, but its indicator is part of
- ;; mode-line-modes.
- (when (buffer-narrowed-p)
- (push '(narrow-to-region "Narrow" " Narrow") minor-modes))
- (setq minor-modes
- (sort minor-modes
- (lambda (a b) (string-lessp (cadr a) (cadr b)))))
- (when minor-modes
- (princ "Enabled minor modes:\n")
- (make-local-variable 'help-button-cache)
- (with-current-buffer standard-output
- (dolist (mode minor-modes)
- (let ((mode-function (nth 0 mode))
- (pretty-minor-mode (nth 1 mode))
- (indicator (nth 2 mode)))
- (save-excursion
- (goto-char (point-max))
- (princ "\n\f\n")
- (push (point-marker) help-button-cache)
- ;; Document the minor modes fully.
- (insert-text-button
- pretty-minor-mode 'type 'help-function
- 'help-args (list mode-function)
- 'button '(t))
- (princ (format " minor mode (%s):\n"
- (if (zerop (length indicator))
- "no indicator"
- (format "indicator%s"
- indicator))))
- (princ (help-split-fundoc (documentation mode-function)
- nil 'doc)))
- (insert-button pretty-minor-mode
- 'action (car help-button-cache)
- 'follow-link t
- 'help-echo "mouse-2, RET: show full information")
- (newline)))
- (forward-line -1)
- (fill-paragraph nil)
- (forward-line 1))
-
- (princ "\n(Information about these minor modes follows the major mode info.)\n\n"))
- ;; Document the major mode.
- (let ((mode mode-name))
- (with-current-buffer standard-output
- (let ((start (point)))
- (insert (format-mode-line mode nil nil buffer))
- (add-text-properties start (point) '(face bold)))))
- (princ " mode")
- (let* ((mode major-mode)
- (file-name (find-lisp-object-file-name mode nil)))
- (when file-name
- (princ (format-message " defined in `%s'"
- (file-name-nondirectory file-name)))
- ;; Make a hyperlink to the library.
- (with-current-buffer standard-output
- (save-excursion
- (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
- nil t)
- (help-xref-button 1 'help-function-def mode file-name)))))
- (princ ":\n")
- (princ (help-split-fundoc (documentation major-mode) nil 'doc)))))
- ;; For the sake of IELM and maybe others
- nil)
-
(defun search-forward-help-for-help ()
"Search forward \"help window\"."
(interactive)
--
2.25.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands
2020-02-29 21:47 ` Štěpán Němec
@ 2020-03-03 15:53 ` Stefan Monnier
0 siblings, 0 replies; 8+ messages in thread
From: Stefan Monnier @ 2020-03-03 15:53 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 39842-done
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/x-markdown; coding=UTF-8, Size: 97 bytes --]
> Patch updated to that effect attached.
Thanks, installed into `master`.
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-03-03 15:53 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-02-29 19:00 bug#39842: [PATCH] Use help-fns-short-filename in other describe- commands Štěpán Němec
2020-02-29 20:02 ` Stefan Monnier
2020-02-29 20:18 ` Štěpán Němec
2020-02-29 20:29 ` Stefan Monnier
2020-02-29 20:40 ` Štěpán Němec
2020-02-29 21:07 ` Stefan Monnier
2020-02-29 21:47 ` Štěpán Němec
2020-03-03 15:53 ` Stefan Monnier
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).