Don't include headings above the TOC heading

[alphapapa]

For example, with this structure:

* Title 
Introduction
** Contents
** First topic
** Second topic

We don't want it to look like this with a TOC:

* Title
Introduction
** Contents 
- Title 
  - Contents 
  - First topic
  - Second topic
** First topic
** Second topic

Because we don't want the title and TOC listed in the TOC. Instead we want it to look like this:

* Title 
Introduction
** Contents
- First topic
- Second topic
** First topic
** Second topic

The existing code works if the TOC is at the same level as the title node, but this PR fixes the given examples.

Thanks!

[alphapapa]

The tests are failing with Emacs 24.3.1 but working with 25.2.

24.3 is four years old, are you intentionally testing with it? :)

Thanks.

[snosov1]

Hey!

And I thought you'd leave it after the :noexport: merge! =)

Anyway, I really think that the existing functionality is good enough this time. I can't imagine any good reason why you would strongly prefer

* Title 
Introduction
** Contents
** First topic
** Second topic

over

* Title  :noexport:
Introduction
* Contents :TOC:
* First topic
* Second topic

Please, let me know your thoughts about this.

24.3 is four years old, are you intentionally testing with it? :)

Well, it's the "default" version on the travis' version of Ubuntu (which, I believe, is 12.04 LTS). I guess, there's merit in testing it. And, anyway, there shouldn't be any reason for the package to not work on older versions, since it's, practically, just simple text processing.

[alphapapa]

And I thought you'd leave it after the :noexport: merge! =)

Well, I keep discovering ways to make this great package better. :)

Anyway, I really think that the existing functionality is good enough this time. I can't imagine any good reason why you would strongly prefer

Because I want a top-level heading that the rest of the document is beneath. That's the most logical hierarchy to me in this case. It's not a big deal, I just don't want all of the headings after the first to have the same big font size. ;)

Well, it's the "default" version on the travis' version of Ubuntu (which, I believe, is 12.04 LTS). I guess, there's merit in testing it. And, anyway, there shouldn't be any reason for the package to not work on older versions, since it's, practically, just simple text processing.

12.04 is five and a half years old by now, though. It should even be unsupported by Canonical by now, as LTS are (or were) 5 years for server and 3 for desktop. I mean, it's up to you, but I don't think anyone's running this package on Ubuntu 12.04. Travis is just a bit outdated now. The "canonical" way to test Emacs packages with Travis is to use the EVM repo, which provides images for specific versions. Requiring it to work on Emacs 24.3 deprives us of useful things added to later versions, like seq.el, when-let, etc.

Well, if you don't want to merge this, that's ok, I can still use it on my own, and maybe fork it to make it suit my needs better. It's a good foundation. :)

[snosov1]

I just don't want all of the headings after the first to have the same big font size. ;)

I tinkered with it a bit and I can kind of see the logic, but it still looks like you're trying to do things differently from what's intended. Do you know that you can have a #+TITLE: Title line in the beginning of the file to declare, well, a title? =)

It looks like you should be doing that instead of messing with the hierarchy. Also, if you do this - you're free to make all the other headings to be 2-star (or 3-start or whatever) to reduce their size. And the existing functionality will work seamlessly.

12.04 is five and a half years old by now, though. It should even be unsupported by Canonical by now, as LTS are (or were) 5 years for server and 3 for desktop.

Believe it or not, I still have 12.04 installed on my laptop. And I don't really see a reason to switch =) And, again, Travis uses it, so I think I'll keep it for now.

Besides, one of the reasons I use Emacs is packages like dired and calc that were written tens of years ago and still work today surprisingly well - even though they don't use all the new and fancy features. I kind of find it fascinating - it means the software was well designed and well implemented - vast majority of the SW around becomes obsolete too quickly.

The "canonical" way to test Emacs packages with Travis is to use the EVM repo, which provides images for specific versions.

Can you, please, point me to a "sample" .travis.yml that does this? I recall myself fixing the config not so long ago and not being too happy about it.

Well, if you don't want to merge this, that's ok, I can still use it on my own, and maybe fork it to make it suit my needs better. It's a good foundation. :)

Yeah, I think I'll pass on this one. But, please, consider my #+TITLE: Title suggestion - maybe it'll work good enough for you. Besides, I don't want to lose such a dedicated user to a fork =)

[alphapapa]

Hi again,

Yes, I know about the title header, but 1) I just generally don't like to use it, and 2) AFAIK they don't render on GitHub as a top-level heading. I want the top-level heading to be the document root, and the contents to be a child node.

For the Travis config, you can look at one I use here, which I modeled on...I forget, but I think it's in the commit log or something (it was probably the MELPA one): https://github.com/alphapapa/helm-org-rifle/blob/master/.travis.yml

Besides, I don't want to lose such a dedicated user to a fork =)

Aww. ;) Well, last night I put together a rough package that does most of what I need. I...uh...learned some things about processing...irregular?...tree structures in elisp...it was rough. haha But learning is good. I tried to use as many built-in Org functions as I could, and process the document tree as a structure, but org-element-map and org-map-entries don't seem to be ideal for this. Or maybe they are and I just haven't figured out how yet. Anyway, if you're curious, you can find it here: http://github.com/alphapapa/org-make-toc I don't know how far I will go with it, but at least it does serve this use-case for now. I also decided to use properties instead of tags to control whether entries are ignored, which one is the TOC, etc.

[snosov1]

https://github.com/alphapapa/helm-org-rifle/blob/master/.travis.yml

Thanks! Seems like the right way to go. Will, probably, switch to this EVM stuff when I'll be fixing the config next time (FDD - Failure Driven Development)

http://github.com/alphapapa/org-make-toc

Looks cool! =) I guess toc-org could look like this if I knew a bit more about org or elisp in general. BTW, do you know about the markdown-toc package? It does the similar thing for markdown. I don't really use it myself, but I find that the code is in much better shape if you consider the number of "fancy features" and "internal functions" to be a target function =)

[alphapapa]

LOL, FDD, I like it! :)

Thanks for pointing me at markdown-toc, that code looks really high quality. I see that he uses imenu to get the document structure. I almost tried that, but I decided to go with the structure returned by the Org document parser. But it might be simpler to go with a flat list and a level number...

[alphapapa]

FYI, I finally put org-make-toc on MELPA. A little friendly competition. ;) toc-org does have a few more features, but org-make-toc has some flexibility in other ways.

[snosov1]

Aargh! I assume that I won't be receiving any more contributions from you, which is a tremendous loss! =)

Out of curiosity - what was the critical feature that you've missed?

[alphapapa]

Well, I wanted more flexibility for one thing. There was another feature request I posted about having the TOC heading as a child of the top-level heading, which is how I structure most of my readmes (for the font size if nothing else)...oh no, wait, that was this issue, but I forgot to scroll up, LOL. I also wanted more control over excluding entries, and doing it with tags starts to feel clumsy to me.

I don't know if there was a single critical feature. Part of the reason I made it was for the fun of doing it. I'd been using it for quite a while before I recently cleaned it up for MELPA, so you haven't exactly just lost a user, haha. ;) But toc-org served me very well, and I thank you for it! :)

[snosov1]

I don't know if there was a single critical feature. Part of the reason I made it was for the fun of doing it.

Yeah, that's what I thought =)

Thanks for all the conversations we had around this topic. I wish I'll be able to switch to your package one day, so that I don't have to maintain this one anymore ;)

[alphapapa]

I enjoyed them! I'd be happy to collaborate with you on it, so feel free to send any ideas or code you may come up with. :)