bug#36417: [PATCH] Document bookmark annotations in Emacs Manual

[Stefan Kangas <stefan@marxist.se>]

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

Eli Zaretskii <eliz@gnu.org> writes:
> > +@vindex bookmark-use-annotations
> > +@vindex bookmark-automatically-show-annotations
>
> How about "@cindex bookmark annotations" as well?

Done.

> > +  If you set the variable @code{bookmark-use-annotations} to t,
>                                                                 ^
> @code{t}

Done.  Would we also want to do this change while we're at it, or is
it ok as is?

-  If you set the variable @code{bookmark-save-flag} to 1, each command
+  If you set the variable @code{bookmark-save-flag} to @code{1}, each command

> > +setting a bookmark will query for an annotation.  The annotation will
> > +be automatically shown when you jump to that bookmark.
>
> Please explain what does "show" mean in this context.

Done.  Let me know if it's not clear enough.

> Btw, what is the use case for using annotations but not showing them?
> If that use case is not important enough, perhaps we shouldn't mention
> the second option.

Good point.  I don't think it's a very important use case, so I
removed it.

Thank you for reviewing; sorry about the basic mistakes.  Please find
attached an updated patch.

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-Document-bookmark-annotations-in-Emacs-Manual.patch --]
[-- Type: text/x-patch, Size: 1962 bytes --]

From 251d4b3de994a4d9a55e2ec94a3c9945d4297d38 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 28 Jun 2019 13:40:37 +0200
Subject: [PATCH] Document bookmark annotations in Emacs Manual

* doc/emacs/regs.texi (Bookmarks): Document annotations.
* lisp/bookmark.el (bookmark-use-annotations): Clarify docstring.
---
 doc/emacs/regs.texi | 7 +++++++
 lisp/bookmark.el    | 5 +----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 3702694647..1c8e338e65 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -359,6 +359,13 @@ Bookmarks
   The variable @code{bookmark-default-file} specifies the file in
 which to save bookmarks by default.
 
+@vindex bookmark-use-annotations
+@cindex bookmark annotations
+  If you set the variable @code{bookmark-use-annotations} to @code{t},
+setting a bookmark will query for an annotation.  The annotation will
+be automatically shown in a separate window when you jump to a
+bookmark.
+
 @vindex bookmark-search-size
   Bookmark position values are saved with surrounding context, so that
 @code{bookmark-jump} can find the proper position even if the file is
diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 9a3a2a3bdf..bbef0a927d 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -36,9 +36,6 @@
 
 ;;; Misc comments:
 ;;
-;; If variable bookmark-use-annotations is non-nil, an annotation is
-;; queried for when setting a bookmark.
-;;
 ;; The bookmark list is sorted lexically by default, but you can turn
 ;; this off by setting bookmark-sort-flag to nil.  If it is nil, then
 ;; the list will be presented in the order it is recorded
@@ -52,7 +49,7 @@ bookmark
 
 
 (defcustom bookmark-use-annotations nil
-  "If non-nil, saving a bookmark queries for an annotation in a buffer."
+  "If non-nil, setting a bookmark queries for an annotation in a buffer."
   :type 'boolean
   :group 'bookmark)
 
-- 
2.11.0