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

From: Stefan Kangas <[email-masked]>
Date: Fri, 28 Jun 2019 17:18:58 +0200

I've attached a new version with hopefully slightly clearer wording.

Thanks,
Stefan Kangas
From aa1115202346572f720eedd38e147cd5a48ac7f8 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
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..68a8245b34 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.  If a bookmark has an
+annotation, it is automatically shown in a separate window when you
+jump to the 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