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

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

[Stefan Kangas]

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

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

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

From d13c355eb7d1cc345ae953ab9daefd81f12c8018 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 | 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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 28 Jun 2019 13:51:27 +0200
> 
> +@vindex bookmark-use-annotations
> +@vindex bookmark-automatically-show-annotations

How about "@cindex bookmark annotations" as well?

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

> +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.

> +@code{bookmark-automatically-show-annotations} to nil.
                                                     ^^^
@code{nil}

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.

Thanks.

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

[Stefan Kangas]

[-- 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

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

[Stefan Kangas]

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

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

Thanks,
Stefan Kangas

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

From aa1115202346572f720eedd38e147cd5a48ac7f8 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..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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 28 Jun 2019 17:18:58 +0200
> Cc: 36417@debbugs.gnu.org
> 
> I've attached a new version with hopefully slightly clearer wording.

Thanks, pushed.

> > > +  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

There's no need, as 1 always stands for itself.

> sorry about the basic mistakes

No need to apologize; thanks for working on this.

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

[Drew Adams]

> > 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.

It should not be removed.  Many users like to have
an annotation-edit/create buffer displayed whenever
they set (create or update) a bookmark.  Many other
users do not want this behavior, but prefer to add
or edit an annotation only on demand.

This option is at least as important as the other
one.

In both cases a user can prefer to only deal with
annotations on demand - not have them popped up
in their face.  But for users who do want them in
their face, they can want that for setting or for
jumping, or for both.

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

[Eli Zaretskii]

> Date: Fri, 28 Jun 2019 09:07:23 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 36417@debbugs.gnu.org
> 
> > > 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.
> 
> It should not be removed.

We didn't remove the variable, we just avoided documenting it in the
manual.  Not every option of every package is documented in the Emacs
manual.  If you think bookmark.el warrants a more detailed
documentation, please consider writing a separate Texinfo manual for
it, as we have for many other packages.

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

[Drew Adams]

> 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.

Showing a bookmark's annotation means displaying
it (in its own buffer).

Option `bookmark-automatically-show-annotations'
is about _automatically_ showing annotations
whenever bookmarks are jumped to.  If it is nil
then a bookmark's annotation is shown (displayed)
only on demand.

Option `bookmark-use-annotations" non-nil means
that a buffer is opened for you to add an
annotation, if none exists, or edit an existing
annotation, whenever a bookmark is set.

One is about showing annotations when bookmarks
are jumped to.  The other is about editing (and
creating) annotations whenever bookmarks are set
(created or updated).

It is true that the doc string for
`bookmark-use-annotations' mistakenly currently
says `saving' instead of `setting'.  That, at
least, should be corrected.

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

[Drew Adams]

> > > > 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.
> >
> > It should not be removed.
> 
> We didn't remove the variable, we just avoided documenting it in the
> manual.  

Yes, I realized that.  And that was perhaps based on
Stefan's saying he doesn't think it's a very important
use case.

I pointed out that it is just as important as using
the other option.

> Not every option of every package is documented in the Emacs
> manual.

No, of course not.  You always say that, as if
someone claimed the contrary.  No one has _ever_
done so, as far I know.

> If you think bookmark.el warrants a more detailed
> documentation, please consider writing a separate Texinfo manual for
> it, as we have for many other packages.

That's reading a lot into my reply.  I was setting
the record straight wrt what these variables are
for, and pointing out that neither is more important
than the other.  You can document them both in the
manual or remove them both from the manual, as far
as I'm concerned.  You can document only one of them,
but there is not special reason (IMHO) to choose this
one or that one.

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

[Eli Zaretskii]

> Date: Fri, 28 Jun 2019 11:52:42 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: stefan@marxist.se, 36417@debbugs.gnu.org
> 
> > > > > 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.
> > >
> > > It should not be removed.
> > 
> > We didn't remove the variable, we just avoided documenting it in the
> > manual.  
> 
> Yes, I realized that.  And that was perhaps based on
> Stefan's saying he doesn't think it's a very important
> use case.

He said that in response to my question, which I asked because I also
didn't see that as too important.

> I pointed out that it is just as important as using
> the other option.

You are in minority here.

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

[Drew Adams]

> > > We didn't remove the variable, we just avoided
> > > documenting it in the manual.
> >
> > Yes, I realized that.  And that was perhaps based on
> > Stefan's saying he doesn't think it's a very important
> > use case.
> 
> He said that in response to my question, which I asked
> because I also didn't see that as too important.

Seriously?  It doesn't seem like you even
knew what it was for.

You asked, "What is the use case for using
annotations but not showing them?"

I had to point out that (1) "using" is a
misnomer for _setting_ (creating, editing),
and (2) "using" an annotation _does_ also
show it.

The actions take place at different times.

The annotation is shown in both cases.  So
your question made no sense: there is no
"using" an annotation without showing it.

You can't go by the words "use" and "show"
in the two variable names.

I imagine a real question behind what you
asked might be, "What is the use case for
the "*-use-*" variable?".  I answered that.

> > I pointed out that it is just as important as using
> > the other option.
> 
> You are in minority here.

Whoop-dee-doo!