Advice on studying Emacs Lisp files

Advice on studying Emacs Lisp files

[Marcin Borkowski]

OK,

so I started a personal project of code reading.  I would like to start
with (standard) Emacs files.

However, here's a problem: I'd like to take notes while I'm studying.
And it's no surprise that I'd like to use Emacs to do this.  For obvious
reasons, I don't want to make my notes in the files themselves (as
comments).  OTOH, if I copy them to some personal directory, I lose the
ability to use find-function (which will jump to the original files).

Do you have any suggestions for a good workflow for that?  I might use
Org-mode (and links), but it would involve jumping between buffers,
which might not be optimal.  Maybe someone has a better idea?

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> so I started a personal project of code reading.  I would like to start
> with (standard) Emacs files.
> 
> However, here's a problem: I'd like to take notes while I'm studying.
> And it's no surprise that I'd like to use Emacs to do this.  For obvious
> reasons, I don't want to make my notes in the files themselves (as
> comments).  OTOH, if I copy them to some personal directory, I lose the
> ability to use find-function (which will jump to the original files).
> 
> Do you have any suggestions for a good workflow for that?  I might use
> Org-mode (and links), but it would involve jumping between buffers,
> which might not be optimal.  Maybe someone has a better idea?

You can bookmark locations, and use annotations for your notes.
If you use Bookmark+ then you can use Org mode for the annotations.

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-14, at 22:59, Drew Adams <drew.adams@oracle.com> wrote:

>> so I started a personal project of code reading.  I would like to start
>> with (standard) Emacs files.
>> 
>> However, here's a problem: I'd like to take notes while I'm studying.
>> And it's no surprise that I'd like to use Emacs to do this.  For obvious
>> reasons, I don't want to make my notes in the files themselves (as
>> comments).  OTOH, if I copy them to some personal directory, I lose the
>> ability to use find-function (which will jump to the original files).
>> 
>> Do you have any suggestions for a good workflow for that?  I might use
>> Org-mode (and links), but it would involve jumping between buffers,
>> which might not be optimal.  Maybe someone has a better idea?
>
> You can bookmark locations, and use annotations for your notes.
> If you use Bookmark+ then you can use Org mode for the annotations.

That's interesting, thanks a lot!  I will definitely check that out,
I had no idea about this functionality.  I'll have to check whether
these bookmarks/annotations are somehow visible in the buffer they point
to.

Regards,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> >> I'd like to take notes while I'm studying... I don't want to make my
> >> notes in the files themselves (as comments)...
> >>
> >> Do you have any suggestions for a good workflow for that?  I might use
> >> Org-mode (and links), but it would involve jumping between buffers,
> >> which might not be optimal.  Maybe someone has a better idea?
> >
> > You can bookmark locations, and use annotations for your notes.
> > If you use Bookmark+ then you can use Org mode for the annotations.
> 
> ... I will definitely check that out, I had no idea about this
> functionality.  I'll have to check whether these bookmarks/annotations
> are somehow visible in the buffer they point to.

If you use Bookmark+ then you can make bookmark locations be highlighted
in various ways. This is optional.

http://www.emacswiki.org/emacs/BookmarkPlus#HighlightingBookmarkLocations

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-15, at 00:30, Drew Adams <drew.adams@oracle.com> wrote:

>> >> I'd like to take notes while I'm studying... I don't want to make my
>> >> notes in the files themselves (as comments)...
>> >>
>> >> Do you have any suggestions for a good workflow for that?  I might use
>> >> Org-mode (and links), but it would involve jumping between buffers,
>> >> which might not be optimal.  Maybe someone has a better idea?
>> >
>> > You can bookmark locations, and use annotations for your notes.
>> > If you use Bookmark+ then you can use Org mode for the annotations.
>> 
>> ... I will definitely check that out, I had no idea about this
>> functionality.  I'll have to check whether these bookmarks/annotations
>> are somehow visible in the buffer they point to.
>
> If you use Bookmark+ then you can make bookmark locations be highlighted
> in various ways. This is optional.
>
> http://www.emacswiki.org/emacs/BookmarkPlus#HighlightingBookmarkLocations

Wow, that is impressive.  I have one problem though: how to
create/edit/view annotations for bookmarks /without/ using the bookmark
list?  I.e., for the bookmark at point or something?

Also, how to set (in init.el) the default way for highlighting
bookmarks?  I'd prefer the "right fringe" style and not the "right
fringe + line" one.

Also, I've set bmkp-crosshairs-flag to t, but cannot see the
crosshairs.  (I have the necessary libraries installed).  This is
probably too vague anyway, I'll try to look into this problem myself.

