From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Org Mode List <emacs-orgmode@gnu.org>
Subject: [RFC] Exclude headlines from TOC, take 2
Date: Sat, 07 Oct 2017 16:16:27 +0200 [thread overview]
Message-ID: <87zi93gi10.fsf@nicolasgoaziou.fr> (raw)
[-- 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
next reply other threads:[~2017-10-07 14:16 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-07 14:16 Nicolas Goaziou [this message]
2017-10-15 19:40 ` [RFC] Exclude headlines from TOC, take 2 Nicolas Goaziou
2017-10-16 16:35 ` Kaushal Modi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87zi93gi10.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).