Add ability to force-enable TOC

Add ability to force-enable TOC

[Kaushal Modi]

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

Hello,

I have use-cases where I don't like to see the headings numbered but still
want the TOC to be generated.

I have this in many of my Org files:

#+OPTIONS: num:nil H:4

But after commit bd23781[1], that has stopped working i.e. no TOC is
created because of num:nil.

Can we enforce the TOC generation using the "toc:" option. Below does not
work at the moment, but would like that to work.

#+OPTIONS: num:nil H:4 toc:4

Thanks.

[1]:
http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=bd2378161e76932103c9ef1f8343ffcc0d275007
-- 

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Kaushal Modi]

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

On Tue, Sep 19, 2017 at 10:49 AM Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> Can we enforce the TOC generation using the "toc:" option. Below does not
> work at the moment, but would like that to work.
>
> #+OPTIONS: num:nil H:4 toc:4
>

Above works after the below patch:

diff --git a/lisp/ox.el b/lisp/ox.el
index 2be77a87b33..1831432df87 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -5227,7 +5227,8 @@ Footnote sections and unnumbered headlines are
ignored."
     (org-element-map (org-element-contents scope) 'headline
       (lambda (headline)
  (unless (or (org-element-property :footnote-section-p headline)
-    (not (org-export-numbered-headline-p headline info)))
+    (and (null (plist-get info :with-toc))
+ (not (org-export-numbered-headline-p headline info))))
   (let ((level (org-export-get-relative-level headline info)))
     (and (<= level n) headline))))
       info)))

But I am pretty sure that's not the right way as the default value of
org-export-with-toc is t.
-- 

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Carsten Dominik]

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

On Tue, Sep 19, 2017 at 4:49 PM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> Hello,
>
> I have use-cases where I don't like to see the headings numbered but still
> want the TOC to be generated.
>
> I have this in many of my Org files:
>
> #+OPTIONS: num:nil H:4
>
> But after commit bd23781[1], that has stopped working i.e. no TOC is
> created because of num:nil.
>

I would see this as a bug - clearly it makes sense to have a TOC without
numbering.

Nicolas, was this an oversight, or was this change intended?

Carsten


>
> Can we enforce the TOC generation using the "toc:" option. Below does not
> work at the moment, but would like that to work.
>
> #+OPTIONS: num:nil H:4 toc:4
>
> Thanks.
>
> [1]: http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=
> bd2378161e76932103c9ef1f8343ffcc0d275007
> --
>
> Kaushal Modi
>

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

Re: Add ability to force-enable TOC

[Nicolas Goaziou]

Hello,

Carsten Dominik <dominik@uva.nl> writes:

> On Tue, Sep 19, 2017 at 4:49 PM, Kaushal Modi <kaushal.modi@gmail.com>
> wrote:
>
>> Hello,
>>
>> I have use-cases where I don't like to see the headings numbered but still
>> want the TOC to be generated.
>>
>> I have this in many of my Org files:
>>
>> #+OPTIONS: num:nil H:4
>>
>> But after commit bd23781[1], that has stopped working i.e. no TOC is
>> created because of num:nil.
>>
>
> I would see this as a bug - clearly it makes sense to have a TOC without
> numbering.
>
> Nicolas, was this an oversight, or was this change intended?

The change was intended. The idea was discussed on the ML. You may want
to check the thread.

This is on par with, e.g., what LaTeX does.

Regards,

-- 
Nicolas Goaziou

Re: Add ability to force-enable TOC

[Kaushal Modi]

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

On Tue, Sep 19, 2017 at 3:27 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> The change was intended. The idea was discussed on the ML. You may want
> to check the thread.
>
> This is on par with, e.g., what LaTeX does.
>

What would be a good way, though, to bring back that functionality? I don't
mind if I need to set extra options/variables for that.
-- 

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Nicolas Goaziou]

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

> On Tue, Sep 19, 2017 at 3:27 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> The change was intended. The idea was discussed on the ML. You may want
>> to check the thread.
>>
>> This is on par with, e.g., what LaTeX does.
>>
>
> What would be a good way, though, to bring back that functionality? I don't
> mind if I need to set extra options/variables for that.

What is exactly the feature you are missing? Your example is a special
case where _no_ heading is numbered. But we also had to deal with
situations where only _some_ headings were numbered.

In any case, this change solves two problems:

1. it makes all export back-ends consistent with TOC;

2. it allows to use, e.g., @heading instead of @unnumberedsec in Texinfo
   export. Thus, we don't need to provide a way to determine which one
   should be used.

I admit the second point is probably only convenient for the lazy me:
I don't have to find a proper way to support @heading commands in
Texinfo export anymore.

Regards,

Re: Add ability to force-enable TOC

[Kaushal Modi]

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

