* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
@ 2019-06-28 11:51 Stefan Kangas
2019-06-28 14:19 ` Eli Zaretskii
0 siblings, 1 reply; 11+ messages in thread
From: Stefan Kangas @ 2019-06-28 11:51 UTC (permalink / raw)
To: 36417
[-- 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
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 11:51 bug#36417: [PATCH] Document bookmark annotations in Emacs Manual Stefan Kangas
@ 2019-06-28 14:19 ` Eli Zaretskii
2019-06-28 15:13 ` Stefan Kangas
0 siblings, 1 reply; 11+ messages in thread
From: Eli Zaretskii @ 2019-06-28 14:19 UTC (permalink / raw)
To: Stefan Kangas; +Cc: 36417
> 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 14:19 ` Eli Zaretskii
@ 2019-06-28 15:13 ` Stefan Kangas
2019-06-28 15:18 ` Stefan Kangas
2019-06-28 16:07 ` Drew Adams
0 siblings, 2 replies; 11+ messages in thread
From: Stefan Kangas @ 2019-06-28 15:13 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 36417
[-- 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
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 15:13 ` Stefan Kangas
@ 2019-06-28 15:18 ` Stefan Kangas
2019-06-28 18:37 ` Eli Zaretskii
2019-06-28 16:07 ` Drew Adams
1 sibling, 1 reply; 11+ messages in thread
From: Stefan Kangas @ 2019-06-28 15:18 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 36417
[-- 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
^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 15:18 ` Stefan Kangas
@ 2019-06-28 18:37 ` Eli Zaretskii
0 siblings, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2019-06-28 18:37 UTC (permalink / raw)
To: Stefan Kangas; +Cc: 36417-done
> 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 15:13 ` Stefan Kangas
2019-06-28 15:18 ` Stefan Kangas
@ 2019-06-28 16:07 ` Drew Adams
2019-06-28 18:39 ` Eli Zaretskii
1 sibling, 1 reply; 11+ messages in thread
From: Drew Adams @ 2019-06-28 16:07 UTC (permalink / raw)
To: Stefan Kangas, Eli Zaretskii; +Cc: 36417
> > 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#36417: [PATCH] Document bookmark annotations in Emacs Manual
2019-06-28 16:07 ` Drew Adams
@ 2019-06-28 18:39 ` Eli Zaretskii
0 siblings, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2019-06-28 18:39 UTC (permalink / raw)
To: Drew Adams; +Cc: stefan, 36417
> 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.
^ permalink raw reply [flat|nested] 11+ messages in thread
[parent not found: <<CADwFkm=Bvo+Y3fjbzLdthQwPsjZ1sS_J4vMqNzp_rzX7DVUKzA@mail.gmail.com>]
[parent not found: <<<CADwFkm=Bvo+Y3fjbzLdthQwPsjZ1sS_J4vMqNzp_rzX7DVUKzA@mail.gmail.com>]
end of thread, other threads:[~2019-06-28 22:26 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-06-28 11:51 bug#36417: [PATCH] Document bookmark annotations in Emacs Manual Stefan Kangas
2019-06-28 14:19 ` Eli Zaretskii
2019-06-28 15:13 ` Stefan Kangas
2019-06-28 15:18 ` Stefan Kangas
2019-06-28 18:37 ` Eli Zaretskii
2019-06-28 16:07 ` Drew Adams
2019-06-28 18:39 ` Eli Zaretskii
[not found] <<CADwFkm=Bvo+Y3fjbzLdthQwPsjZ1sS_J4vMqNzp_rzX7DVUKzA@mail.gmail.com>
[not found] ` <<83y31lhjwz.fsf@gnu.org>
2019-06-28 16:01 ` Drew Adams
[not found] ` <<CADwFkmm89N1q7SQ0YY++Q=k5pOwZmQhjOs+aAT6BHptwk6eqHA@mail.gmail.com>
[not found] ` <<93a1eeb8-568b-4ecc-9d38-37ac23545977@default>
[not found] ` <<83mui1h7vf.fsf@gnu.org>
2019-06-28 18:52 ` Drew Adams
2019-06-28 19:45 ` Eli Zaretskii
[not found] <<<CADwFkm=Bvo+Y3fjbzLdthQwPsjZ1sS_J4vMqNzp_rzX7DVUKzA@mail.gmail.com>
[not found] ` <<<83y31lhjwz.fsf@gnu.org>
[not found] ` <<<CADwFkmm89N1q7SQ0YY++Q=k5pOwZmQhjOs+aAT6BHptwk6eqHA@mail.gmail.com>
[not found] ` <<<93a1eeb8-568b-4ecc-9d38-37ac23545977@default>
[not found] ` <<<83mui1h7vf.fsf@gnu.org>
[not found] ` <<079f4f36-497b-4580-905f-3acb2eb89f3e@default>
[not found] ` <<83k1d5h4u9.fsf@gnu.org>
2019-06-28 22:26 ` Drew Adams
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).