Add org-bookmark-heading to Org proper?

Add org-bookmark-heading to Org proper?

[Adam Porter]

As mentioned in <87oa3gs8tc.fsf@gmx.us>, some changes to the org-id
functions are being proposed.  My org-bookmark-heading package uses
org-id-find, so if that function changes or is removed, I'd have to
change the package for newer Org versions.

Given that, now might be a good time to consider merging the package
into Org proper.  It seems like something that should be in Org already,
being able to make Emacs bookmarks that point to Org headings.  It's
actually just three functions, so not much of a "package" really.

https://github.com/alphapapa/org-bookmark-heading

Thoughts?  :)

Re: Add org-bookmark-heading to Org proper?

[Xebar Saram]

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

I *highly* support this. i use

org-bookmark-heading extensivly and its very much part of my base org mode
workflow

thx


best

Z

On Thu, Sep 22, 2016 at 5:33 PM, Adam Porter <adam@alphapapa.net> wrote:

> As mentioned in <87oa3gs8tc.fsf@gmx.us>, some changes to the org-id
> functions are being proposed.  My org-bookmark-heading package uses
> org-id-find, so if that function changes or is removed, I'd have to
> change the package for newer Org versions.
>
> Given that, now might be a good time to consider merging the package
> into Org proper.  It seems like something that should be in Org already,
> being able to make Emacs bookmarks that point to Org headings.  It's
> actually just three functions, so not much of a "package" really.
>
> https://github.com/alphapapa/org-bookmark-heading
>
> Thoughts?  :)
>
>
>

[-- Attachment #2: Type: text/html, Size: 1392 bytes --]

Re: Add org-bookmark-heading to Org proper?

[Kaushal Modi]

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

I have seen mailing list references like the one below a couple of times.
But they have never worked for me. Email clients in browser like
gmail/inbox treat them as email addresses. So when I click them, I get a
compose window with To: email set to "87oa3gs8tc.fsf@gmx.us". Do such links
work only in gnus and such? If so, it would be useful to have a generic
usual http format link.

Note that even
http://lists.gnu.org/archive/html/emacs-orgmode/2016-09/msg00359.html shows
that as:

> As mentioned in <address@hidden>, some changes to the org-id



On Thu, Sep 22, 2016 at 11:08 AM Adam Porter <adam@alphapapa.net> wrote:

> As mentioned in <87oa3gs8tc.fsf@gmx.us>,
>
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1327 bytes --]

Re: Add org-bookmark-heading to Org proper?

[Adam Porter]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I have seen mailing list references like the one below a couple of
> times. But they have never worked for me. Email clients in browser
> like gmail/inbox treat them as email addresses. So when I click them,
> I get a compose window with To: email set to "87oa3gs8tc.fsf@gmx.us".
> Do such links work only in gnus and such? If so, it would be useful to
> have a generic usual http format link.
>
> Note that even
> http://lists.gnu.org/archive/html/emacs-orgmode/2016-09/msg00359.html
> shows that as:

Sorry about that.  I read the list with Gnus through Gmane, and I don't
know of a better way to do it, other than going to the list archive site
and digging up the URL, which seems like a lot of trouble...  ;) AFAIK
you can google the message-ID and get to the thread in question,
although it might be a few days before Google indexes it.
Alternatively, Gnus should be able to access it directly through Gmane
NNTP, and when the new Gmane web interface comes online, that should
work too.

Re: Add org-bookmark-heading to Org proper?

[Aaron Ecay]

Hi Adam,

The package looks useful, and we ought to have this functionality as
part of org.  The first question that arises is whether you have
completed the copyright assignment process described at
<http://orgmode.org/worg/org-contribute.html#orgheadline1>: an
assignment is necessary for any patches to org-mode core.

The assignment process takes some time, so (if the assignment is
something you want to do) you can go ahead and get started.  You only
have to go through the process once, and you’re covered for this and
all future contributions to org mode/emacs.

-- 
Aaron Ecay

Re: Add org-bookmark-heading to Org proper?

[Adam Porter]

Aaron Ecay <aaronecay@gmail.com> writes:

> The first question that arises is whether you have
> completed the copyright assignment process described at
> <http://orgmode.org/worg/org-contribute.html#orgheadline1>: an
> assignment is necessary for any patches to org-mode core.

I was expecting that to be the next question.  ;)  I haven't done so
yet, but I'd be glad to.  I'll put it on my todo list and report back
when it's done.

Re: Add org-bookmark-heading to Org proper?

[Nicolas Goaziou]

Hello,

> Given that, now might be a good time to consider merging the package
> into Org proper.  It seems like something that should be in Org already,
> being able to make Emacs bookmarks that point to Org headings.  It's
> actually just three functions, so not much of a "package" really.
>
> https://github.com/alphapapa/org-bookmark-heading
>
> Thoughts?  :)

I think Org could benefit from a shrunk version of this library, i.e.,
`org-bookmark-make-record' and `org-bookmark-jump'.

However I'm not convinced about `org-bookmark-jump-indirect' since this
variable complicates code and the same effect can be achieved easily
once the destination headline is reached.

Besides, the helm part doesn't really belong to Org. IIUC, it is not
even needed if we drop support for `org-bookmark-jump-indirect', as
suggested above.

A few suggestions, after a cursory look:

- please switch to lexical binding as all but one file in Org core,

- it is "Org mode", not "org-mode"

- `org-replace-links-in-string-with-desc' already exists, it is
  (mis)called `org-link-display-format'

- `assoc' -> `assq' when key is a symbol

- if you create a marker, unset it once useless

- first sentence in docstrings has to fit in the first line.


Thank you for your work.


Regards,

-- 
Nicolas Goaziou