TIA,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> >> >> I'd like to take notes while I'm studying... I don't want to make my
> >> >> notes in the files themselves (as comments)...
> >> >
> >> > You can bookmark locations, and use annotations for your notes.
> >> > If you use Bookmark+ then you can use Org mode for the annotations.
> >>
> >> ...visible in the buffer they point to.
> >
> > If you use Bookmark+ then you can make bookmark locations be
> > highlighted in various ways.  This is optional.
> > http://www.emacswiki.org/emacs/BookmarkPlus#HighlightingBookmarkLocations
> 
> Wow, that is impressive.  I have one problem though: how to
> create/edit/view annotations for bookmarks /without/ using the
> bookmark list?  I.e., for the bookmark at point or something?

1. See standard options `bookmark-use-annotations' and
`bookmark-automatically-show-annotations'.

2. In Bookmark+, standard functions `bookmark-edit-annotation',
`bookmark-show-annotation', and `bookmark-show-all-annotations' are
also commands.  The first two prompt you for the name of an annotated
bookmark (with completion) and then show you the annotation.

With a prefix arg, `bookmark-edit-annotation' lets you choose any
bookmark, so you can add an annotation to an unannotated bookmark.
Otherwise, it lets you choose an annotated bookmark, to edit the
annotation.

You can also use command `bmkp-annotate-bookmark' to add or edit
an annotation, instead of using `bookmark-edit-annotation' with a
prefix arg.

> Also, how to set (in init.el) the default way for highlighting
> bookmarks?  I'd prefer the "right fringe" style and not the "right
> fringe + line" one.

Customize option `bmkp-light-style-non-automated' and/or option
`bmkp-light-style-autonamed'.  The latter is for autonamed
bookmarks; the former is for all other kinds of bookmarks.
 
> Also, I've set bmkp-crosshairs-flag to t, but cannot see the
> crosshairs.  (I have the necessary libraries installed).  This is
> probably too vague anyway, I'll try to look into this problem myself.

Yes, too vague.  Recursively bisect your init file until you find the
culprit.  Ask yourself first whether crosshairs highlighting works
elsewhere, i.e., whether your problem arises only for indicating
bookmark destinations or is more general.

Please download the latest files for Bookmark+.  You can follow up
with me off list for any such questions, if you like.

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-17, at 21:32, Drew Adams <drew.adams@oracle.com> wrote:

>> >> >> I'd like to take notes while I'm studying... I don't want to make my
>> >> >> notes in the files themselves (as comments)...
>> >> >
>> >> > You can bookmark locations, and use annotations for your notes.
>> >> > If you use Bookmark+ then you can use Org mode for the annotations.
>> >>
>> >> ...visible in the buffer they point to.
>> >
>> > If you use Bookmark+ then you can make bookmark locations be
>> > highlighted in various ways.  This is optional.
>> > http://www.emacswiki.org/emacs/BookmarkPlus#HighlightingBookmarkLocations
>> 
>> Wow, that is impressive.  I have one problem though: how to
>> create/edit/view annotations for bookmarks /without/ using the
>> bookmark list?  I.e., for the bookmark at point or something?
>
> 1. See standard options `bookmark-use-annotations' and
> `bookmark-automatically-show-annotations'.

Thanks!  BTW, the latter one seems to be `t' by default.

> 2. In Bookmark+, standard functions `bookmark-edit-annotation',
> `bookmark-show-annotation', and `bookmark-show-all-annotations' are
> also commands.  The first two prompt you for the name of an annotated
> bookmark (with completion) and then show you the annotation.

This does not seem to be the case for the latter two functions.  (I have
bookmark+ from the Git repo mentioned on the EW page.)

> With a prefix arg, `bookmark-edit-annotation' lets you choose any
> bookmark, so you can add an annotation to an unannotated bookmark.
> Otherwise, it lets you choose an annotated bookmark, to edit the
> annotation.
>
> You can also use command `bmkp-annotate-bookmark' to add or edit
> an annotation, instead of using `bookmark-edit-annotation' with a
> prefix arg.

Thanks.  I'll have to digest everything here slowly and mold it into my
workflow.

>> Also, how to set (in init.el) the default way for highlighting
>> bookmarks?  I'd prefer the "right fringe" style and not the "right
>> fringe + line" one.
>
> Customize option `bmkp-light-style-non-automated' and/or option
                                         ^^^^^^^^^ autonamed, of course
