From 7a8692ec67360414143524d49a098fd99fce03a3 Mon Sep 17 00:00:00 2001 From: Rudolf Adamkovic Date: Sat, 24 Aug 2024 21:35:44 +0200 Subject: [PATCH 1/3] ox-texinfo: Support alternative navigation * doc/org-manual.org (Headings and sectioning structure): Describe the new feature. * etc/ORG-NEWS (Texinfo exports can use alternative navigation): Announce the new feature. * lisp/ox-texinfo.el (org-texinfo-headline, org-texinfo-template): Use the `ALT_NEXT', `ALT_PREVIOUS', and `ALT_UP' Org properties when generating Texinfo @node lines for Next, Previous, and Up pointers. * testing/lisp/test-ox-texinfo.el (test-ox-texinfo/alt-title, test-ox-texinfo/alt-navigation/all-directions, test-ox-texinfo/alt-navigation/one-direction, test-ox-texinfo/alt-navigation/no-directions, test-ox-texinfo/alt-navigation/with-alt-title, test-ox-texinfo/alt-navigation/top/default, test-ox-texinfo/alt-navigation/top/default): Test the new feature to avoid regressions in the future. --- doc/org-manual.org | 20 +++ etc/ORG-NEWS | 8 + lisp/ox-texinfo.el | 103 +++++++----- testing/lisp/test-ox-texinfo.el | 290 ++++++++++++++++++++++++++++++++ 4 files changed, 382 insertions(+), 39 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 9365c66b1..049454624 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -15999,6 +15999,26 @@ the node in which a reader enters an Info manual. As such, it is expected not to appear in printed output generated from the =.texi= file. See [[info:texinfo::The Top Node]], for more information. +#+cindex: @samp{ALT_NEXT}, property +#+cindex: @samp{ALT_PREVIOUS}, property +#+cindex: @samp{ALT_UP}, property +Texinfo automatically sets the /Next/, /Previous/, and /Up/ pointers, +reflecting the hierarchy of your document. If you want to use a +different hierarchy, or no hierarchy at all, set the =ALT_NEXT=, +=ALT_PREVIOUS=, and =ALT_UP= properties to the relevant titles. For +example: + +#+begin_example +,* Mathematical Logic + :PROPERTIES: + :ALT_TITLE: Logic + :END: +,* Proposition + :PROPERTIES: + :ALT_UP: Logic + :END: +#+end_example + *** Indices :PROPERTIES: :DESCRIPTION: Creating indices. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 392788055..49dafcd5d 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -77,6 +77,14 @@ You can now create links to =shortdoc= documentation groups for Emacs Lisp functions (see =M-x shortdoc-display-group=). Requires Emacs 28 or newer. +*** Texinfo exports can use alternative navigation + +You can now alter the Texinfo navigation hierarchy by specifying the +/Next/, /Previous/, and /Up/ pointers in the =ALT_NEXT=, +=ALT_PREVIOUS=, and =ALT_UP= properties, respectively. For more +information, see "13.14.6 Headings and sectioning structure" section +of the Org manual. + ** New and changed options # Chanes deadling with changing default values of customizations, diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el index 6adee9fca..808dc22f6 100644 --- a/lisp/ox-texinfo.el +++ b/lisp/ox-texinfo.el @@ -512,46 +512,63 @@ INFO is a plist used as a communication channel. See ;; Else use format string. (fmt (format fmt text)))) +(defun org-texinfo--node-line (headline info) + "Return node line for HEADLINE. + +INFO is a plist used as a communication channel." + (let ((next (org-element-property :ALT_NEXT headline)) + (previous (org-element-property :ALT_PREVIOUS headline)) + (up (org-element-property :ALT_UP headline))) + (string-trim-right + (concat (format "@node %s" (org-texinfo--get-node headline info)) + (if (or next previous up) ", ") + (and next (org-texinfo--sanitize-node next)) + (if (or previous up) ", ") + (and previous (org-texinfo--sanitize-node previous)) + (if (or up) ", ") + (and up (org-texinfo--sanitize-node up)))))) + (defun org-texinfo--get-node (datum info) "Return node or anchor associated to DATUM. -DATUM is a headline, a radio-target or a target. INFO is a plist -used as a communication channel. The function guarantees the +DATUM is org-data (root), a headline, a radio-target or a target. INFO +is a plist used as a communication channel. The function guarantees the node or anchor name is unique." - (let ((cache (plist-get info :texinfo-node-cache))) - (or (cdr (assq datum cache)) - (let* ((salt 0) - (basename - (org-texinfo--sanitize-node - (pcase (org-element-type datum) - (`headline - (org-texinfo--sanitize-title - (org-export-get-alt-title datum info) info)) - (`radio-target - (org-export-data (org-element-contents datum) info)) - (`target - (org-element-property :value datum)) - (_ - (or (org-element-property :name datum) - (org-export-get-reference datum info)))))) - (name basename)) - ;; Org exports deeper elements before their parents. If two - ;; node names collide -- e.g., they have the same title -- - ;; within the same hierarchy, the second one would get the - ;; smaller node name. This is counter-intuitive. - ;; Consequently, we ensure that every parent headline gets - ;; its node beforehand. As a recursive operation, this - ;; achieves the desired effect. - (let ((parent (org-element-lineage datum 'headline))) - (when (and parent (not (assq parent cache))) - (org-texinfo--get-node parent info) - (setq cache (plist-get info :texinfo-node-cache)))) - ;; Ensure NAME is unique and not reserved node name "Top", - ;; no matter what case is used. - (while (or (string-equal "Top" (capitalize name)) - (rassoc name cache)) - (setq name (concat basename (format " (%d)" (cl-incf salt))))) - (plist-put info :texinfo-node-cache (cons (cons datum name) cache)) - name)))) + (if (eq (org-element-type datum) 'org-data) "Top" + (let ((cache (plist-get info :texinfo-node-cache))) + (or (cdr (assq datum cache)) + (let* ((salt 0) + (basename + (org-texinfo--sanitize-node + (pcase (org-element-type datum) + (`headline + (org-texinfo--sanitize-title + (org-export-get-alt-title datum info) info)) + (`radio-target + (org-export-data (org-element-contents datum) info)) + (`target + (org-element-property :value datum)) + (_ + (or (org-element-property :name datum) + (org-export-get-reference datum info)))))) + (name basename)) + ;; Org exports deeper elements before their parents. If + ;; two node names collide -- e.g., they have the same + ;; title -- within the same hierarchy, the second one + ;; would get the smaller node name. This is + ;; counter-intuitive. Consequently, we ensure that every + ;; parent headline gets its node beforehand. As a + ;; recursive operation, this achieves the desired effect. + (let ((parent (org-element-lineage datum 'headline))) + (when (and parent (not (assq parent cache))) + (org-texinfo--get-node parent info) + (setq cache (plist-get info :texinfo-node-cache)))) + ;; Ensure NAME is unique and not reserved node name "Top", + ;; no matter what case is used. + (while (or (string-equal "Top" (capitalize name)) + (rassoc name cache)) + (setq name (concat basename (format " (%d)" (cl-incf salt))))) + (plist-put info :texinfo-node-cache (cons (cons datum name) cache)) + name))))) (defun org-texinfo--sanitize-node (title) "Bend string TITLE to node line requirements. @@ -875,7 +892,12 @@ holding export options." ;; Configure Top Node when not for TeX. Also include contents ;; from the first section of the document. "@ifnottex\n" - "@node Top\n" + ;; Top node. + (org-element-map (plist-get info :parse-tree) 'org-data + (lambda (root) + (org-texinfo--node-line root info)) + info t) + "\n" (format "@top %s\n" title) (let* ((first-section (org-element-map (plist-get info :parse-tree) 'section @@ -1118,7 +1140,10 @@ holding contextual information." (concat ;; Even if HEADLINE is using @subheading and al., leave an ;; anchor so cross-references in the Org document still work. - (format (if notoc? "@anchor{%s}\n" "@node %s\n") node) + (if notoc? + (format "@anchor{%s}" node) + (org-texinfo--node-line headline info)) + "\n" (format command full-text) contents)))))) diff --git a/testing/lisp/test-ox-texinfo.el b/testing/lisp/test-ox-texinfo.el index b16a344e7..fb0269649 100644 --- a/testing/lisp/test-ox-texinfo.el +++ b/testing/lisp/test-ox-texinfo.el @@ -345,5 +345,295 @@ body (should-not (org-element-contents section)) (should (eq first-heading (org-element-parent section))))))) + +;;; Alternative title and navigation + +(ert-deftest test-ox-texinfo/alt-title () + "Test alternative titles." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_TITLE: Title 2" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title 2$")))))) + +(ert-deftest test-ox-texinfo/alt-title/sanitized () + "Test sanitized alternative titles." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_TITLE: (Foo:) Bar, baz." + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node \\[Foo) Bar baz$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/next () + "Test alternative navigation to Next nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NEXT: Next" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, Next$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/next/sanitized () + "Test sanitized alternative navigation to Next nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_NEXT: (Foo:) Bar, baz." + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title 1, \\[Foo) Bar baz$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/next/with-previous () + "Test alternative navigation to Next and Previous nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NEXT: Next" + ":ALT_PREVIOUS: Previous" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, Next, Previous$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/next/with-previous-and-up () + "Test alternative navigation to Next, Previous, and Up nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NEXT: Next" + ":ALT_PREVIOUS: Previous" + ":ALT_UP: Up" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, Next, Previous, Up$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/previous () + "Test alternative navigation to Previous nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_PREVIOUS: Previous" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, , Previous$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/previous/sanitized () + "Test sanitized alternative navigation to Previous nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_PREVIOUS: (Foo:) Bar, baz." + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title 1, , \\[Foo) Bar baz$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/previous/with-up () + "Test alternative navigation to Previous and Up nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_PREVIOUS: Previous" + ":ALT_UP: Up" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, , Previous, Up$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/up () + "Test alternative navigation to Up nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_UP: Up" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title, , , Up$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/up/sanitized () + "Test sanitized alternative navigation to Up nodes." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_UP: (Foo:) Bar, baz." + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title 1, , , \\[Foo) Bar baz$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/no-pointers () + "Test alternative navigation with no pointers." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NEXT:" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title,$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/top-node/not-set () + "Test alternative navigation for Top nodes, when not set." + (should + (org-test-with-temp-text "Hello world!" + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Top$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/top-node/set () + "Test alternative navigation for Top nodes, when set." + (should + (org-test-with-temp-text + (string-join + (list ":PROPERTIES:" + ":ALT_NEXT: Next" + ":ALT_PREVIOUS: Previous" + ":ALT_UP: Up" + ":END:" + "#+TITLE: Title" + "* Headline") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Top, Next, Previous, Up$")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/with-alt-title () + "Test alternative navigation combined with alternative titles." + (should + (org-test-with-temp-text + (string-join + (list "* Title 1" + ":PROPERTIES:" + ":ALT_TITLE: Title 2" + ":ALT_UP: Title 3" + ":END:") + "\n") + (let ((export-buffer "*Test Texinfo Export*") + (org-export-show-temporary-export-buffer nil)) + (org-export-to-buffer 'texinfo export-buffer + nil nil nil nil nil + #'texinfo-mode) + (with-current-buffer export-buffer + (goto-char (point-min)) + (re-search-forward "^@node Title 2, , , Title 3$")))))) + (provide 'test-ox-texinfo) ;;; test-ox-texinfo.el end here -- 2.39.3 (Apple Git-146)