On Tue, Sep 19, 2017 at 3:57 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> What is exactly the feature you are missing? Your example is a special
> case where _no_ heading is numbered.


I would not consider this as a special case. It is very common for HTML
exports to not always number the headings.

Blog posts are also very common examples.. we do not have blog posts with
numbered h1/h2 headings. But for long blog posts, it often a norm to
include a TOC. Example:
https://scripter.co/notes/string-functions-nim-vs-python/

I also use the ascii exporter to export notes taken during meetings. I do
not number them, and with a long notes, TOC is helpful.

Numbered headings is more common in texinfo and latex, I believe.


> But we also had to deal with
> situations where only _some_ headings were numbered.
>
> In any case, this change solves two problems:
>
> 1. it makes all export back-ends consistent with TOC;
>

 I understand that. But would like a way to get back the earlier behavior
too.

2. it allows to use, e.g., @heading instead of @unnumberedsec in Texinfo
>    export. Thus, we don't need to provide a way to determine which one
>    should be used.
>
> I admit the second point is probably only convenient for the lazy me:
> I don't have to find a proper way to support @heading commands in
> Texinfo export anymore.
>

How about this updated patch?

diff --git a/lisp/ox.el b/lisp/ox.el
index 2be77a87b33..7b6170cb832 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -5227,7 +5227,8 @@ Footnote sections and unnumbered headlines are
ignored."
     (org-element-map (org-element-contents scope) 'headline
       (lambda (headline)
  (unless (or (org-element-property :footnote-section-p headline)
-    (not (org-export-numbered-headline-p headline info)))
+    (and (not (numberp (plist-get info :with-toc)))
+ (not (org-export-numbered-headline-p headline info))))
   (let ((level (org-export-get-relative-level headline info)))
     (and (<= level n) headline))))
       info)))


That way if the file has:

#+OPTIONS: num:nil

No TOC will be exported (even though the org-export-with-toc default is t).

But if the file has:

#+OPTIONS: num:nil toc:4

As the toc value is a number, the TOC will be exported even though num is
nil.

-- 

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Carsten Dominik]

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

On Tue, Sep 19, 2017 at 9:27 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Carsten Dominik <dominik@uva.nl> writes:
>
> > On Tue, Sep 19, 2017 at 4:49 PM, Kaushal Modi <kaushal.modi@gmail.com>
> > wrote:
> >
> >> Hello,
> >>
> >> I have use-cases where I don't like to see the headings numbered but
> still
> >> want the TOC to be generated.
> >>
> >> I have this in many of my Org files:
> >>
> >> #+OPTIONS: num:nil H:4
> >>
> >> But after commit bd23781[1], that has stopped working i.e. no TOC is
> >> created because of num:nil.
> >>
> >
> > I would see this as a bug - clearly it makes sense to have a TOC without
> > numbering.
> >
> > Nicolas, was this an oversight, or was this change intended?
>
> The change was intended. The idea was discussed on the ML. You may want
> to check the thread.
>
> This is on par with, e.g., what LaTeX does.
>

That may be so, but I find that unfortunate.  I am really using this
feature often.

I will go back and take a look at this thread.  Can someone tell me what
the subject line of that thread was?

Carsten


>
> Regards,
>
> --
> Nicolas Goaziou
>

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

Re: Add ability to force-enable TOC

[Rasmus]

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

> On Tue, Sep 19, 2017 at 3:27 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> The change was intended. The idea was discussed on the ML. You may want
>> to check the thread.
>>
>> This is on par with, e.g., what LaTeX does.
>>
>
> What would be a good way, though, to bring back that functionality? I don't
> mind if I need to set extra options/variables for that.

In the case of LaTeX you could do:

    #+latex_header: \setcounter{secnumdepth}{0}
    #+options: toc:3

For what it’s worth, I don’t think the new behavior is correct, seeing
Kaushal’s example.

The option "num" touches secnumdepth (in ox-latex).  But setting that does
not imply that all headings should be constructed with their starred
variant (e.g. "\section*{.}").

IMO, this behavior should be reverted in maint as it would be nice to
include 9.1 in the next version of Emacs.

Rasmus

-- 
This message is brought to you by the department of redundant departments

Re: Add ability to force-enable TOC

[Rasmus]

Carsten Dominik <dominik@uva.nl> writes:

> That may be so, but I find that unfortunate.  I am really using this
> feature often.
>
> I will go back and take a look at this thread.  Can someone tell me what
> the subject line of that thread was?

I think it’s this one.

    Subject: setting local variables
    Date: Thu, 07 Sep 2017 14:48:03 +0200 (and earlier)

Rasmus

-- 
May the Force be with you

Re: Add ability to force-enable TOC

[Kaushal Modi]

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