> `bmkp-light-style-autonamed'.  The latter is for autonamed
> bookmarks; the former is for all other kinds of bookmarks.

Is it a good idea to run bmkp-light-bookmarks in a hook or something, so
that the bookmarks ale always visible, or can it e.g. degrade
performance?

>> Also, I've set bmkp-crosshairs-flag to t, but cannot see the
>> crosshairs.  (I have the necessary libraries installed).  This is
>> probably too vague anyway, I'll try to look into this problem myself.
>
> Yes, too vague.  Recursively bisect your init file until you find the
> culprit.  Ask yourself first whether crosshairs highlighting works
> elsewhere, i.e., whether your problem arises only for indicating
> bookmark destinations or is more general.

I disabled crosshairs altogether, it seems that it doesn't really do any
good to me.

> Please download the latest files for Bookmark+.  You can follow up
> with me off list for any such questions, if you like.

As above: I used the git repo.

As for the other suggestion: I decided to write here anyway, someone
might be interested in this, too.  Also, once I figure out a workflow
for my use case, I intend to describe it on my site.

Thanks a lot,

-- 
Marcin Borkowski               This email was proudly sent
http://mbork.pl                from my Emacs.

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> > 1. See standard options `bookmark-use-annotations' and
> >    `bookmark-automatically-show-annotations'.
> 
> Thanks!  BTW, the latter one seems to be `t' by default.

That is the vanilla Emacs default.  I generally leave such things
alone.  All of the vanilla options (i.e., `bookmark-*') are left
alone.  Bookmark+ option names have the prefix `bmkp-'.

> > 2. In Bookmark+, standard functions `bookmark-edit-annotation',
> > `bookmark-show-annotation', and `bookmark-show-all-annotations' are
> > also commands.  The first two prompt you for the name of an annotated
> > bookmark (with completion) and then show you the annotation.
> 
> This does not seem to be the case for the latter two functions.  (I have
> bookmark+ from the Git repo mentioned on the EW page.)

What does not seem to be the case - they are not commands or they
do not prompt you as I said?

Anyway, both claims should hold.  I suspect that you do not have
the latest source files.  The latest files are always on Emacs Wiki.
I cannot speak to when or how successfully mirroring happens. ;-)
 
> > option `bmkp-light-style-non-automated' and/or option
>                                ^^^^^^^^^ autonamed, of course

Yes, that's what I meant.

> > `bmkp-light-style-autonamed'.  The latter is for autonamed
> > bookmarks; the former is for all other kinds of bookmarks.
> 
> Is it a good idea to run bmkp-light-bookmarks in a hook or something,
> so that the bookmarks ale always visible, or can it e.g. degrade
> performance?

There are options for highlighting all bookmarks or particular
kinds of bookmarks automatically when you jump to or set a bookmark:
`bmkp-auto-light-when-jump' and `bmkp-auto-light-when-set'.  You
generally do not need to fiddle with hooks (in particular, hooks
`bookmark-after-jump-hook' and `bmkp-after-set-hook').

Option `bmkp-light-threshold' controls the number of bookmark
highlights.

I doubt that performance will be affected in any noticeable way.
It is more a question of what you find helpful vs what you find
annoying.  Different strokes for different folks.

IMO, highlighting is most helpful for bookmarks in the current
buffer, in particular for autonamed bookmarks or when cycling
among bookmarks in the buffer.

> As for the other suggestion: I decided to write here anyway, someone
> might be interested in this, too.  Also, once I figure out a workflow
> for my use case, I intend to describe it on my site.  Thanks a lot

You're welcome.

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-24, at 00:38, Drew Adams <drew.adams@oracle.com> wrote:

>> > 2. In Bookmark+, standard functions `bookmark-edit-annotation',
>> > `bookmark-show-annotation', and `bookmark-show-all-annotations' are
>> > also commands.  The first two prompt you for the name of an annotated
>> > bookmark (with completion) and then show you the annotation.
>> 
>> This does not seem to be the case for the latter two functions.  (I have
>> bookmark+ from the Git repo mentioned on the EW page.)
>
> What does not seem to be the case - they are not commands or they
> do not prompt you as I said?

Two of them are not interactive.

> Anyway, both claims should hold.  I suspect that you do not have
> the latest source files.  The latest files are always on Emacs Wiki.
> I cannot speak to when or how successfully mirroring happens. ;-)

I see.  I'll update my install.

