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

From: Stefan Kangas <[email-masked]>
Date: Fri, 28 Jun 2019 13:51:27 +0200

bookmark.el has a useful feature to set and show annotations.  This is
unfortunately not very well documented in the Emacs manual.

Please find attached a patch that attempts to document this feature.

Thanks,
Stefan Kangas
From d13c355eb7d1cc345ae953ab9daefd81f12c8018 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 | 8 ++++++++
 lisp/bookmark.el    | 5 +----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 3702694647..6a584038ed 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -359,6 +359,14 @@ Bookmarks
   The variable @code{bookmark-default-file} specifies the file in
 which to save bookmarks by default.
 
+@vindex bookmark-use-annotations
+@vindex bookmark-automatically-show-annotations
+  If you set the variable @code{bookmark-use-annotations} to t,
+setting a bookmark will query for an annotation.  The annotation will
+be automatically shown when you jump to that bookmark.  If you want to
+use annotations but not show them automatically, you can set
+@code{bookmark-automatically-show-annotations} to nil.
+
 @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 381b912944..68b762ddd6 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)

-- 
2.11.0