Temporary notes in Emacs buffers?

classic Classic list List threaded Threaded
59 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Temporary notes in Emacs buffers?

Marcin Borkowski-3
Hi all,

I've been wondering if there is some package which could let me make
"temporary notes" in Emacs buffers, similar to (but different than) the
"yellow notes" in some pdf viewers.

My use case is that I'm making a sweeping change across a pretty large
codebase, and I'd like to make some notes in places I've already visited
/ ones I need to change / etc.

At present, I use normal code comments, however, this is suboptimal,
since I cannot use them in certain modes (occur buffer, JSON).

Ideally, a place with a comment would have that comment highlighted
somehow, and I should be able to go to the next/previous comment, and
list all comments in a file or in the project (think Git repo,
Projectile project or a directory tree).  Also, mass inserting such
comments from an occur/multi-occur/projectile-ag/counsel-rg/etc. buffers
would be great.

What I /don't/ want is modifying the files - the comments might persist
in some /other/, .gitignore-d file, or just disappear on exiting Emacs.

I know bookmark+ has similar features, but I'd prefer something more
lightweight.

Does there exist something like that?  Am I the only one interested in
such a feature?  (I'd be happy to code it myself, though it would take
time, of course.)

TIA,

--
Marcin Borkowski
http://mbork.pl

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Mpho Jele
Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Tomas Zerolo
On Fri, Dec 27, 2019 at 12:43:46PM +0200, Mpho Jele wrote:
> Check this out: https://github.com/joodland/bm/blob/master/README.md

Throwing "annotate" into the EmacsWiki draws some hits (note:
"annotate" is also a term in version control jargon, where it
has a slightly different meaning, so some filtering is needed):

  https://www.emacswiki.org/emacs/OrgAnnotateFile
  https://www.emacswiki.org/emacs/AnnotationMode
  https://www.emacswiki.org/emacs/org-annotate-file.el
  https://www.emacswiki.org/emacs/Annotate
  https://www.emacswiki.org/emacs/annotate.el

Besides, there's an annotate minor mode in Melpa (M-x list-packages,
in a reasonably recent Emacs) which might cover your needs.

Cheers
-- t

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
In reply to this post by Marcin Borkowski-3
> I've been wondering if there is some package which could let me make
> "temporary notes" in Emacs buffers, similar to (but different than) the
> "yellow notes" in some pdf viewers.
>
> My use case is that I'm making a sweeping change across a pretty large
> codebase, and I'd like to make some notes in places I've already
> visited
> / ones I need to change / etc.
>
> At present, I use normal code comments, however, this is suboptimal,
> since I cannot use them in certain modes (occur buffer, JSON).
>
> Ideally, a place with a comment would have that comment highlighted
> somehow, and I should be able to go to the next/previous comment, and
> list all comments in a file or in the project (think Git repo,
> Projectile project or a directory tree).  Also, mass inserting such
> comments from an occur/multi-occur/projectile-ag/counsel-rg/etc.
> buffers
> would be great.
>
> What I /don't/ want is modifying the files - the comments might persist
> in some /other/, .gitignore-d file, or just disappear on exiting Emacs.
>
> I know bookmark+ has similar features, but I'd prefer something more
> lightweight.
>
> Does there exist something like that?  Am I the only one interested in
> such a feature?  (I'd be happy to code it myself, though it would take
> time, of course.)

Vanilla Emacs bookmarks provide the ability to annotate.
Bookmark+ enhances annotating (e.g. to use Org and
indirection), but the annotation provided by vanilla
Emacs bookmarking does what you requested.

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Sharon Kimble-2
In reply to this post by Marcin Borkowski-3
Marcin Borkowski <[hidden email]> writes:

> Hi all,
>
> I've been wondering if there is some package which could let me make
> "temporary notes" in Emacs buffers, similar to (but different than) the
> "yellow notes" in some pdf viewers.
>
> My use case is that I'm making a sweeping change across a pretty large
> codebase, and I'd like to make some notes in places I've already visited
> / ones I need to change / etc.

