From 1c4fc3979ea26ca93742b16d9c135ec62a8b4d0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= Date: Thu, 22 Aug 2024 12:27:01 +0200 Subject: [PATCH 1/2] ox-texinfo: Add support for custom navigation hierarchies * doc/org-manual.org (Headings and sectioning structure): Describe the new functionality in detail. * etc/ORG-NEWS (Texinfo exports can have custom navigation hierarchies): Inform end users about the new functionality. * lisp/org.el (org-default-properties): Offer the `ALT_TITLE' and `ALT_NAVIGATION' properties for completion. * lisp/ox-texinfo.el (org-texinfo-headline): Use the `ALT_NAVIGATION' property when generating Texinfo notes to set the Next, Previous, and Up pointers of the relevant Texinfo node. * 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 the new functionality to avoid regressions in the future. --- doc/org-manual.org | 23 ++++++++ etc/ORG-NEWS | 7 +++ lisp/org.el | 3 +- lisp/ox-texinfo.el | 5 +- testing/lisp/test-ox-texinfo.el | 99 +++++++++++++++++++++++++++++++++ 5 files changed, 135 insertions(+), 2 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 9365c66b1..9b53c13c1 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -15999,6 +15999,29 @@ 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_NAVIGATION}, property +By default, Texinfo automatically sets the /Next/, /Previous/, and +/Up/ pointers, reflecting the hierarchy of your document. If you want +it to reflect a different hierarchy, or no hierarchy at all, set the +=ALT_NAVIGATION= property to a list of at most 3 titles, separated by +commas, to be used for the /Next/, /Previous/, and /Up/ pointers, +respectively. For example: + +#+begin_example +,* Mathematical Logic + :PROPERTIES: + :ALT_TITLE: Logic + :END: + +,* Proposition + :PROPERTIES: + :ALT_NAVIGATION: ,, Logic + :END: + + - /Next/ and /Previous/ disabled. + - /Up/ leads to [[Mathematical Logic]]. +#+end_example + *** Indices :PROPERTIES: :DESCRIPTION: Creating indices. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 392788055..25dd3ae49 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -77,6 +77,13 @@ 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 have custom navigation hierarchies + +You can now alter the Texinfo navigation hierarchy by specifying the +/Next/, /Previous/, and /Up/ pointers in the =ALT_NAVIGATION= +property. 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/org.el b/lisp/org.el index d5c1dcb35..dcd05571e 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -12691,7 +12691,8 @@ but in some other way.") "EXPORT_TITLE" "EXPORT_AUTHOR" "EXPORT_DATE" "UNNUMBERED" "ORDERED" "NOBLOCKING" "COOKIE_DATA" "LOG_INTO_DRAWER" "REPEAT_TO_STATE" "CLOCK_MODELINE_TOTAL" "STYLE" "HTML_CONTAINER_CLASS" - "ORG-IMAGE-ACTUAL-WIDTH") + "ORG-IMAGE-ACTUAL-WIDTH" + "ALT_TITLE" "ALT_NAVIGATION") "Some properties that are used by Org mode for various purposes. Being in this list makes sure that they are offered for completion.") diff --git a/lisp/ox-texinfo.el b/lisp/ox-texinfo.el index 6adee9fca..43fdf27ae 100644 --- a/lisp/ox-texinfo.el +++ b/lisp/ox-texinfo.el @@ -1102,6 +1102,7 @@ holding contextual information." (full-text (funcall (plist-get info :texinfo-format-headline-function) todo todo-type priority text tags)) + (navigation (org-element-property :ALT_NAVIGATION headline)) (contents (concat "\n" (if (org-string-nw-p contents) (concat "\n" contents) "") @@ -1118,7 +1119,9 @@ 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) + (format (if notoc? "@anchor{%s}" "@node %s") node) + (if navigation (concat "," navigation) "") + "\n" (format command full-text) contents)))))) diff --git a/testing/lisp/test-ox-texinfo.el b/testing/lisp/test-ox-texinfo.el index b16a344e7..352df378f 100644 --- a/testing/lisp/test-ox-texinfo.el +++ b/testing/lisp/test-ox-texinfo.el @@ -345,5 +345,104 @@ 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)) + (search-forward "@node Title 2")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/all-directions () + "Test alternative navigation in all directions." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NAVIGATION: Next,Previous,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)) + (search-forward "@node Title,Next,Previous,Up")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/one-direction () + "Test alternative navigation in only one direction." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NAVIGATION: ,, 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)) + (search-forward "@node Title,,, Up")))))) + +(ert-deftest test-ox-texinfo/alt-navigation/no-directions () + "Test alternative navigation with all directions disabled." + (should + (org-test-with-temp-text + (string-join + (list "* Title" + ":PROPERTIES:" + ":ALT_NAVIGATION: ,,," + ":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)) + (search-forward "@node Title,,,")))))) + +(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_NAVIGATION: Next,Previous,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)) + (search-forward "@node Title 2,Next,Previous,Up")))))) + (provide 'test-ox-texinfo) ;;; test-ox-texinfo.el end here -- 2.39.3 (Apple Git-146)