>> Is it a good idea to run bmkp-light-bookmarks in a hook or something,
>> so that the bookmarks ale always visible, or can it e.g. degrade
>> performance?
>
> There are options for highlighting all bookmarks or particular
> kinds of bookmarks automatically when you jump to or set a bookmark:
> `bmkp-auto-light-when-jump' and `bmkp-auto-light-when-set'.  You
> generally do not need to fiddle with hooks (in particular, hooks
> `bookmark-after-jump-hook' and `bmkp-after-set-hook').

What I meant was that I want the bookmarks to be highlighted as soon as
I visit the file.

> Option `bmkp-light-threshold' controls the number of bookmark
> highlights.
>
> I doubt that performance will be affected in any noticeable way.
> It is more a question of what you find helpful vs what you find
> annoying.  Different strokes for different folks.

Yes.  I do not intend to use bookmarks very heavily (i.e., not too many
of them), and I'd like them to be highlighted by default, without any
explicit action.

> IMO, highlighting is most helpful for bookmarks in the current
> buffer, in particular for autonamed bookmarks or when cycling
> among bookmarks in the buffer.

Yes.  However, this seems to be a tautology: I'm *always* in the
"current buffer"!

Also, I want to use bookmarks to, well, mark places I consider bugs, for
instance.  I'd like to *see* them even when just scrolling through the
buffer.

Thanks again!

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> I want the bookmarks to be highlighted as soon as I visit the file...
> I do not intend to use bookmarks very heavily (i.e., not too many of
> them), and I'd like them to be highlighted by default, without any
> explicit action.

See `bmkp-(un)light-bookmarks' and `bmkp-(un)light-this-buffer'.

Use them from Lisp or interactively.  `bmkp-(un)light-bookmarks':

`C-x p H', `C-x p U' - Highlight, unhighlight bookmarks:
                       With plain `C-u': all bookmarks
                       With `C-u C-u': navigation-list bookmarks
                       Otherwise, bookmarks in current buffer:
                        No prefix arg:  all bookmarks
                        Prefix arg > 0: autonamed bookmarks
                                   < 0: non-autonamed bookmarks

More generally, please consult the bookmark highlighting doc.

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-24, at 16:40, Drew Adams <drew.adams@oracle.com> wrote:

>> I want the bookmarks to be highlighted as soon as I visit the file...
>> I do not intend to use bookmarks very heavily (i.e., not too many of
>> them), and I'd like them to be highlighted by default, without any
>> explicit action.
>
> See `bmkp-(un)light-bookmarks' and `bmkp-(un)light-this-buffer'.
>
> Use them from Lisp or interactively.  `bmkp-(un)light-bookmarks':

So do I get it correctly that the best bet (assuming that I want the
bookmarks to be highlighted by default) is to call bmkp-light-bookmarks
in some hook firing after loading?

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> >> I want the bookmarks to be highlighted as soon as I visit the file...
> >> I do not intend to use bookmarks very heavily (i.e., not too many of
> >> them), and I'd like them to be highlighted by default, without any
> >> explicit action.
> >
> > See `bmkp-(un)light-bookmarks' and `bmkp-(un)light-this-buffer'.
> >
> > Use them from Lisp or interactively.  `bmkp-(un)light-bookmarks':
> 
> So do I get it correctly that the best bet (assuming that I want the
> bookmarks to be highlighted by default) is to call bmkp-light-bookmarks
> in some hook firing after loading?

After loading what?  That function lights up a set of bookmarks.
You could pass it your `bookmark-alist' as arg and it would then
light up *all* of your bookmarks.  But such all-bookmarks behavior
is not provided interactively, because it is not in fact useful.

`bmkp-light-bookmarks' just highlights.  It does not open any
buffers, and if a bookmark's buffer is not displayed then (for
better or worse) its highlighting is simply applied to the
current buffer.

`bmkp-light-bookmarks' is meant for bookmark locations that are
already displayed.  The interactive use cases defined for it
are really those that make sense (whether you invoke it
interactively or not).

Highlighting a bookmark makes little sense if the bookmarked
location is not visible.  And if it is visible then its buffer
is displayed somewhere.  Go to the buffer and then highlight
bookmarks there.  If you turn on `bmkp-auto-light-when-jump'
then getting there by jumping takes care of highlighting the
location.

I don't know what your best bet is.  I'd say just customize
`bmkp-auto-light-when-jump' and `bmkp-auto-light-when-set'
to the value `all-in-buffer'.  Then setting or jumping to a
bookmark will light all of the bookmarks in its buffer.

Or put `bmkp-light-this-buffer' on a hook such as  a mode hook
or `find-file-hook'.

I'd say start by playing with bookmarks a bit: setting them,
jumping to them, cycling among them, etc.  Play with autonamed
bookmarks, which are particularly useful with highlighting.

Once you find out how you will actually be using bookmarks,
you will, I think, discover how you want them to make use of
highlighting.

Re: Advice on studying Emacs Lisp files

[Marcin Borkowski]

On 2015-01-24, at 00:38, Drew Adams <drew.adams@oracle.com> wrote:

>> > 1. See standard options `bookmark-use-annotations' and
>> >    `bookmark-automatically-show-annotations'.
>> 
>> Thanks!  BTW, the latter one seems to be `t' by default.
>
> That is the vanilla Emacs default.  I generally leave such things
> alone.  All of the vanilla options (i.e., `bookmark-*') are left
> alone.  Bookmark+ option names have the prefix `bmkp-'.

OK, now I have another (not very important) problem.  With
bookmark-automatically-show-annotations set to t, I get a buffer with
the annotation when I jump to a bookmark.  However, it is read-only and
basically unusable for e.g. editing the annotation.  Is this intended
behavior?

>> > 2. In Bookmark+, standard functions `bookmark-edit-annotation',
>> > `bookmark-show-annotation', and `bookmark-show-all-annotations' are
>> > also commands.  The first two prompt you for the name of an annotated
>> > bookmark (with completion) and then show you the annotation.
>> 
>> This does not seem to be the case for the latter two functions.  (I have
>> bookmark+ from the Git repo mentioned on the EW page.)
>
> What does not seem to be the case - they are not commands or they
> do not prompt you as I said?
>
> Anyway, both claims should hold.  I suspect that you do not have
> the latest source files.  The latest files are always on Emacs Wiki.
> I cannot speak to when or how successfully mirroring happens. ;-)

Now I know.  There was seemingly some confusion about loading.  I guess
I should have restarted my Emacs, since some parts of the bookmarking
code seemed to come from the vanilla Emacs parts.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> >> > 1. See standard options `bookmark-use-annotations' and
> >> >    `bookmark-automatically-show-annotations'.
> >>
> >> Thanks!  BTW, the latter one seems to be `t' by default.
> >
> > That is the vanilla Emacs default.  I generally leave such things
> > alone.  All of the vanilla options (i.e., `bookmark-*') are left
> > alone.  Bookmark+ option names have the prefix `bmkp-'.
> 
> OK, now I have another (not very important) problem.  With
> bookmark-automatically-show-annotations set to t, I get a buffer with
> the annotation when I jump to a bookmark.  However, it is read-only and
> basically unusable for e.g. editing the annotation.  Is this intended
> behavior?

Yes.  If you want to edit an annotation then use
`bookmark-edit-annotation' instead of `bookmark-show-annotation'.
But that advice doesn't help for automatic showing of annotations -
that is always show-only, not edit.

I suppose it would make sense to provide a key binding for the edit
command in the show-only buffer, or perhaps let you choose to have
automatically shown annotations open for editing.

I'll think about it.  I don't use annotations, myself, and I've done
little more with that feature than what is in vanilla Emacs.  The
main thing I did (recently) was to allow for using Org mode (or any
other) and allow for an annotation to be external (in a separate file).

RE: Advice on studying Emacs Lisp files

[Drew Adams]

> > OK, now I have another (not very important) problem.  With
> > bookmark-automatically-show-annotations set to t, I get a buffer with
> > the annotation when I jump to a bookmark.  However, it is read-only and
> > basically unusable for e.g. editing the annotation.  Is this intended
> > behavior?
> 
> Yes.  If you want to edit an annotation then use
> `bookmark-edit-annotation' instead of `bookmark-show-annotation'.
> But that advice doesn't help for automatic showing of annotations -
> that is always show-only, not edit.
> 
> I suppose it would make sense to provide a key binding for the edit
> command in the show-only buffer, or perhaps let you choose to have
> automatically shown annotations open for editing.
> 
> I'll think about it.  I don't use annotations, myself, and I've done
> little more with that feature than what is in vanilla Emacs.  The
> main thing I did (recently) was to allow for using Org mode (or any
> other) and allow for an annotation to be external (in a separate file).

I've taken care of this now.

If you set option `bookmark-automatically-show-annotations' to `edit'
then an automatically shown annotation opens in edit mode.

And you can switch between edit mode and read-only (show) mode
using `C-x C-q'.

---

Especially if you use annotations heavily, consider using external
annotations.  An external annotation is stored in a separate file,
URL, or bookmark, not in your bookmarks file, i.e., not as part of
the bookmark that it annotates.

Accessing an external annotation (e.g. showing it) visits its
destination.  So for example, you can use bookmarks to one or more
Org files to annotate one or more bookmarks.  The annotation saved
with the bookmark itself just specifies the destination. 

See http://www.emacswiki.org/emacs/BookmarkPlus#BookmarkAnnotations.