org-toc.el - browsable table of contents for Org

org-toc.el - browsable table of contents for Org

[Bastien]

Hi folks,

here is a new package for Org. It lets you browse the table of contents
of any Org buffer:

  http://www.cognition.ens.fr/~guerry/u/org-toc.el

What it basically does is to create an indirect buffer from your Org
buffer, set it to read-only, then lets you navigate through it.

Here is what the help message looks like:

,----
| [return] jump to heading           [1-4] hide headlines below this level
| [space]  go to heading             [c] toggle column view
| [TAB]    cycle subtree             [f] toggle follow mode
| [q]      quit the TOC              [i] toggle info mode
| [n/p]    next/previous heading     [r] toggle recenter mode
`----

Thanks again to Carsten for useful hints and early feedback on this.
Please test it and send me any feedback.

Enjoy!

-- 
Bastien

Re: org-toc.el - browsable table of contents for Org

[Levin]

> Hi folks,
>
> here is a new package for Org. It lets you browse the table of contents
> of any Org buffer:
>
>   http://www.cognition.ens.fr/~guerry/u/org-toc.el
>
> What it basically does is to create an indirect buffer from your Org
> buffer, set it to read-only, then lets you navigate through it.
>

This is very useful. It'll be another org killer tool.
I'd like to make some suggestions:
1. Preserve the org buffer tree state when entering org-toc. Currently they 
are all collapsed.

2. pressing tab in org-toc will not only cyle in org buffer, but also in the 
org-toc buffer (of course, only headlines are shown).

3. it's very useful for org-toc to keep its state, so next time it is called, 
the toc structure is shown and unchanged. (maybe one org-toc per org buffer, 
and pressing `g' in org-toc to refresh?)

-Levin

Re: org-toc.el - browsable table of contents for Org

[Bastien]

Levin <zslevin@gmail.com> writes:

> This is very useful. It'll be another org killer tool.

Thanks!  I'm releasing org-toc.el 0.7:

  http://www.cognition.ens.fr/~guerry/u/org-toc.el

I've been thinking quite carefully about your suggestions. 

> 1. Preserve the org buffer tree state when entering org-toc. Currently
> they are all collapsed.

This was intentional. I want to keep Org base buffer and Org TOC
(indirect) buffer as visually distinct as possible. So the default
behavior is to display a table of contents showing the first level
headlines.

