Mea culpa.. attached...
/PA
On Wed, 19 Feb 2025 at 07:22, Pedro Andres Aranda Gutierrez <
paag...@gmail.com> wrote:
> Hi Ihor,
>
> I'll dive again in my Outbox to check, but I'm pretty sure I sent you what
> I consider is now the last version, consolidated as a unified patch.
> It has all comments regarding the documentation and a reworked LISP
> implementation which was prompted some comments of yours. It passes tests,
> etc.
>
> Best, /P.A.
>
> On Tue, 18 Feb 2025 at 19:41, Ihor Radchenko <yanta...@posteo.net> wrote:
>
>> Pedro Andres Aranda Gutierrez <paag...@gmail.com> writes:
>>
>> > OK, great. But there's also the patch for the table of contents
>> waiting...
>> > and we wanted to give this idea another approach to
>> > code once and use it both to export latex and beamer. I'd appreciate we
>> do
>> > this after we have sorted out the table of contents.
>>
>> In my book, I am waiting for you to submit the next version of the
>> TOC patch. Just double-checking.
>>
>> --
>> Ihor Radchenko // yantar92,
>> Org mode maintainer,
>> Learn more about Org mode at <https://orgmode.org/>.
>> Support Org development at <https://liberapay.com/org-mode>,
>> or support my work at <https://liberapay.com/yantar92>
>>
>
>
> --
> Fragen sind nicht da, um beantwortet zu werden,
> Fragen sind da um gestellt zu werden
> Georg Kreisler
>
> Headaches with a Juju log:
> unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
> a leader-deposed hook here, but we can't yet
> Year 1 of the New Koprocracy
>
>
--
Fragen sind nicht da, um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler
Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should run
a leader-deposed hook here, but we can't yet
Year 1 of the New Koprocracy
From f22f8ad7f67c343e8685456f90ec830d2dccf01c Mon Sep 17 00:00:00 2001
From: "Pedro A. Aranda" <paag...@gmail.com>
Date: Wed, 12 Feb 2025 07:27:27 +0100
Subject: [PATCH] New combined patch for ToC handling
---
doc/org-manual.org | 41 +++++++++++-
etc/ORG-NEWS | 15 +++++
lisp/ox-latex.el | 93 +++++++++++++++++++++------
testing/lisp/test-ox-latex.el | 115 ++++++++++++++++++++++++++++++++++
4 files changed, 242 insertions(+), 22 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 65a1185d1..2edb74986 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14852,6 +14852,41 @@ some text in German...
\end{foreigndisplayquote}
#+end_example
+*** Controlling the way the [[*Table of Contents]] is generated
+#+cindex: LaTeX ToC export
+
+When exporting your document to LaTeX, only numbered sections will be
+included. This is closer to LaTeX and different to how other exporters
+work. If you need an unnumbered section to appear in the table of
+contents, use the property =UNNUMBERED= and set it to =toc=:
+
+#+begin_example
+:PROPERTIES:
+:UNNUMBERED: toc
+:END:
+#+end_example
+
+#+cindex: LaTeX ToC export a la ~org~
+#+cindex: @samp{org-latex-toc-include-unnumbered-style}
+If you want the LaTeX exporter to behave like other exporters,
+customise the variable ~org-latex-toc-include-unnumbered-style~ and
+set it to ~t~:
+
+#+begin_example
+(setq org-latex-toc-include-unnumbered-style t)
+#+end_example
+
+or add this setting in the local variables.
+
+In this case, unnumbered sections will be included in the table of
+contents, unless you set the =UNNUMBERED= property to ~notoc~:
+
+#+begin_example
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+#+end_example
+
** Markdown Export
:PROPERTIES:
:DESCRIPTION: Exporting to Markdown.
@@ -23509,8 +23544,10 @@ Beamer---, the =org-latex-package-alist= variable needs further
configuration. See [[LaTeX specific export settings]].
[fn:43] At the moment, some export backends do not obey this
-specification. For example, LaTeX export excludes every unnumbered
-headline from the table of contents.
+specification. For example, LaTeX export excludes by default
+every unnumbered headline from the table of contents, unless you set
+the custom variable =org-latex-toc-include-unnumbered-style= to =t= or add
+=:UNNUMBERED: toc= to the section's properties.
[fn:44] Note that ~org-link-search-must-match-exact-headline~ is
locally bound to non-~nil~. Therefore, ~org-link-search~ only matches
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index cb2c16da8..c14f7fc72 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -295,6 +295,21 @@ slide to specific animation steps.
This text will be displayed on animation step 2 and later.
#+END_SRC
+*** ox-latex: Table of contents generation has been fixed and augmented
+
+The LaTeX exporter differs from other exporters in that it *does not*
+export unnumbered sections by default.
+
+The LaTeX exporter will use the new property =:UNNUMBERED: toc= to
+include unnumbered sections in the table of contents.
+
+Additionally, a new custom variable
+~org-latex-toc-include-unnumbered-style~ has been introduced. It
+enables including unnumbered sections in the ToC aligned with the
+behaviour of other exporters. In this case, to exclude a section from
+the table of contents, mark it as =:UNNUMBERED: notoc= in its
+properties.
+
** New functions and changes in function arguments
# This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index bc31df6f5..326a65167 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -643,7 +643,8 @@ precedence over this variable."
:version "26.1"
:package-version '(Org . "8.3")
:type '(choice (const :tag "No template" nil)
- (string :tag "Format string")))
+ (string :tag "Format string"))
+ :safe #'string-or-null-p)
;;;; Headline
@@ -675,6 +676,7 @@ command like \"\\sidenote{%s%s}\" that you want to use.
The value will be passed as an argument to `format' as the following
(format org-latex-default-footnote-command
footnote-description footnote-label)"
+
:group 'org-export-latex
:package-version '(Org . "9.7")
:type 'string)
@@ -1537,6 +1539,18 @@ calling `org-latex-compile'."
(string :tag "Message"))))
+(defcustom org-latex-toc-include-unnumbered-style nil
+ "Set this variable to true to include unnumbered headings in the
+table of contents as other exporters do.
+
+The default behaviour is to include numbered headings only.
+To include an unnumbered heading, set the `:UNNUMBERED:'
+property to `toc'"
+ :group 'org-export-latex
+ :package-version '(Org . "9.8")
+ :type 'boolean
+ :safe #'booleanp)
+
;;; Internal Functions
@@ -2275,6 +2289,12 @@ holding contextual information."
(unless (org-element-property :footnote-section-p headline)
(let* ((class (plist-get info :latex-class))
(level (org-export-get-relative-level headline info))
+ ;; "LaTeX TOC handling"
+ ;; :unnumbered: toc will add the heading to the ToC
+ ;; "Org TOC handling"
+ ;; :unnumbered: notoc to suppress heading from the ToC
+ ;; else include all headings (including unnumbered) like other modes
+ (unnumbered-type (org-export-get-node-property :UNNUMBERED headline t))
(numberedp (org-export-numbered-headline-p headline info))
(class-sectioning (assoc class (plist-get info :latex-classes)))
;; Section formatting will set two placeholders: one for
@@ -2401,25 +2421,58 @@ holding contextual information."
(string-match-p "\\<local\\>" v)
(format "\\stopcontents[level-%d]" level)))))
info t)))))
- (if (and (or (and opt-title (not (equal opt-title full-text)))
- ;; Heading contains footnotes. Add optional title
- ;; version without footnotes to avoid footnotes in
- ;; TOC/footers.
- (and (not (equal full-text-no-footnote full-text))
- (setq opt-title full-text-no-footnote)))
- (string-match "\\`\\\\\\(.+?\\){" section-fmt))
- (format (replace-match "\\1[%s]" nil nil section-fmt 1)
- ;; Replace square brackets with parenthesis
- ;; since square brackets are not supported in
- ;; optional arguments.
- (replace-regexp-in-string
- "\\[" "(" (replace-regexp-in-string "\\]" ")" opt-title))
- full-text
- (concat headline-label pre-blanks contents))
- ;; Impossible to add an alternative heading. Fallback to
- ;; regular sectioning format string.
- (format section-fmt full-text
- (concat headline-label pre-blanks contents))))))))
+ ;; When do we need an alternative heading?
+ ;; 1. On numbered section with footnotes in title or alt_title
+ ;; 2. On an unnumbered section if :UNNUMBERED: allows it regardless of footnotes
+ ;; This applies to anything that may go into the ToC.
+ ;; Specifically for paragraphs, see first answer of
+ ;; https://tex.stackexchange.com/questions/288072/footnotes-within-paragraph
+ (let ((need-alternative (string-match "\\`\\\\\\(.+?\\){" section-fmt))
+ (section-kw (match-string 1 section-fmt)))
+ (when need-alternative
+ (if (string-suffix-p "*" section-kw)
+ (progn ;; unnumbered sections
+ ;; Then we need to obey what the :UNNUMBERED: property says
+ (if org-latex-toc-include-unnumbered-style ;; legacy or new behavior ?
+ ;; new behavior (á la org)
+ (when (string= unnumbered-type "notoc")
+ (setq need-alternative nil))
+ ;; legacy behavior (á la LaTeX)
+ (unless (string= unnumbered-type "toc")
+ (setq need-alternative nil))))
+ ;; numbered sections
+ (if (and (equal full-text full-text-no-footnote) ;; no footnotes
+ (equal full-text opt-title)) ;; same alternative title
+ (setq need-alternative nil))))
+ ;; In all cases
+ ;; Get rid of the footnotes in opt-title
+ (unless (equal full-text-no-footnote full-text)
+ (setq opt-title full-text-no-footnote))
+ (if need-alternative
+ (let ((new-format section-fmt)
+ (new-extra "")) ;; put the addcontentsline here
+ (if (string-suffix-p "*" section-kw)
+ ;; Subsection that needs alternative title:
+ ;; Keep section format, use \\addcontentsline
+ (setq new-extra (format "\\addcontentsline{toc}{%s}{%s}\n"
+ (string-remove-suffix "*" section-kw)
+ opt-title))
+ ;; section... we need the brackets
+ (let*
+ ;; Replace square brackets with parenthesis
+ ;; since square brackets are not supported in
+ ;; optional arguments.
+ ((un-bracketed-alt (replace-regexp-in-string
+ "\\[" "(" (replace-regexp-in-string "\\]" ")" opt-title)))
+ (replacement-re (concat "\\1[" un-bracketed-alt "]")))
+ (setq new-format (replace-match replacement-re nil nil section-fmt 1))))
+ (format new-format
+ full-text
+ (concat headline-label new-extra pre-blanks contents)))
+ ;; Impossible to add an alternative heading. Fallback to
+ ;; regular sectioning format string.
+ (format section-fmt full-text
+ (concat headline-label pre-blanks contents)))))))))
(defun org-latex-format-headline-default-function
(todo _todo-type priority text tags _info)
diff --git a/testing/lisp/test-ox-latex.el b/testing/lisp/test-ox-latex.el
index b75921ae7..90f447eea 100644
--- a/testing/lisp/test-ox-latex.el
+++ b/testing/lisp/test-ox-latex.el
@@ -154,5 +154,120 @@ Column & Column \\\\
(search-forward
"\\href{https://orgmode.org/worg/images/orgmode/org-mode-unicorn.svg}{\\includegraphics[width=.9\\linewidth]{/wallpaper.png}}";))))
+(ert-deftest test-ox-latex/num-t ()
+ "Test toc treatment for fixed num:t"
+ (org-test-with-exported-text
+ 'latex
+ "#+TITLE: num: fix
+#+OPTIONS: toc:t H:3 num:t
+
+* Section
+
+** Subsection 1
+:PROPERTIES:
+:UNNUMBERED: t
+:END:
+is suppressed
+** Subsection 2
+:PROPERTIES:
+:UNNUMBERED: toc
+:END:
+
+** Subsection 3
+:PROPERTIES:
+:UNNUMBERED: toc
+:ALT_TITLE: Alternative
+:END:
+
+* Section 2
+:PROPERTIES:
+:ALT_TITLE: SECTION 2
+:END:
+"
+ (goto-char (point-min))
+ (should
+ (search-forward "\\begin{document}
+
+\\maketitle
+\\tableofcontents
+
+\\section{Section}
+\\label{"))
+ (should (search-forward "}
+
+\\subsection*{Subsection 1}
+\\label{"))
+ (should (search-forward "}
+is suppressed
+\\subsection*{Subsection 2}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{subsection}{Subsection 2}
+\\subsection*{Subsection 3}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{subsection}{Alternative}
+\\section[SECTION 2]{Section 2}
+\\label{"))
+ (should (search-forward "}
+\\end{document}"))))
+
+(ert-deftest test-ox-latex/new-toc-as-org ()
+ "test toc treatment with `org-latex-toc-include-unnumbered-style' set to `t'"
+ (let ((org-latex-toc-include-unnumbered-style t))
+ (org-test-with-exported-text
+ 'latex
+ "#+TITLE: num: fix
+#+OPTIONS: toc:t H:3 num:nil
+
+* Section
+
+** Subsection 1
+
+** Subsection 2
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+is suppressed
+
+** Subsection 3
+:PROPERTIES:
+:ALT_TITLE: Alternative
+:END:
+
+* Section 2
+:PROPERTIES:
+:ALT_TITLE: SECTION 2
+:END:
+"
+ (goto-char (point-min))
+ (should (search-forward "\\begin{document}
+
+\\maketitle
+\\tableofcontents
+
+\\section*{Section}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{section}{Section}
+
+\\subsection*{Subsection 1}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{subsection}{Subsection 1}
+
+\\subsection*{Subsection 2}
+\\label{"))
+ (should (search-forward "}
+is suppressed
+\\subsection*{Subsection 3}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{subsection}{Alternative}
+\\section*{Section 2}
+\\label{"))
+ (should (search-forward "}
+\\addcontentsline{toc}{section}{SECTION 2}")))))
+
(provide 'test-ox-latex)
;;; test-ox-latex.el ends here
--
2.34.1
![https://orgmode.org/worg/images/orgmode/org-mode-unicorn.svg}{\\includegraphics[width=.9\\linewidth]{/wallpaper.png}}"](https://orgmode.org/worg/images/orgmode/org-mode-unicorn.svg}{\\includegraphics[width=.9\\linewidth]{/wallpaper.png}}"){kind=link}