[RFC] Exclude headlines from TOC, take 2

[RFC] Exclude headlines from TOC, take 2

[Nicolas Goaziou]

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

Hello,

Here is another take on the possibility to exclude headlines from the
table of contents.

Last attempt was rejected because users need to include /unnumbered/
headlines in the TOC. Point taken. However, I don't think it makes sense
to exclude /numbered/ headlines from the TOC. Hence, I propose to
exclude any headline with an UNNUMBERED property set to "notoc".

So basically,

  - only unnumbered headlines can be excluded
  - we do not introduce another property

Here is an example document, with the generated TOC in plain text
export:

--8<---------------cut here---------------start------------->8---
#+options: toc:t

* H1
:PROPERTIES:
:UNNUMBERED: t
:END:

* H2

** H2.1

** H2.2
:PROPERTIES:
:UNNUMBERED: notoc
:END:

*** H221

** H2.3

* H3
:PROPERTIES:
:UNNUMBERED: notoc
:END:


* H4

* H5
:PROPERTIES:
:UNNUMBERED: t
:END:
--8<---------------cut here---------------end--------------->8---

gives

  H1
  1 H2
  .. 1.1 H2.1
  .. 1.2 H2.3
  2 H4
  H5


I attach a possible implementation, with documentation and tests. Note
that this doesn't work with LaTeX export back-end, which still dutifully
ignores any unnumbered headline. Patches welcome to improve this.

WDYT?


Regards,

-- 
Nicolas Goaziou                                                0x80A93738

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Implement-notoc-UNNUMBERED-value.patch --]
[-- Type: text/x-diff, Size: 5212 bytes --]

From e6c6534997e03d4817a95c6f57f9c0421810c50b Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Sat, 7 Oct 2017 16:03:17 +0200
Subject: [PATCH] ox: Implement "notoc" UNNUMBERED value

* lisp/ox.el (org-export-collect-headlines): Exclude headlines with
  UNNUMBERED property set to "notoc".

* doc/org.texi (Export settings):
(Table of contents): Document new value.

* testing/lisp/test-ox.el (test-org-export/collect-headlines): Add
  test.
---
 doc/org.texi            | 24 +++++++++++++++++++++---
 etc/ORG-NEWS            |  3 +++
 lisp/ox.el              | 14 +++++++++-----
 testing/lisp/test-ox.el | 15 +++++++++++++++
 4 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index fd26d9790..146699b11 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10813,7 +10813,9 @@ Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
 Toggle section-numbers (@code{org-export-with-section-numbers}).  When set to
 number @samp{n}, Org numbers only those headlines at level @samp{n} or above.
 Set @code{UNNUMBERED} property to non-@code{nil} to disable numbering of
-heading and subheadings entirely.
+heading and subheadings entirely.  Moreover, when the value is @samp{notoc}
+the headline, and all its children, do not appear in the table of contents
+either (@pxref{Table of contents}.
 
 @item p:
 @vindex org-export-with-planning
@@ -10911,6 +10913,22 @@ keyword:
 #+OPTIONS: toc:nil        @r{no default TOC at all}
 @end example
 
+@cindex excluding entries from table of contents
+@cindex table of contents, exclude entries
+Org includes both numbered and unnumbered headlines in the table of
+contents@footnote{At the moment, some export back-ends, notably @LaTeX{}, do
+not obey this specification.  They simply exclude every unnumbered headline
+from the table of contents.}.  If you need to exclude unnumbered headlines,
+along with all their children, set their @samp{UNNUMBERED} property to
+@samp{notoc} value.
+
+@example
+* Subtree not numbered, not in table of contents either
+  :PROPERTIES:
+  :UNNUMBERED: notoc
+  :END:
+@end example
+
 @cindex #+TOC
 Org normally inserts the table of contents directly before the first headline
 of the file.  To move the table of contents to a different location, first
@@ -10935,8 +10953,8 @@ compatibility issues, @code{titletoc} has to be loaded @emph{before}
 variable.
 
 @example
-* Section #+TOC: headlines 1 local @r{insert local TOC, with direct children
-only}
+* Section
+#+TOC: headlines 1 local @r{insert local TOC, with direct children only}
 @end example
 
 Use the @code{TOC} keyword to generate list of tables (resp.@: all listings)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 53d604b8c..86c253d9c 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -26,6 +26,9 @@ document, use =shrink= value instead, or in addition to align:
 #+END_EXAMPLE
 
 ** New features