Re: Add org-bookmark-heading to Org proper?

[Adam Porter]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

Hi Nicholas,

> I think Org could benefit from a shrunk version of this library, i.e.,
> `org-bookmark-make-record' and `org-bookmark-jump'.
>
> However I'm not convinced about `org-bookmark-jump-indirect' since this
> variable complicates code and the same effect can be achieved easily
> once the destination headline is reached.
>
> Besides, the helm part doesn't really belong to Org. IIUC, it is not
> even needed if we drop support for `org-bookmark-jump-indirect', as
> suggested above.

Yes, the Helm-related code would certainly be left out.  I could propose
a patch to Thierry or make it a separate package on MELPA.

The indirect feature could be left out as well, but I find it so useful
that I think it might be worth including so that users can try it.  It
really transforms the way I use Org, especially in combination with some
other functions I have that use indirect buffers when jumping to items
from the agenda.  It wouldn't need to be enabled by default, of course.
But it's not strictly necessary, so I won't fight you on that if you
want to leave it out.  ;)  

> A few suggestions, after a cursory look:
>
> - please switch to lexical binding as all but one file in Org core,
>
> - it is "Org mode", not "org-mode"
>
> - `org-replace-links-in-string-with-desc' already exists, it is
>   (mis)called `org-link-display-format'
>
> - `assoc' -> `assq' when key is a symbol
>
> - if you create a marker, unset it once useless
>
> - first sentence in docstrings has to fit in the first line.

Thanks for reading through the code and finding these.  I'll go through
them soon and prepare a patch (which I'll post after doing the copyright
assignment).

> Thank you for your work.

No, thank you!  :D

Re: Add org-bookmark-heading to Org proper?

[Nicolas Goaziou]

Hello,

Adam Porter <adam@alphapapa.net> writes:

> The indirect feature could be left out as well, but I find it so useful
> that I think it might be worth including so that users can try it.  It
> really transforms the way I use Org, especially in combination with some
> other functions I have that use indirect buffers when jumping to items
> from the agenda.  It wouldn't need to be enabled by default, of course.
> But it's not strictly necessary, so I won't fight you on that if you
> want to leave it out.  ;)

I think controlling how the bookmark locations are displayed is
a different feature, which may fit better in Bookmark than in Org.

We could introduce a generic hook somewhere so that to permit users
adding their own display mechanism. However, the variable is, IMO, too
specific.

On another topic, by looking at bookmark.el, it seems you shouldn't
create the internal representation of the bookmarks by hand, and use
setters instead (e.g., `bookmark-set-filename').

Regards,

-- 
Nicolas Goaziou

Re: Add org-bookmark-heading to Org proper?

[Adam Porter]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

Hi Nicolas,

> I think controlling how the bookmark locations are displayed is
> a different feature, which may fit better in Bookmark than in Org.

I think I see what you mean, but at the same time, it seems like an
Org-specific feature since it calls org-tree-to-indirect-buffer.  I
guess I think of Org as building on core Emacs features, so putting an
Org-specific feature in core bookmark.el seems...backwards?  (Though I'm
not sure that's what you meant...)

> We could introduce a generic hook somewhere so that to permit users
> adding their own display mechanism. However, the variable is, IMO, too
> specific.

That hook idea sounds interesting, but I'm not sure I understand how it
would be different than the built-in bookmark-handler feature.
bookmark-handle-bookmark says that the handler it calls, "changes
current buffer and point and returns nil, or signals a `file-error'," so
that's what my org-bookmark-jump handler does, in an Org-specific way.

The indirect-buffer feature could of course be removed from
org-bookmark-jump, and a user could add it himself as advice that runs
afterward.

Or maybe something like an org-bookmark-jump-hook could be added to call
other functions after jumping to an Org bookmark. I guess this is what
you meant, I just had to talk myself through it.  :)

> On another topic, by looking at bookmark.el, it seems you shouldn't
> create the internal representation of the bookmarks by hand, and use
> setters instead (e.g., `bookmark-set-filename').

I went by the docstring for bookmark-make-record-function, which says
that modes can set it buffer-locally for locations that should be
treated specially, and that the function called should return a record
according to bookmark-alist.  I guess the setters are intended for
modifying existing bookmarks...?

Thanks for your feedback.

Re: Add org-bookmark-heading to Org proper?

[Nicolas Goaziou]

Hello,

Adam Porter <adam@alphapapa.net> writes:

> I think I see what you mean, but at the same time, it seems like an
> Org-specific feature since it calls org-tree-to-indirect-buffer.  I
> guess I think of Org as building on core Emacs features, so putting an
> Org-specific feature in core bookmark.el seems...backwards?  (Though I'm
> not sure that's what you meant...)

I'm not saying that Bookmark should call `org-tree-to-indirect-buffer',
but provide a way for major modes to specify a jump function.

In any way, you are right, it already exists through the `handler'
mechanism.

> That hook idea sounds interesting, but I'm not sure I understand how it
> would be different than the built-in bookmark-handler feature.

There is only one handler per major mode. Providing a "-function" (or
a "-hook", it depends if it extends a default feature or replace it)
variable could allow users to add their own "view" function
(`org-tree-to-indirect-buffer' in your case, but not limited to it).

> Or maybe something like an org-bookmark-jump-hook could be added to call
> other functions after jumping to an Org bookmark. I guess this is what
> you meant, I just had to talk myself through it.  :)

This is what I meant.

> I went by the docstring for bookmark-make-record-function, which says
> that modes can set it buffer-locally for locations that should be
> treated specially, and that the function called should return a record
> according to bookmark-alist.  I guess the setters are intended for
> modifying existing bookmarks...?

It makes sense, indeed.


Regards,

-- 
Nicolas Goaziou