[ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Adam Porter]

Hi friends,

I've published an easy-to-use version of a tool that I think Org has
long needed: a sidebar tree-view buffer for navigating outlines.

https://github.com/alphapapa/org-sidebar#org-sidebar-tree

There have been some similar, unpolished tools floating around,
including an answer I posted on Emacs.StackExchange several years ago.
And the org-panes package has been around even longer, but hasn't been
touched for 5 years, and it isn't on MELPA, so few people know about it.

So I've put together org-sidebar-tree and released it as part of
org-sidebar, which makes it easy to use and customize.  Here are some
screenshots:

https://github.com/alphapapa/org-sidebar/raw/master/images/tree.gif
https://github.com/alphapapa/org-sidebar/raw/master/images/sidebar-with-tree.png
https://github.com/alphapapa/org-sidebar/raw/master/images/tree-and-item-sidebars.png

It seems to work well, but I'm sure wider testing will reveal some
improvements to be made.  I'd appreciate any feedback.

Thanks,
Adam

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Fraga, Eric]

On Tuesday,  1 Oct 2019 at 09:01, Adam Porter wrote:
> I've published an easy-to-use version of a tool that I think Org has
> long needed: a sidebar tree-view buffer for navigating outlines.

Hi Adam,

thanks for the heads up.  I have my own hand-crafted rather primitive
tool for this so it will be nice to see a properly implemented
version.  I'll give it a try and will get back to you.  I hope it works
well with evil...

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.2.4-401-gfabd6d

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Fraga, Eric]

Hi Adam,

I've had a chance to play with it a little bit.  Works very well
generally.  Some notes:

- a way to exit the sidebar-tree mode to get back to the full buffer
  (e.g. to run commands that require the whole file).  The documentation
  seems to indicate that 'q' should do this but it didn't work for
  me.  I do use evil mode but q didn't work whether in evil or emacs
  states.

- hitting RET on a headline which has subtrees doesn't show the
  subtrees.  Can this be customized?  It might be nice to have two
  different bindings to allow for recursion and not.
  
- invoking org-sidebar-tree when point is at the top of the file,
  e.g. on the #+title: line of a document, gives an error:
  outline-back-to-heading: Before first heading.

I will probably use this in place of my rough and ready version.

Thanks,
eric

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.2.4-401-gfabd6d

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Adam Porter]

"Fraga, Eric" <e.fraga@ucl.ac.uk> writes:

> Hi Adam,
>
> I've had a chance to play with it a little bit.  Works very well
> generally.  Some notes:

Hi Eric,

> - a way to exit the sidebar-tree mode to get back to the full buffer
>   (e.g. to run commands that require the whole file).  The documentation
>   seems to indicate that 'q' should do this but it didn't work for
>   me.  I do use evil mode but q didn't work whether in evil or emacs
>   states.

Please note that it's not a mode, it's just a side window displaying an
indirect buffer in Org mode (like how org-tree-to-indirect-buffer
works).  You can do anything in the tree-view buffer that you can do in
any other Org buffer, including inputting characters, calling Org
commands, switching windows, killing the buffer, deleting the window,
etc.

The only difference is that certain keys are bound by default to
commands which are more appropriate for the tree-view buffer, e.g. the
cycle commands don't show body text, and RET/mouse-1 jump to headings in
the source window.

"q" is no longer bound differently, and the readme has been updated.

> - hitting RET on a headline which has subtrees doesn't show the
>   subtrees.  Can this be customized?  It might be nice to have two
>   different bindings to allow for recursion and not.

Like other Org buffers, <tab> is used to cycle headings by default.  As
documented, the keymap org-sidebar-tree-map is used, which you're free
to customize.

I recently improved the tree-view cycling command to work more like
org-cycle.  Please let me know if you think it needs more work.

> - invoking org-sidebar-tree when point is at the top of the file,
>   e.g. on the #+title: line of a document, gives an error:
>   outline-back-to-heading: Before first heading.

That bug is fixed.

Note as well that the tree-view can be activated for narrowed Org
buffers, in which case it is also narrowed to the visible portion of the
buffer.  So you can, e.g.:

1.  "M-x customize-option RET org-sidebar-tree-jump-fn RET", and set it to
    use indirect buffers when jumping to headings.
2.  "M-x org-sidebar-tree RET" in an Org buffer.
3.  Move point to a heading and press RET to display that heading in the
    other window.
4.  "M-x org-sidebar-tree RET" to display only that subtree in the
    tree-view buffer.

This makes it easy to treat subtrees as separate projects or entities.

Thanks for your feedback!

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Fraga, Eric]

Thanks for the clarifications and updates.  I'll play some more and will
get back to you.

