[O] [RFC] Exclude headlines from TOC, take 2

[Nicolas Goaziou]

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

>From e6c6534997e03d4817a95c6f57f9c0421810c50b Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <address@hidden>
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 address@hidden 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
 
address@hidden excluding entries from table of contents
address@hidden table of contents, exclude entries
+Org includes both numbered and unnumbered headlines in the table of
address@hidden 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
address@hidden value.
+
address@hidden
+* Subtree not numbered, not in table of contents either
+  :PROPERTIES:
+  :UNNUMBERED: notoc
+  :END:
address@hidden 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