Can't add bookmarks for help pages

Can't add bookmarks for help pages

[Kelly Dean]

Emacs lets me add bookmarks for man and info pages, but not for help pages (it says "Buffer not visiting a file or directory"). Not letting me bookmark help pages isn't user-friendly.

RE: Can't add bookmarks for help pages

[Drew Adams]

> Emacs lets me add bookmarks for man and info pages, but not 
> for help pages (it says "Buffer not visiting a file or 
> directory"). Not letting me bookmark help pages isn't user-friendly.

What do you mean by a help page?  Do you mean the output, in buffer *Help*, from
a help command/key such as `C-h f' or `C-h v'?

If so, then no, normally you cannot bookmark that - but see below.

With Bookmark+ [*] you can bookmark a buffer that is not associated with a file,
but except for certain predefined buffer types, such as Info and Dired, to jump
to the bookmark later that buffer must already be present (live).  And it must
already have the text that you expect.

So that won't help you here, not right out of the box.

But it's easy enough to do.  You just need to define your own new bookmark type
for it.  To do that you need to define two functions:

1. A function that creates the bookmark record for that type.
2. A handler function the DTRT when you "jump" to the bookmark.

Here's how:

(defun my-make-help-record ()
  "Create and return a `*Help*' bookmark record."
  (unless (car help-xref-stack-item)
    (error "Cannot create bookmark - help command not known"))
  `(,@(bookmark-make-record-default 'NO-FILE 'NO-CONTEXT)
      (filename    . ,bmkp-non-file-filename)
      (buffer-name . "*Help*")
      (help-fn     . ,(car help-xref-stack-item))
      (help-arg    . ,(cadr help-xref-stack-item))
      (handler     . my-jump-help-bookmark)))

(defun my-jump-help-bookmark (bookmark)
  "Jump to `*Help*' bookmark BOOKMARK.
Handler function for record returned by `my-make-help-record'.
BOOKMARK is a bookmark name or a bookmark record."
  (let ((help-fn   (bookmark-prop-get bookmark 'help-fn))
        (help-arg  (bookmark-prop-get bookmark 'help-arg)))
    (funcall help-fn help-arg)))

(add-hook 'help-mode-hook
          #'(lambda () (set (make-local-variable
                             'bookmark-make-record-function)
                       'my-make-help-record)))

Then, whenever you are in buffer `*Help*', the normal bookmark-setting key, `C-x
r m', creates a bookmark that will show that same help text in `*Help*' when you
jump to it.  It just calls the same help command with the same argument.

E.g., if you used `C-h f forward-char' and you then set a bookmark in `*Help*',
then jumping to it later would show again the help for function `forward-char',
with the cursor at the same spot.

But why would you want such a bookmark type (assuming this was what you had in
mind)?  Why not just use the help commands?  Why would you want a bookmark for a
specific bit of help text (e.g. for a specific variable), rather than just use a
general command that works for any argument (e.g. any variable name)?

Probably I'm missing what you really want to do.

[*] http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus

RE: Can't add bookmarks for help pages

[Drew Adams]

> (defun my-jump-help-bookmark (bookmark)
>   "Jump to `*Help*' bookmark BOOKMARK.
> Handler function for record returned by `my-make-help-record'.
> BOOKMARK is a bookmark name or a bookmark record."
>   (let ((help-fn   (bookmark-prop-get bookmark 'help-fn))
>         (help-arg  (bookmark-prop-get bookmark 'help-arg)))
>     (funcall help-fn help-arg)))

Sorry, did I say the cursor would be at the recorded position?
Then make that:

(defun my-jump-help-bookmark (bookmark)
  "..."
  (let ((help-fn   (bookmark-prop-get bookmark 'help-fn))
        (help-arg  (bookmark-prop-get bookmark 'help-arg))
        (position  (bookmark-prop-get bookmark 'position)))
    (funcall help-fn help-arg)
    (with-current-buffer "*Help*" (goto-char position))))
    
Or if you want buffer `*Help*' to be current, then replace the last sexp,
(with-current...), with these two sexps:

(pop-to-buffer "*Help*")
(goto-char position)

RE: Can't add bookmarks for help pages

[Kelly Dean]

--- On Sat, 6/9/12, Drew Adams <drew.adams@oracle.com> wrote:
> What do you mean by a help page?  Do you mean the
> output, in buffer *Help*, from
> a help command/key such as `C-h f' or `C-h v'?
Yes.

> But it's easy enough to do.  You just need to define
> your own new bookmark type
> for it.  To do that you need to define two functions:
[snip]
Thanks, but the first time I tried it (this is also the first time I tried Bookmark Plus), I got the message "bmkp-bookmark-name-member: Args out of range: 0, 0", and all of my bookmarks disappeared in the *Bookmark List* buffer. I killed and restarted Emacs, and when I pressed C-x r l, I got the same message again, and it doesn't list any bookmarks. I didn't lose any data which matters; I'm still just evaluating Emacs, not using it yet.

While trying to reproduce the problem, I deleted the Bookmark Plus elc files which I'd generated, and deleted my-make-help-record and my-jump-help-bookmark from my init file, so the problem must be just with Bookmark Plus, or Emacs, or how I'm using them.
Using Emacs 24.1:
rm ~/.emacs.d/bookmarks
emacs -Q
C-x C-f foo ret
C-x r m ret
C-x C-c
emacs #Using init file with just (setq load-path (cons "~/.emacs.d/lib" load-path)) (require 'bookmark+)
C-x r l
I get "bmkp-bookmark-name-member: Args out of range: 0, 0". I have the eight files from https://github.com/emacsmirror/bookmark-plus (dated May 16, 2012), and no elc files.

Another try:
rm ~/.emacs.d/bookmarks
emacs #Using the same init file
C-x C-f foo ret
C-x r m ret
I get "bmkp-autonamed-bookmark-p: Wrong type argument: stringp, nil"
C-x r m foo ret
C-x r l
I get "let: Args out of range: 0, 0"
C-x C-c
Emacs writes (custom-set-variables '(bmkp-last-as-first-bookmark-file "~/.emacs.d/bookmarks")) to my init file without asking me first.

> But why would you want such a bookmark type (assuming this
> was what you had in
> mind)?  Why not just use the help commands?  Why
> would you want a bookmark for a
> specific bit of help text (e.g. for a specific variable),
> rather than just use a
> general command that works for any argument (e.g. any
> variable name)?
I want to bookmark help pages in Emacs for the same reason that I bookmark web pages in my browser and bookmark man and info pages in Emacs: to put them on my reading list.
Another reason is that I'm trying to be able to save all of my state (see my other post on this list, "Saving all state, not just some of it"), and had the idea that even though Emacs doesn't save my open help pages, I can at least bookmark them to remind me what to re-open after I restart Emacs.

BTW, I happened to skim through bookmark+-mac.el and noticed this:
;;      In particular, ALWAYS LOAD `bookmark+-mac.el' (not
;;      `bookmark+-mac.elc') BEFORE YOU BYTE-COMPILE new versions of
;;      the files, in case there have been any changes to Lisp macros
;;      (in `bookmark+-mac.el').
;;
;;      (This is standard procedure for Lisp: code that depends on
;;      macros needs to be byte-compiled anew after loading the
;;      updated macros.)
If I byte-compile Bookmark Plus, then in a few months when I update, I'm going to forget your warning, and I'm going to suffer whatever consequences result. Maybe the new packaging system in Emacs 24 helps with such dependency issues?

RE: Can't add bookmarks for help pages

[Drew Adams]

> Thanks, but the first time I tried it (this is also the first 
> time I tried Bookmark Plus), I got the message 
> "bmkp-bookmark-name-member: Args out of range: 0, 0", and all 
> of my bookmarks disappeared in the *Bookmark List* buffer.
>
> I killed and restarted Emacs, and when I pressed C-x r l, I got 
> the same message again, and it doesn't list any bookmarks. I 
> didn't lose any data which matters; I'm still just evaluating 
> Emacs, not using it yet.

1. Thanks for the report, Kelly.  Sorry for your trouble.

2. It is a good idea to back up your bookmark file(s) from time to time, and in
particular before you try any new bookmark-related code. ;-)

3. That problem should be fixed now.  Please download file bookmark+-1.el again.

> While trying to reproduce the problem, I deleted the Bookmark Plus
> elc files which I'd generated

Good.  It's a good idea to test first with source files, before trying
byte-compiled versions.

> and deleted my-make-help-record and my-jump-help-bookmark from my init 
> file, so the problem must be just with Bookmark Plus, or 
> Emacs, or how I'm using them.
> Using Emacs 24.1:

FWIW, `M-x emacs-version' gives more precise info about the version.
There are lots of "Emacs 24.1" out there, and they can be quite different.

> Another try:
> rm ~/.emacs.d/bookmarks
> emacs #Using the same init file
> C-x C-f foo ret
> C-x r m ret
> I get "bmkp-autonamed-bookmark-p: Wrong type argument: stringp, nil"

You entered an empty bookmark name, and apparently no default name was
available.  So you ended up with a bookmark with an empty name.  This should be
prevented now - try the latest bookmark+-1.el.

> C-x r m foo ret
> C-x r l
> I get "let: Args out of range: 0, 0"
> C-x C-c

That's the first problem you mentioned, I think.

> Emacs writes (custom-set-variables 
> '(bmkp-last-as-first-bookmark-file "~/.emacs.d/bookmarks")) 
> to my init file without asking me first.

Yes, it does.  This is a feature.  It's your choice, but it's opt-out, not
opt-in.  You can turn it off by customizing option
`bmkp-last-as-first-bookmark-file' (setting it to nil).

See: (1) the doc string of option `bmkp-last-as-first-bookmark-file'
     (2) http://www.emacswiki.org/cgi-bin/wiki/BookmarkPlus#toc37

If you want to have a better idea of what Bookmark+ does and why, take a look at
the doc.  If you're worried about what it might do, read about it before using
it.

> BTW, I happened to skim through bookmark+-mac.el and noticed this:
> ;;      In particular, ALWAYS LOAD `bookmark+-mac.el' (not
> ;;      `bookmark+-mac.elc') BEFORE YOU BYTE-COMPILE new versions of
> ;;      the files, in case there have been any changes to Lisp macros
> ;;      (in `bookmark+-mac.el').
> ;;
> ;;      (This is standard procedure for Lisp: code that depends on
> ;;      macros needs to be byte-compiled anew after loading the
> ;;      updated macros.)
>
> If I byte-compile Bookmark Plus, then in a few months when I 
> update, I'm going to forget your warning, and I'm going to 
> suffer whatever consequences result. Maybe the new packaging 
> system in Emacs 24 helps with such dependency issues?

As the note says, this is standard practice for Lisp.

If the only code that uses a particular macro is in the same file as the macro
definition (and occurs after it), then the caveat is a no-op.  Otherwise, users
of Lisp code that defines and uses macros need to be aware of this in general.
It is not specific to Bookmark+.

Yes, autoloading can help take care of this.  Bookmark+ still needs a few
autoload tweaks to get it to play well with package.el etc.  But it is good to
know about Lisp macros and get in the habit of loading them first, before
byte-compiling code that uses them.  The good news is that that macros file does
not change very often.

Again, sorry for your trouble.  Please try downloading bookmark+-1.el again.
Let me know if you run into another problem.  You can email me off list if you
prefer.

Re: Can't add bookmarks for help pages

[Stefan Monnier]

> Emacs lets me add bookmarks for man and info pages, but not for help pages
> (it says "Buffer not visiting a file or directory"). Not letting me bookmark
> help pages isn't user-friendly.

Agreed.  Patches to add bookmark support to help buffers would
be welcome.


        Stefan

RE: Can't add bookmarks for help pages

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 213 bytes --]

> > Not letting me bookmark help pages isn't user-friendly.
> 
> Agreed.  Patches to add bookmark support to help buffers would
> be welcome.

Attached.

How about a patch to upgrade bookmark.el to Bookmark+? ;-)

[-- Attachment #2: help-mode-2012-06-11.patch --]
[-- Type: application/octet-stream, Size: 2122 bytes --]

diff -c help-mode-patched-2012-06-11.el help-mode.el
*** help-mode-patched-2012-06-11.el	Mon Jun 11 13:49:28 2012
--- help-mode.el	Mon Jun 11 11:27:18 2012
***************
*** 274,282 ****
  Commands:
  \\{help-mode-map}"
    (set (make-local-variable 'revert-buffer-function)
!        'help-mode-revert-buffer)
!   (set (make-local-variable 'bookmark-make-record-function)
!        'help-bookmark-make-record))
  
  ;;;###autoload
  (defun help-mode-setup ()
--- 274,280 ----
  Commands:
  \\{help-mode-map}"
    (set (make-local-variable 'revert-buffer-function)
!        'help-mode-revert-buffer))
  
  ;;;###autoload
  (defun help-mode-setup ()
***************
*** 793,830 ****
    (with-output-to-temp-buffer (help-buffer)
      (insert string)))
  
- \f
- ;; Bookmark support
- 
- (defvar bookmark-make-record-function)
- 
- (declare-function bookmark-prop-get "bookmark" (bookmark prop))
- 
- (defun help-bookmark-make-record ()
-   "Create and return a help-mode bookmark record.
- Implements `bookmark-make-record-function' for help-mode buffers."
-   (unless (car help-xref-stack-item)
-     (error "Cannot create bookmark - help command not known"))
-   `(,@(bookmark-make-record-default 'NO-FILE 'NO-CONTEXT)
-       (buffer-name . "*Help*")
-       (help-fn     . ,(car help-xref-stack-item))
-       (help-arg    . ,(cadr help-xref-stack-item))
-       (position    . ,(point))
-       (handler     . help-bookmark-jump)))
- 
- ;;;###autoload
- (defun help-bookmark-jump (bookmark)
-   "Jump to help-mode bookmark BOOKMARK.
- Handler function for record returned by `help-bookmark-make-record'.
- BOOKMARK is a bookmark name or a bookmark record."
-   (let ((help-fn   (bookmark-prop-get bookmark 'help-fn))
-         (help-arg  (bookmark-prop-get bookmark 'help-arg))
-         (position  (bookmark-prop-get bookmark 'position)))
-     (funcall help-fn help-arg)
-     (pop-to-buffer "*Help*")
-     (goto-char position)))
- 
- 
  (provide 'help-mode)
  
  ;;; help-mode.el ends here
--- 791,796 ----

Diff finished.  Mon Jun 11 13:53:50 2012

Re: Can't add bookmarks for help pages

[Stefan Monnier]

>> Agreed.  Patches to add bookmark support to help buffers would
>> be welcome.
> Attached.

Thanks, installed.

> How about a patch to upgrade bookmark.el to Bookmark+? ;-)

No idea.  Send the bits you think are cleanest first,


        Stefan

RE: Can't add bookmarks for help pages

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 406 bytes --]

> > > Not letting me bookmark help pages isn't user-friendly.
> > 
> > Agreed.  Patches to add bookmark support to help buffers would
> > be welcome.
> 
> Attached.

My bad.  I was unclear about the *Help* xref stack.  That patch worked for help
functions that expect an argument but not for ones that expect no arg.

The attached patch (against the latest help-mode.el) should DTRT.  Sorry for the
noise.

[-- Attachment #2: help-mode-2012-06-12.patch --]
[-- Type: application/octet-stream, Size: 1986 bytes --]

diff -c "help-mode-BZR-2012-06-12.el" "help-mode-patched-2012-06-12.el"
*** help-mode.el	Tue Jun 12 10:00:12 2012
--- help-mode-patched-2012-06-12.el	Tue Jun 12 10:02:46 2012
***************
*** 806,814 ****
    (unless (car help-xref-stack-item)
      (error "Cannot create bookmark - help command not known"))
    `(,@(bookmark-make-record-default 'NO-FILE 'NO-CONTEXT)
-       (buffer-name . "*Help*")
        (help-fn     . ,(car help-xref-stack-item))
!       (help-arg    . ,(cadr help-xref-stack-item))
        (position    . ,(point))
        (handler     . help-bookmark-jump)))
  
--- 806,813 ----
    (unless (car help-xref-stack-item)
      (error "Cannot create bookmark - help command not known"))
    `(,@(bookmark-make-record-default 'NO-FILE 'NO-CONTEXT)
        (help-fn     . ,(car help-xref-stack-item))
!       (help-args   . ,(cdr help-xref-stack-item))
        (position    . ,(point))
        (handler     . help-bookmark-jump)))
  
***************
*** 817,826 ****
    "Jump to help-mode bookmark BOOKMARK.
  Handler function for record returned by `help-bookmark-make-record'.
  BOOKMARK is a bookmark name or a bookmark record."
!   (let ((help-fn   (bookmark-prop-get bookmark 'help-fn))
!         (help-arg  (bookmark-prop-get bookmark 'help-arg))
!         (position  (bookmark-prop-get bookmark 'position)))
!     (funcall help-fn help-arg)
      (pop-to-buffer "*Help*")
      (goto-char position)))
  
--- 816,825 ----
    "Jump to help-mode bookmark BOOKMARK.
  Handler function for record returned by `help-bookmark-make-record'.
  BOOKMARK is a bookmark name or a bookmark record."
!   (let ((help-fn    (bookmark-prop-get bookmark 'help-fn))
!         (help-args  (bookmark-prop-get bookmark 'help-args))
!         (position   (bookmark-prop-get bookmark 'position)))
!     (apply help-fn help-args)
      (pop-to-buffer "*Help*")
      (goto-char position)))
  

Diff finished at Tue Jun 12 10:22:26