+*** Exclude unnumbered headlines from table of contents
+Set their =UNNUMBERED= property to the special =notoc= value.  See
+manual for details.
 *** ~org-archive~ functions update status cookies
 
 Archiving headers through ~org-archive-subtree~ and
diff --git a/lisp/ox.el b/lisp/ox.el
index 4d3d7afb9..cba254d6f 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -5223,12 +5223,16 @@ Footnote sections are ignored."
 	 (n (if (not (wholenump n)) limit
 	      (min (if (eq (org-element-type scope) 'org-data) n
 		     (+ (org-export-get-relative-level scope info) n))
-		   limit))))
+		   limit)))
+	 (skipped nil))
     (org-element-map (org-element-contents scope) 'headline
-      (lambda (headline)
-	(unless (org-element-property :footnote-section-p headline)
-	  (let ((level (org-export-get-relative-level headline info)))
-	    (and (<= level n) headline))))
+      (lambda (h)
+	(if (or (org-element-property :footnote-section-p h)
+		(equal "notoc" (org-element-property :UNNUMBERED h))
+		(memq (org-element-property :parent h) skipped)
+		(< n (org-export-get-relative-level h info)))
+	    (progn (push h skipped) nil)
+	  h))
       info)))
 
 (defun org-export-collect-elements (type info &optional predicate)
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 46ef51bab..cbfee4c8c 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -4314,6 +4314,21 @@ Another text. (ref:text)
 	    (org-test-with-parsed-data "* H1\n** Footnotes"
 	      (mapcar (lambda (h) (org-element-property :raw-value h))
 		      (org-export-collect-headlines info))))))
+  ;; Do not collect headlines with UNNUMBERED property set to "notoc".
+  ;; Headlines with another value for the property are still
+  ;; collected.
+  (should
+   (equal '("H1")
+	  (org-test-with-parsed-data
+	      "* H1\n* H2\n:PROPERTIES:\n:UNNUMBERED: notoc\n:END:"
+	    (mapcar (lambda (h) (org-element-property :raw-value h))
+		    (org-export-collect-headlines info)))))
+  (should
+   (equal '("H1" "H2")
+	  (org-test-with-parsed-data
+	      "* H1\n* H2\n:PROPERTIES:\n:UNNUMBERED: t\n:END:"
+	    (mapcar (lambda (h) (org-element-property :raw-value h))
+		    (org-export-collect-headlines info)))))
   ;; Collect headlines locally.
   (should
    (equal '("H2" "H3")
-- 
2.14.1

Re: [RFC] Exclude headlines from TOC, take 2

[Nicolas Goaziou]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Here is another take on the possibility to exclude headlines from the
> table of contents.
>
> Last attempt was rejected because users need to include /unnumbered/
> headlines in the TOC. Point taken. However, I don't think it makes sense
> to exclude /numbered/ headlines from the TOC. Hence, I propose to
> exclude any headline with an UNNUMBERED property set to "notoc".
>
> So basically,
>
>   - only unnumbered headlines can be excluded
>   - we do not introduce another property

[...]

> I attach a possible implementation, with documentation and tests. Note
> that this doesn't work with LaTeX export back-end, which still dutifully
> ignores any unnumbered headline. Patches welcome to improve this.

Pushed.

Re: [RFC] Exclude headlines from TOC, take 2

[Kaushal Modi]

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

On Sun, Oct 15, 2017 at 3:41 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
> > I attach a possible implementation, with documentation and tests. Note
> > that this doesn't work with LaTeX export back-end, which still dutifully
> > ignores any unnumbered headline. Patches welcome to improve this.
>
> Pushed.
>

Works great! Thank you!

My brief test for C-c C-e h o

#+TITLE: Test for new UNNUMBERED notoc feature

* Org version
=master= branch as of <2017-10-16 Mon>
-
http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=9b13e44ad795792afabb0623b58653bbf35bf040
* This heading will not be numbered, but will be present in TOC
:PROPERTIES:
:UNNUMBERED: t
:END:
Something
** Sub heading A
* This heading will not be numbered, and also will be absent in TOC
:PROPERTIES:
:UNNUMBERED: notoc
:END:
Something
** Sub heading B
* Regular heading
Once again this is a regular heading and will appear numbered, and in the
TOC too.
** Sub heading C

-- 

Kaushal Modi

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