On Wed, Sep 20, 2017, 4:14 AM Carsten Dominik <dominik@uva.nl> wrote:

>
> I will go back and take a look at this thread.  Can someone tell me what
> the subject line of that thread was?
>

http://lists.gnu.org/archive/html/emacs-orgmode/2017-09/msg00157.html
-- 

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Nicolas Goaziou]

Hello,

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

> On Tue, Sep 19, 2017 at 3:57 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> What is exactly the feature you are missing? Your example is a special
>> case where _no_ heading is numbered.
>
>
> I would not consider this as a special case. It is very common for HTML
> exports to not always number the headings.

I didn't say it was an unusual case. I said it didn't cover all the
use-cases. Maybe you are really needing a subset of the initial feature.
IOW, do mixed numbered/unnumbered headings make sense in TOC?

>> 1. it makes all export back-ends consistent with TOC;
>>
>
>  I understand that. But would like a way to get back the earlier behavior
> too.

Then there is the other way around: how do we tell LaTeX to include both
numbered and unnumbered headings?

And: how do we distinguish @unnumberedsec from @heading in Texinfo?

> That way if the file has:
>
> #+OPTIONS: num:nil
>
> No TOC will be exported (even though the org-export-with-toc default is t).
>
> But if the file has:
>
> #+OPTIONS: num:nil toc:4
>
> As the toc value is a number, the TOC will be exported even though num is
> nil.

AFAICT, this doesn't solve any of the two concerns. What we can do for
"num:nil toc:4" can be done for "num:nil" alone.

Regards,

Re: Add ability to force-enable TOC

[Kaushal Modi]

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

On Wed, Sep 20, 2017, 6:25 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> I didn't say it was an unusual case. I said it didn't cover all the
> use-cases. Maybe you are really needing a subset of the initial feature.
>

Understood.

IOW, do mixed numbered/unnumbered headings make sense in TOC?
>

Correct. That does not make sense to me. That is not my use case.

>> 1. it makes all export back-ends consistent with TOC;
> >>
> >
> >  I understand that. But would like a way to get back the earlier behavior
> > too.
>
> Then there is the other way around: how do we tell LaTeX to include both
> numbered and unnumbered headings?
>

I see your point.

AFAICT, this doesn't solve any of the two concerns. What we can do for
> "num:nil toc:4" can be done for "num:nil" alone.
>

That might work.. treat num:nil differently than num:0

So here's the summary as per my understanding.

Currently we support these:

1. Don't allow a mix of numbered and unnumbered headings in TOC. If any
heading is unnumbered using the UNNUMBERED property, remove it from the
TOC.

2. If we globally unnumber headings beyond a certain level by doing
something like num:3, don't show headings beyond that level in the TOC. So
num:0 wouldn't number any heading and also not generate the TOC.

Now the 3rd use case (mine):

3. Unnumber all headings, but still keep them in TOC.

So allow this 3rd use case when, may be, we have num:nil and not num:0?

WDYT?

@Carsten: Does this satisfy your use case too?

> --

Kaushal Modi

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

Re: Add ability to force-enable TOC

[Rasmus]

Rasmus <rasmus@gmx.us> writes:

> IMO, this behavior should be reverted in maint as it would be nice to
> include 9.1 in the next version of Emacs.

I misunderstood the initial report.  Ignore the above.

I don’t understand why, in ox-latex, "num" sets both
"\setcounter{secnumdepth}{.}"  and switches to "section*" and friends.
Setting "\setcounter{secnumdepth}{.}" is enough to get unnumbered
headlines...

Rasmus

-- 
C is for Cookie

Re: Add ability to force-enable TOC

[Matt Lundin]

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

> On Wed, Sep 20, 2017, 6:25 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>     I didn't say it was an unusual case. I said it didn't cover all
>     the use-cases. Maybe you are really needing a subset of the
>     initial feature.
>
> Understood. 
>
>     IOW, do mixed numbered/unnumbered headings make sense in TOC?
>
> Correct. That does not make sense to me. That is not my use case. 

I support the use case of unnumbered table of contents.

In addition (although this is probably too much of a corner case to
support officially in Org Mode), it is common in the U.S. to use a mix
of numbered and unnumbered headings in books. One accomplishes this in
LaTeX with the following:

--8<---------------cut here---------------start------------->8---
\tableofcontents

\chapter*{Introduction}
\addcontentsline{toc}{chapter}{Introduction}

\chapter{A Chapter}

\chapter{Another Chapter}

\chapter*{Conclusion}
\addcontentsline{toc}{chapter}{Introduction}
--8<---------------cut here---------------end--------------->8---

The resulting Table of Contents looks like this...

Introduction            3
1 A Chapter             5
2 Another Chapter       7
Conclusion              9

Best,
Matt