* org-toc.el - browsable table of contents for Org
@ 2007-09-23 14:38 Bastien
2007-09-24 9:31 ` Levin
0 siblings, 1 reply; 8+ messages in thread
From: Bastien @ 2007-09-23 14:38 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: org-toc.el - browsable table of contents for Org
2007-09-23 14:38 org-toc.el - browsable table of contents for Org Bastien
@ 2007-09-24 9:31 ` Levin
2007-09-24 23:06 ` Bastien
0 siblings, 1 reply; 8+ messages in thread
From: Levin @ 2007-09-24 9:31 UTC (permalink / raw)
To: emacs-orgmode
> 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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: org-toc.el - browsable table of contents for Org
2007-09-24 9:31 ` Levin
@ 2007-09-24 23:06 ` Bastien
2007-09-26 14:11 ` Renzo Been
0 siblings, 1 reply; 8+ messages in thread
From: Bastien @ 2007-09-24 23:06 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: org-toc.el - browsable table of contents for Org
2007-09-24 23:06 ` Bastien
@ 2007-09-26 14:11 ` Renzo Been
2007-09-26 16:06 ` Bastien
0 siblings, 1 reply; 8+ messages in thread
From: Renzo Been @ 2007-09-26 14:11 UTC (permalink / raw)
To: emacs-orgmode
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
`-----
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Re: org-toc.el - browsable table of contents for Org
2007-09-26 14:11 ` Renzo Been
@ 2007-09-26 16:06 ` Bastien
2007-09-26 16:22 ` Carsten Dominik
2007-09-29 7:37 ` Renzo Been
0 siblings, 2 replies; 8+ messages in thread
From: Bastien @ 2007-09-26 16:06 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Re: org-toc.el - browsable table of contents for Org
2007-09-26 16:06 ` Bastien
@ 2007-09-26 16:22 ` Carsten Dominik
2007-09-29 7:37 ` Renzo Been
1 sibling, 0 replies; 8+ messages in thread
From: Carsten Dominik @ 2007-09-26 16:22 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: org-toc.el - browsable table of contents for Org
2007-09-26 16:06 ` Bastien
2007-09-26 16:22 ` Carsten Dominik
@ 2007-09-29 7:37 ` Renzo Been
2007-09-29 13:21 ` Bastien
1 sibling, 1 reply; 8+ messages in thread
From: Renzo Been @ 2007-09-29 7:37 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: Re: org-toc.el - browsable table of contents for Org
2007-09-29 7:37 ` Renzo Been
@ 2007-09-29 13:21 ` Bastien
0 siblings, 0 replies; 8+ messages in thread
From: Bastien @ 2007-09-29 13:21 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2007-09-29 13:21 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2007-09-23 14:38 org-toc.el - browsable table of contents for Org Bastien
2007-09-24 9:31 ` Levin
2007-09-24 23:06 ` Bastien
2007-09-26 14:11 ` Renzo Been
2007-09-26 16:06 ` Bastien
2007-09-26 16:22 ` Carsten Dominik
2007-09-29 7:37 ` Renzo Been
2007-09-29 13:21 ` Bastien
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).