You can set `org-toc-default-depth' to another level if you want.

When this variable is set to `nil', Org TOC will display a TOC that is
in the same *global* state of folding, except that it will never show
all the content of the file -- it will show all *branches* instead
(otherwise the TOC wouldn't be a TOC anymore, right?)

> 2. pressing tab in org-toc will not only cyle in org buffer, but also
> in the org-toc buffer (of course, only headlines are shown).

I want the TAB-related keys to cycle through states in the base buffer,
not in the TOC buffer.  So TAB will cycle through the current subtree,
S-TAB will cycle globally, but both will do their job in the base Org
buffer.

To cycle *locally*, use the `:' (org-toc-cycle-subtree) which operates
in the current TOC buffer (and cycle through FOLDED CHILDREN BRANCHES).

> 3. it's very useful for org-toc to keep its state, so next time it is
> called, the toc structure is shown and unchanged. (maybe one org-toc
> per org buffer, and pressing `g' in org-toc to refresh?)

Great idea!  I tried to implement this like that:

`s': store a TOC configuration
`g': jump to that configuration

If the TOC has been modified inbetween, no problem, the configuration
will be back. You can even quit the TOC, work on your document, then
open the TOC again, and fetch the last stored configuration. And this
works for several Org files.  

Hope this suits your needs.

PS: Carsten (and I) would like to find a way to make this TOC buffer
looks visually more distinct than the base buffer. Any suggestion is
most welcome!

PS: Some time ago someone mentionned the need for a way to store the
state of visibility for a buffer. Well, this is not exactly what this
last function provides, but I think it's a first step to it...

-- 
Bastien

Re: org-toc.el - browsable table of contents for Org

[Renzo Been]

Bastien <bzg@altern.org> writes:

,-----
| Oke,
| 
| Org-TOC is a really nice way to navigate through
| any org-file.
| 
| As to your P.S to make the TOC buffer look
| visually more distinct from the base buffer. I
| have a couple of suggestions:
| 
| - Draw a box around the contents of the
|   TOC-buffer (like I did with this e-mail). I
|   don't know if that's possible to write via
|   e-lisp, because the TOC-buffer has to be
|   updated frequently...
| - Have the TOC get it's own face, so it can be
|   shown in a different color. But than you could
|   kind of lose the differences between headlines
|   (if headlines of more levels are shown in the
|   TOC-buffer)...
| - Use h-line to high-lite TOC-buffer lines in a
|   different color
| 
| And I also have one question:
| Is there a way to have the TOC auto-loaded with
| an org-file (through an in-file setting)?
| 
| Ciao,
| Renzo
`-----

Re: Re: org-toc.el - browsable table of contents for Org

[Bastien]

Renzo Been <swangdoodles@gmail.com> writes:

> | Org-TOC is a really nice way to navigate through
> | any org-file.

Thanks!

> | - Draw a box around the contents of the TOC-buffer (like I did with
> | this e-mail). I don't know if that's possible to write via e-lisp,
> | because the TOC-buffer has to be updated frequently...

I must acknowledge that the boxquote stuff wrapping your e-mails always
looked a bit weird to me.. I usually see this as a way to quote emails
or code examples, not to encapsulate your own prose.

I don't see any way to make boxquotes works with the TOC anyway, since
there would be too many complexity when displaying several levels at the
same time.

But I like the idea of having some kind of margin, just as linum.el does
for line numbers:

  http://stud4.tuwien.ac.at/~e0225855/linum/linum.html

What kind of information you would like to be displayed in this margin?
(Remember there is org-toc-info already, so the margin and the echo-area
should work in a complementary way.)

> | - Have the TOC get it's own face, so it can be shown in a different
> | color. But than you could kind of lose the differences between
> | headlines (if headlines of more levels are shown in the
> | TOC-buffer)...

We could have a whole new set of customizable faces for org-toc-mode, I
will consider this.

> | - Use h-line to high-lite TOC-buffer lines in a
> |   different color

I don't know "h-line"... did you mean "hl-line? I think the purpose of
global-hl-line-mode is only to highlight the current line, not several
lines.

> | And I also have one question: Is there a way to have the TOC
> | auto-loaded with an org-file (through an in-file setting)?

I tried to insert this at the end of a file:

  # Local Variables:
  # eval: (org-show-table-of-contents)
  # End:

but it requires M-x normal-mode, which I don't understand. Even by
setting both `enable-local-variables' and `enable-local-eval' to t
(which is not recommended!) ... any hint on this is welcome!

-- 
Bastien

Re: Re: org-toc.el - browsable table of contents for Org

[Carsten Dominik]

On Sep 26, 2007, at 9:06, Bastien wrote:
>
> I don't see any way to make boxquotes works with the TOC anyway, since
> there would be too many complexity when displaying several levels at 
> the
> same time.


How about changing the background color of the toc, maybe only slightly 
from the default?

- Carsten

Re: org-toc.el - browsable table of contents for Org

[Renzo Been]

Bastien <bzg@altern.org> writes:

> I must acknowledge that the boxquote stuff wrapping your e-mails always
> looked a bit weird to me.. I usually see this as a way to quote emails
> or code examples, not to encapsulate your own prose.

True, I was kind of misusing the boxquotes. I just liked the looks of them. For 
e-mailing to friends that's oke, but on a mail-list like this one it looks a 
bit confusing... Sorry for that. 

> I don't see any way to make boxquotes works with the TOC anyway, since
> there would be too many complexity when displaying several levels at the
> same time.

Agreed 

> But I like the idea of having some kind of margin, just as linum.el does
> for line numbers:
> http://stud4.tuwien.ac.at/~e0225855/linum/linum.html

Yes, I had a look at linum, and it looks like a good mechanism that can be of 
use in the TOC. If you could make such a margin, that would be great for the 
TOC... 

> What kind of information you would like to be displayed in this margin?
> (Remember there is org-toc-info already, so the margin and the echo-area
> should work in a complementary way.)

Maybe the margin could display how many sub-headings are below the heading that 
shows in the TOC? Or how many lines of text there are folded inside it? Or the 
number of TODO's that are below it? 

Or maybe it's better to keep things simple. And put no extra information in the 
margin? Just put two or three symbols (ones that do not conflict with org-mode) 
there, to make the TOC display distinguishable from the base-buffer. You could 
use a symbol from the utf-8 coding table. I've put some examples here: 

http://swangdoodles.googlepages.com/Unicodes-for-org-toc.html 

> I don't know "h-line"... did you mean "hl-line? I think the purpose of
> global-hl-line-mode is only to highlight the current line, not several
> lines.

Yes, I meant hl-line... I'm using it in my agenda-views. But your right, it 
only works on one line. 

> I tried to insert this at the end of a file:
>   # Local Variables:
>   # eval: (org-show-table-of-contents)
>   # End:

> but it requires M-x normal-mode, which I don't understand. Even by
> setting both `enable-local-variables' and `enable-local-eval' to t
> (which is not recommended!) ... any hint on this is welcome!

When I set in my .emacs:
 '(enable-local-eval t)
And at the bottom of the org-file:
 # Local Variables:
 # eval: (org-toc-show)
 # End:
What happens is that the TOC-buffer does open. But it is opened as a full view 
buffer,
not as a split screen together with the org-file

What might also be handy is to limit the size of the TOC-buffer. Right now, 
what happens when I'm in a large org-file, and use the TOC, is that it takes 
over half the screen...

Ciao,
Renzo

Re: Re: org-toc.el - browsable table of contents for Org

[Bastien]

Renzo Been <swangdoodles@gmail.com> writes:

>> But I like the idea of having some kind of margin, just as linum.el does
>> for line numbers:
>> http://stud4.tuwien.ac.at/~e0225855/linum/linum.html
>
> Yes, I had a look at linum, and it looks like a good mechanism that can be of 
> use in the TOC. If you could make such a margin, that would be great for the 
> TOC... 
>
>> What kind of information you would like to be displayed in this margin?
>> (Remember there is org-toc-info already, so the margin and the echo-area
>> should work in a complementary way.)
>
> Maybe the margin could display how many sub-headings are below the heading that 
> shows in the TOC? Or how many lines of text there are folded inside it? Or the 
> number of TODO's that are below it? 

Please check latest org-toc.el (0.9a):

  http://www.cognition.ens.fr/~guerry/u/org-toc.el

,----[ org-toc-margin-default-format ]
| The default margin format. This is overriden by any occurrence
| of #+TOC_MARGIN: in the base Org buffer.
| 
| %l stands for the heading's line number.
| %h stands for the number of headings below this heading.
| %t stands for the number of TODO items below this heading.
| 
| For example, a format like "%5l hl:%2h td:%2t | " would show:
| 
|  1456 hl: 2 td: 1 | * A headline here
| 
| - this headline is on line 1456
| - there are 2 headlines below it
| - there are 1 TODO item among these 2 headlines
| 
| Attention: using a complex margin format for big Org files could
| slow down things considerabily.
`----

> Or maybe it's better to keep things simple. And put no extra
> information in the margin?

The default for the margin is "", since I also think it's better to not
display too much information by default.

> Just put two or three symbols (ones that do not conflict with org-mode) 
> there, to make the TOC display distinguishable from the base-buffer. You could 
> use a symbol from the utf-8 coding table. I've put some examples here: 
>
> http://swangdoodles.googlepages.com/Unicodes-for-org-toc.html 

I added a new background for the TOC. Please tell me what do you think.

> What happens is that the TOC-buffer does open. But it is opened as a full view 
> buffer,
> not as a split screen together with the org-file

I will investigate, thanks.

> What might also be handy is to limit the size of the TOC-buffer. Right
> now, what happens when I'm in a large org-file, and use the TOC, is
> that it takes over half the screen...

For now I just rely on shrink-window-if-larger-than-buffer, which seems
fine to me. But If people think we should force a max size for the TOC,
let me know.

-- 
Bastien