Would 'side-notes' from elpa help? Its a buffer that opens up to the
side of your main buffer, in which you can record all sorts of stuff,
its up to you what you use it for. Then you could just put something
like [1] in the file that you are reviewing and a similar [1] in your
side-note with whatever comment you'd like to make. Its your choice.

To save putting a mark in your main file, you could just use
line-numbers, just as an off-the-cuff thought?

Sharon.
--
A taste of linux = http://www.sharons.org.uk
TGmeds = http://www.tgmeds.org.uk
DrugFacts = https://www.drugfacts.org.uk
Debian 10.1, fluxbox 1.3.7, emacs 26.3, org 9.3

signature.asc (847 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Michael Heerdegen
In reply to this post by Marcin Borkowski-3
Marcin Borkowski <[hidden email]> writes:

> At present, I use normal code comments, however, this is suboptimal,
> since I cannot use them in certain modes (occur buffer, JSON).

Is that occur buffer saved to a file?  Because, if it's a dynamically
created buffer, how could notes attached to it be durable at all?

> Does there exist something like that?  Am I the only one interested in
> such a feature?  (I'd be happy to code it myself, though it would take
> time, of course.)

I also considered to implement something like that several times.

We could use overlays to assign the positions and overlay properties to
store note texts and metadata.  When a buffer is edited, the overlay
begin and end marker positions are updated by Emacs on the fly.  I would
use after-save-hook or so to make Emacs save that stuff automatically
for every file save.  Where it is saved would be (file locally)
configurable: in a file local variable, in a directory local variable,
or in a configurable central place.

When you open a file, a minor-mode-hook would arrange that everything is
restored.

There would also be a variant for dired buffers to attach notes to whole
files.

Michael.

Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> I also considered to implement something like that several times.
>
> We could use overlays to assign the positions and overlay properties to
> store note texts and metadata.  When a buffer is edited, the overlay
> begin and end marker positions are updated by Emacs on the fly.  I
> would use after-save-hook or so to make Emacs save that stuff
> automatically for every file save.  Where it is saved would be (file
> locally) configurable: in a file local variable, in a directory local
> variable, or in a configurable central place.
>
> When you open a file, a minor-mode-hook would arrange that everything
> is restored.
>
> There would also be a variant for dired buffers to attach notes to
> whole files.

FWIW: Marcin said he wasn't interested, but
Bookmark+ really does offer all of that already.

Locations (single position or start+end) of
such "notes" (bookmarks) can be automatically
highlighted.  You can cycle next/previous. You
can hit a key to edit the content (annotation).
Or access any by its name.  (Names can also be
autogenerated.)

[You can also bookmark a multi-region - a set
of zones in a file (or across multiple files).
In that case, you have a single annotation for
the whole set.  (You can have any number of
such sets.)]

Bookmarks are pretty flexible.  You can use
them in lots of different ways.

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Michael Heerdegen
Drew Adams <[hidden email]> writes:

> Bookmarks are pretty flexible.  You can use them in lots of different
> ways.

Yeah - probably.  What I dislike I think: if I move a file to a
different location, the relation to the notes is lost, and I have to
manually relocate the file.  That might be annoying.  That's why my
favorite approach would be to save the data in the file itself or at
least in its directory instead of a central place.  Or is there a
solution for that problem using bookmarks, too?

Thanks,

Michael.

Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> > Bookmarks are pretty flexible.  You can use
> > them in lots of different ways.
>
> Yeah - probably.  What I dislike I think: if I move a file to a
> different location, the relation to the notes is lost, and I have to
> manually relocate the file.  That might be annoying.  That's why my
> favorite approach would be to save the data in the file itself or at
> least in its directory instead of a central place.  Or is there a
> solution for that problem using bookmarks, too?

If you move the destination of a bookmark (the
file or the positions in it) then, when you try
to jump to it:

* If the file is available, but the contexts for
  the recorded positions within it can't be
  found, then an attempt is made to relocate -
  searching for the recorded contexts (text
  before & after the positions.

  If that's not successful, because the file has
  changed too much, then you're prompted to
  relocate the positions.

* If the general location (e.g. file) has moved,
  then you're prompted to relocate it.

You can also manually relocate a bookmark's
target any time, of course.

But normally, if the file has not moved, when
you jump to a bookmark the target positions are
automatically updated (well, it's optional):
The recorded positions are used as a starting
point, and then the recorded contexts are found.
If those have moved then the new location is
recorded.

---

There are advantages to saving annotations (e.g.
bookmarks) in a separate file from their targets.
And there are advantages of saving them in the
same file.

An annotation is a kind of metadata - a note
about the file content or a location.  There
are pros and cons for storing metadata and data
together.  This isn't special to file annotations.

---

You can have any number of bookmark files, and
they can be stored anywhere.  You can, as you
mention, store a file of bookmarks in the same
directory as the file or files that they target.

So you can, if you like, easily move both at
the same time, e.g. to another directory.

However, yes, the target file names recorded in
the bookmarks are absolute names.  So you would
want to define a command that not only moves the
bookmark file and its targeted files, together,
to the same new directory, but also updates the
recorded file names in the bookmarks, to reflect
the new target directory.  That wouldn't be hard.

You can also have bookmark lists composed of
bookmark lists.  And mappings between bookmark
files and bookmark lists need not be 1:1.  You
can have a bookmark file for a book you're
writing, and bookmark lists for each of its
chapters.  Or separate bookmark files for the
chapters.

And you can bookmark a bookmark list, e.g.,
switch to a different chapter just by jumping
to a bookmark-list bookmark.

The only requirement is that a bookmark file
be separate from the files targeted by its
bookmarks.  Why?  Because, like a directory,
a bookmark file is a list of a bunch of files
and their metadata.

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

John Yates-4
My sense of why bookmarks of any sort are not
a solution is that the mapping goes the wrong
way.  You open a list of bookmarks and expect
them to take you to the appropriate targets.
Marcin seems to want to open the target and
have it known whether or not there are any
relevant notes.

/john
Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> My sense of why bookmarks of any sort are not
> a solution is that the mapping goes the wrong
> way.  You open a list of bookmarks and expect
> them to take you to the appropriate targets.
> Marcin seems to want to open the target and
> have it known whether or not there are any
> relevant notes.

That's not true of Bookmark+ bookmarks.
As I said, you can automatically highlight
their locations.  As Marcin requested:

  > similar to (but different than) the
  > "yellow notes" in some pdf viewers.

And you can use different kinds of highlighting
for different sets of bookmarks.

You need not ever display a list of bookmarks,
or even a list of a given set/type of bookmarks.
You can access (show/edit) a bookmark at its
point of use (its target).

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Marcin Borkowski-3
In reply to this post by John Yates-4

On 2020-01-01, at 21:34, John Yates <[hidden email]> wrote:

> My sense of why bookmarks of any sort are not
> a solution is that the mapping goes the wrong
> way.  You open a list of bookmarks and expect
> them to take you to the appropriate targets.
> Marcin seems to want to open the target and
> have it known whether or not there are any
> relevant notes.

Yes and no.  In the end, I need the list, too.  But this is a very good
point.

Thanks,

--
Marcin Borkowski
http://mbork.pl

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Marcin Borkowski-3
In reply to this post by Tomas Zerolo

On 2019-12-27, at 12:51, [hidden email] wrote:

> On Fri, Dec 27, 2019 at 12:43:46PM +0200, Mpho Jele wrote:
>> Check this out: https://github.com/joodland/bm/blob/master/README.md
>
> Throwing "annotate" into the EmacsWiki draws some hits (note:
> "annotate" is also a term in version control jargon, where it
> has a slightly different meaning, so some filtering is needed):
>
>   https://www.emacswiki.org/emacs/OrgAnnotateFile
>   https://www.emacswiki.org/emacs/AnnotationMode
>   https://www.emacswiki.org/emacs/org-annotate-file.el
>   https://www.emacswiki.org/emacs/Annotate
>   https://www.emacswiki.org/emacs/annotate.el
>
> Besides, there's an annotate minor mode in Melpa (M-x list-packages,
> in a reasonably recent Emacs) which might cover your needs.

Thanks to both of you, I will check these out.

Best,

--
Marcin Borkowski
http://mbork.pl

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Michael Heerdegen
In reply to this post by Drew Adams
Drew Adams <[hidden email]> writes:

> However, yes, the target file names recorded in
> the bookmarks are absolute names.  So you would
> want to define a command that not only moves the
> bookmark file and its targeted files, together,
> to the same new directory, but also updates the
> recorded file names in the bookmarks, to reflect
> the new target directory.  That wouldn't be hard.

Not hard, but a disadvantage, because I need to remember that I need to
do it.  All the time.  Or hack any possible way to move files in Emacs.
That's a big minus for me.

Michael.

Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> > However, yes, the target file names recorded in
> > the bookmarks are absolute names.  So you would
> > want to define a command that not only moves the
> > bookmark file and its targeted files, together,
> > to the same new directory, but also updates the
> > recorded file names in the bookmarks, to reflect
> > the new target directory.  That wouldn't be hard.
>
> Not hard, but a disadvantage, because I need to remember that I need to
> do it.  All the time.  Or hack any possible way to move files in Emacs.
> That's a big minus for me.

Do you really often move files for which you have
associated notes?

If so, then you might consider defining a file
handler, to take care of that automatically (by
its `rename-file' operation).

---

Or yes, not use bookmarks for your annotations.

It's clear that the bookmarks that target a
file are something separate from the file,
linked with it only by that targeting.

This is different from, say, file attributes,
which "stay with the file" when you move it,
because they're managed by the same thing that
does the moving: the file system.

And it is different from, say, storing notes
in the file content in some way.

As I said earlier, there are advantages to
having such metadata as part of the data
(file). There are also disadvantages.  It
depends on the various things you want to do,
and how they're implemented.

Bookmarks aren't the answer to everything. ;-)

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Michael Heerdegen
Drew Adams <[hidden email]> writes:

> Do you really often move files for which you have associated notes?

I don't know yet.  But the bookmarks should at least survive making
backups, and remain visible when viewing them at that other place, or
after moving the containing folder for archiving or so.  I would say:
often enough that it matters, yes.

> Or yes, not use bookmarks for your annotations.

Well, they mostly fit, if they would not force me to use absolute file
names.  You are sure that there is no predefined way to use relative
names?

Michael.

Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> > Do you really often move files for which you have associated notes?
>
> I don't know yet.  But the bookmarks should at least survive making
> backups, and remain visible when viewing them at that other place, or
> after moving the containing folder for archiving or so.  I would say:
> often enough that it matters, yes.

I guess you mean just what you said before: You
want to be able to move a file, and some bookmarks
that target it, to a different directory, and have
the bookmarks continue to work there.

> > Or yes, not use bookmarks for your annotations.
>
> Well, they mostly fit, if they would not force me to use absolute file
> names.  You are sure that there is no predefined way to use relative
> names?

You can define a bookmark handler for any type of
bookmark.  The handler could ignore the directory
part of the recorded file name, and get the needed
directory from somewhere else, e.g., from a global
variable or a function.  (It has to come from
somewhere.)  E.g., a variable could have an alist
value with keys for your different whatevers (even
nondir-filename keys) and with dirs as the values.

But then you'd have to update the variable value
when you move the targeted files.  As I said before,
you can write code that does something like that
(my earlier suggestion was code that changes the
target-file names in the bookmarks, but that's not
great) - e.g. code that's kicked off by a bespoke
file-move command.  (But then you have to remember
to use that command to move such files...)

However you look at it, the target file is separate
from bookmarks that refer to it - that's the nature
of the thing.  Something has to let either the
bookmarks themselves or the bookmark-handling code
know where you moved the target file.

(You can also define new types of bookmarks.  E.g.,
you could define one that records a target location
that's just the nondirectory part of a file name.
But this isn't really necessary - the dir part of
an absolute file name could just be ignored - see
above.)

Other than that (you define a handler), this kind
of handling (look up the dir somewhere) could be
added as a general (optional) feature.  The use
case hadn't occurred to me.

Maybe give it a try (define a handler that looks
up the dir somewhere), and let me know how useful
you find it.  (Add your new handler to the value
of variable `bmkp-file-bookmark-handlers', so the
bookmarks will satisfy `bmkp-file-bookmark-p'.)

Or if you don't get around to that then maybe I'll
do something.  But it's less likely that whatever
I might come up with will fit what you need as well
as what you might come up with.  And maybe by
experimenting a bit you'll find that bookmarks are
really not the way you want to go...

---

[Bookmark+ has "autofile" bookmarks, whose bookmark
names are the nondirectory parts of the full file
names.  You can have multiple bookmarks with the
same name, which is a relative file name in this
case.  But the target file recorded in the bookmark
is an absolute name (so far).]

Reply | Threaded
Open this post in threaded view
|

RE: Temporary notes in Emacs buffers?

Drew Adams
> You can define a bookmark handler for any type of
> bookmark.  The handler could ignore the directory
> part of the recorded file name, and get the needed
> directory from somewhere else, e.g., from a global
> variable or a function.  (It has to come from
> somewhere.)  E.g., a variable could have an alist
> value with keys for your different whatevers (even
> nondir-filename keys) and with dirs as the values.
>
> But then you'd have to update the variable value
> when you move the targeted files.  As I said before,
> you can write code that does something like that
> (my earlier suggestion was code that changes the
> target-file names in the bookmarks, but that's not
> great) - e.g. code that's kicked off by a bespoke
> file-move command.  (But then you have to remember
> to use that command to move such files...)
>
> However you look at it, the target file is separate
> from bookmarks that refer to it - that's the nature
> of the thing.  Something has to let either the
> bookmarks themselves or the bookmark-handling code
> know where you moved the target file.

Let me add this:

If your use case is limited to being in the same
directory as the file targeted by your bookmark(s),
then you can just use `default-directory' in your
handler, as the directory in which to look up the
file name (ignoring any recorded directory).

This could be the case, e.g., if you always accessed
your bookmarks from the file itself (e.g., at their
highlighted locations there).  That's the case we've
been discussing, at least in part.

It's also possible to use `default-directory' if
you want to use a relative file name that includes
more than just the non-directory part.  E.g., if
your file is in a subdir of `default-directory`
(current pwd), then you could look it up using
the relevant part of the recorded absolute file
name.  (Or your new bookmark type could record
only such a relevant part as the target location.)

This could be the case if you access the bookmarks
from a parent or other directory (relative file
names can include `../' etc.), but you'll know
where you'll access them from, so the handler can
assume that directory - no need to look it up
somewhere.

There are various possibilities, depending on just
what you might want to do.

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Marcin Borkowski-3
In reply to this post by Michael Heerdegen

On 2020-01-01, at 02:42, Michael Heerdegen <[hidden email]> wrote:

> Marcin Borkowski <[hidden email]> writes:
>
>> At present, I use normal code comments, however, this is suboptimal,
>> since I cannot use them in certain modes (occur buffer, JSON).
>
> Is that occur buffer saved to a file?  Because, if it's a dynamically
> created buffer, how could notes attached to it be durable at all?

Yes, I have saved it.

Best,

--
Marcin Borkowski
http://mbork.pl

Reply | Threaded
Open this post in threaded view
|

Re: Temporary notes in Emacs buffers?

Marcin Borkowski-3
In reply to this post by Drew Adams

On 2020-01-01, at 05:45, Drew Adams <[hidden email]> wrote:

>> I also considered to implement something like that several times.
>>
>> We could use overlays to assign the positions and overlay properties to
>> store note texts and metadata.  When a buffer is edited, the overlay
>> begin and end marker positions are updated by Emacs on the fly.  I
>> would use after-save-hook or so to make Emacs save that stuff
>> automatically for every file save.  Where it is saved would be (file
>> locally) configurable: in a file local variable, in a directory local
>> variable, or in a configurable central place.
>>
>> When you open a file, a minor-mode-hook would arrange that everything
>> is restored.
>>
>> There would also be a variant for dired buffers to attach notes to
>> whole files.
>
> FWIW: Marcin said he wasn't interested, but
> Bookmark+ really does offer all of that already.

I know that, but it is very big and thus daunting to me.

Best,

--
Marcin Borkowski
http://mbork.pl

123