-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.2.6-544-gd215c3

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[stardiviner]

This is really a helpful sidebar package. Thanks :) I like it very much.

Hope can add an command to toggle it. I found I have to manually close it.

Adam Porter <adam@alphapapa.net> writes:

> Hi friends,
>
> I've published an easy-to-use version of a tool that I think Org has
> long needed: a sidebar tree-view buffer for navigating outlines.
>
> https://github.com/alphapapa/org-sidebar#org-sidebar-tree
>
> There have been some similar, unpolished tools floating around,
> including an answer I posted on Emacs.StackExchange several years ago.
> And the org-panes package has been around even longer, but hasn't been
> touched for 5 years, and it isn't on MELPA, so few people know about it.
>
> So I've put together org-sidebar-tree and released it as part of
> org-sidebar, which makes it easy to use and customize.  Here are some
> screenshots:
>
> https://github.com/alphapapa/org-sidebar/raw/master/images/tree.gif
> https://github.com/alphapapa/org-sidebar/raw/master/images/sidebar-with-tree.png
> https://github.com/alphapapa/org-sidebar/raw/master/images/tree-and-item-sidebars.png
>
> It seems to work well, but I'm sure wider testing will reveal some
> improvements to be made.  I'd appreciate any feedback.
>
> Thanks,
> Adam


-- 
[ stardiviner ]
       I try to make every word tell the meaning what I want to express.

       Blog: https://stardiviner.github.io/
       IRC(freenode): stardiviner, Matrix: stardiviner
       GPG: F09F650D7D674819892591401B5DF1C95AE89AC3
      

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Adam Porter]

stardiviner <numbchild@gmail.com> writes:

> This is really a helpful sidebar package. Thanks :) I like it very much.
>
> Hope can add an command to toggle it. I found I have to manually close it.

FYI, I just added some toggle commands.  Thanks for the suggestion.

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Adam Porter]

Gustav,

There are a lot of deprecation recommendations in your attached
document:

> I propose to depricate property-keywords
> I propose to depricate the Options-keyword
> I propose to relabel these keywords as document keywords
> I propose to depricate the #+CATEGORY syntax
> I propose to depricate the #+FILETAGS syntax
> I propose to depricate the #+COLUMNS syntax
> I propose to depricate the #+ARCHIVE syntax
> I propose to depricate the TODO-keywords
> I propose to depricate the priorities-keyword
> I propose to depricate the tags-keyword
> I propose to depricate the link-keyword
> I propose to depricate the constants-keyword
> I propose to depricate the setupfile-keyword
> I propose to depricate the Macro-keyword

The thoroughness of your investigation is admirable.

However, I propose that we don't deprecate any of those.  Org has been
around for over a decade now.  Such drastic changes would not serve
users well.

Note that I'm taking your use of the word "deprecate" to mean what
it's expected to mean in this context: that the software developers
recommend against using it, with the intention to eventually remove
support for the feature.  We shouldn't be removing any such features
from Org.

Not only would it not serve users well, but it would make the software
much more complicated.  As it stands, finding, e.g. a #+CATEGORY:
keyword and getting its value is as simple as:

    (save-excursion
      (goto-char (point-min))
      (when (re-search-forward (rx bol "#+CATEGORY:" (1+ blank)
                                   (group (1+ nonl)))
                               nil t)
        (match-string 1)))

Hiding those keywords in drawers means that either:

a) Eligible drawers must be located, and then the desired
property must be searched for inside of them.

b) Possibly valid properties must be located, and each one must be
confirmed to be inside an eligible drawer.

What benefit would this added complexity serve?  To put the keywords
in one place in the document?  There are already multiple ways to
achieve that.

I can't emphasize enough how important stability and consistency is
for Org and its file formats right now.  As I've said, there are new
implementations in development, which have the potential to bring a
lot of publicity and new users to Org.  For example, this one was
mentioned on a Hacker News post a few days ago:

https://github.com/mickael-kerjean/filestash

In the same HN post were examples of implementations for Vim and
VSCode.  Already, especially in the VSCode ones, there were apparent
incompatibilities in their implementations of the Org file format.

As well, there are now parsers in JavaScript, Python, and Rust.

Markdown is by far the most popular plain-text format, and has been
for years, but it has long suffered from competing, slightly
incompatible flavors and implementations.  Reddit has theirs, GitHub
has theirs, etc.

Org's file format may finally be gaining some momentum.  Let's not
jeopardize Org's chances by making implementors' job more difficult
than it already is.

Re: [ANN] org-sidebar-tree: Sidebar tree-view buffer for outline navigation

[Adam Porter]

Clearly my Gnus-fu is weak, as somehow I posted that in entirely the
wrong thread.  :)