GNU bug report logs - #36417
[PATCH] Document bookmark annotations in Emacs Manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 36417 in the body.
You can then email your comments to 36417 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 13:51:27 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Document-bookmark-annotations-in-Emacs-Manual.patch (text/x-patch, attachment)]

Message #8 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36417 <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 17:19:24 +0300

> From: Stefan Kangas <stefan <at> 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.

Message #11 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36417 <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 17:13:33 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Document-bookmark-annotations-in-Emacs-Manual.patch (text/x-patch, attachment)]

Message #14 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36417 <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 17:18:58 +0200

[Message part 1 (text/plain, inline)]

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

Thanks,
Stefan Kangas

[0001-Document-bookmark-annotations-in-Emacs-Manual-3.patch (text/x-patch, attachment)]

Message #17 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefan <at> marxist.se>
Cc: 36417 <at> debbugs.gnu.org
Subject: RE: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 09:01:20 -0700 (PDT)

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

Message #20 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 36417 <at> debbugs.gnu.org
Subject: RE: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 09:07:23 -0700 (PDT)

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

Message #25 received at 36417-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36417-done <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 21:37:25 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 28 Jun 2019 17:18:58 +0200
> Cc: 36417 <at> 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.

Message #28 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: stefan <at> marxist.se, 36417 <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 21:39:32 +0300

> Date: Fri, 28 Jun 2019 09:07:23 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 36417 <at> 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.

Message #31 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: stefan <at> marxist.se, 36417 <at> debbugs.gnu.org
Subject: RE: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 11:52:42 -0700 (PDT)

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

Message #34 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: stefan <at> marxist.se, 36417 <at> debbugs.gnu.org
Subject: Re: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 22:45:02 +0300

> Date: Fri, 28 Jun 2019 11:52:42 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: stefan <at> marxist.se, 36417 <at> 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.

Message #37 received at 36417 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: stefan <at> marxist.se, 36417 <at> debbugs.gnu.org
Subject: RE: bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
Date: Fri, 28 Jun 2019 15:26:43 -0700 (PDT)

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.